Return userid from check_permission

aiohttp_security/api.py

@@ -103,18 +103,19 @@ async def check_authorized(request: web.Request) -> str:
 
 
 async def check_permission(request: web.Request, permission: Union[str, enum.Enum],
-                           context: Any = None) -> None:
+                           context: Any = None) -> str:
     """Checker that passes only to authoraised users with given permission.
 
     If user is not authorized - raises HTTPUnauthorized,
     if user is authorized and does not have permission -
     raises HTTPForbidden.
     """
 
-    await check_authorized(request)
+    userid = await check_authorized(request)
     allowed = await permits(request, permission, context)
     if not allowed:
         raise web.HTTPForbidden(reason="User does not have '{}' permission".format(permission))
+    return userid
 
 
 def setup(app: web.Application, identity_policy: AbstractIdentityPolicy,

docs/reference.rst

@@ -86,6 +86,8 @@ Public API functions
 
    :param request:  :class:`aiohttp.web.Request` object.
 
+   :return str: authorized user ID if success
+
    :raise: :class:`aiohttp.web.HTTPUnauthorized` for anonymous users.
 
    :raise: :class:`aiohttp.web.HTTPForbidden` if user is

docs/usage.rst

@@ -64,8 +64,10 @@ The workflow is as follows:
    :func:`authorized_userid` *be invoked* .
 4) If the user tries to access a restricted asset the :func:`permits`
    method is called.  Usually assets are protected using the
-   :func:`check_permission` helper.  This should return True if
-   permission is granted.
+   :func:`check_permission` helper, which raises
+   :class:`aiohttp.web.HTTPUnauthorized` or
+   :class:`aiohttp.web.HTTPForbidden` on failure, and returns the
+   :term:`userid` on success.
 
 The :func:`permits` method is implemented by the developer as part of
 the :class:`AbstractAuthorizationPolicy` and passed to the

tests/test_dict_autz.py

@@ -198,8 +198,8 @@ async def logout(request):
 async def test_check_permission(aiohttp_client):
 
     async def index_read(request):
-        await check_permission(request, 'read')
-        return web.Response()
+        userid = await check_permission(request, 'read')
+        return web.Response(text=userid)
 
     async def index_write(request):
         await check_permission(request, 'write')
@@ -238,6 +238,7 @@ async def logout(request):
     await client.post('/login')
     resp = await client.get('/permission/read')
     assert web.HTTPOk.status_code == resp.status
+    assert "Andrew" == await resp.text()
     resp = await client.get('/permission/write')
     assert web.HTTPOk.status_code == resp.status
     resp = await client.get('/permission/forbid')