✨ Update authentication check endpoint and improve documentation

Author: pcrespov

api/specs/web-server/_auth.py

@@ -153,17 +153,15 @@ async def logout(_body: LogoutBody):
 
 @router.get(
     "/auth:check",
-    operation_id="check_authentication",
     status_code=status.HTTP_204_NO_CONTENT,
     responses={
         status.HTTP_401_UNAUTHORIZED: {
             "model": EnvelopedError,
-            "description": "unauthorized reset due to invalid token code",
         }
     },
 )
 async def check_auth():
-    """checks if user is authenticated in the platform"""
+    """checks whether user request is authenticated"""
 
 
 @router.post(

services/web/server/src/simcore_service_webserver/login/_controller/rest/auth.py

@@ -289,17 +289,18 @@ async def logout(request: web.Request) -> web.Response:
         return response
 
 
-@routes.get(f"/{API_VTAG}/auth:check", name="check_authentication")
+@routes.get(f"/{API_VTAG}/auth:check", name="check_auth")
 @login_required
 async def check_auth(request: web.Request) -> web.Response:
-    # lightweight endpoint for checking if users are authenticated
-    # used primarily by Traefik auth middleware to verify session cookies
+    """Lightweight endpoint for checking if users are authenticated & authorized to this product
 
+    Used primarily by Traefik auth middleware to verify session cookies
+    SEE https://doc.traefik.io/traefik/middlewares/http/forwardauth
+    """
     # NOTE: for future development
     # if database access is added here, services like jupyter-math
     # which load a lot of resources will have a big performance hit
     # consider caching some properties required by this endpoint or rely on Redis
-
     assert request  # nosec
 
     return web.json_response(status=status.HTTP_204_NO_CONTENT)

services/web/server/tests/unit/with_dbs/03/login/test_login_auth.py

@@ -41,6 +41,9 @@
 async def test_check_auth(client: TestClient, logged_user: UserInfoDict):
     assert client.app
 
+    url = client.app.router["check_auth"].url_for()
+    assert url.path == "/v0/auth:check"
+
     response = await client.get("/v0/auth:check")
     await assert_status(response, status.HTTP_204_NO_CONTENT)