fixed test-cov and added sample for authentication with auth handlers

Author: eadwinCode

ellar/auth/guard.py

@@ -3,6 +3,9 @@
 import starlette.status
 from ellar.common import GuardCanActivate, IExecutionContext, constants
 
+if t.TYPE_CHECKING:  # pragma: no cover
+    from ellar.common.routing import RouteOperation
+
 
 class AuthenticatedRequiredGuard(GuardCanActivate):
     status_code = starlette.status.HTTP_401_UNAUTHORIZED
@@ -16,9 +19,16 @@ def __init__(
         self.openapi_scope = openapi_scope or []
         self.reflector = Reflector()
 
-    def openapi_security_scheme(self) -> t.Dict:
+    def openapi_security_scheme(
+        self, route: t.Optional["RouteOperation"] = None
+    ) -> t.Dict:
         # this will only add security scope to the applied controller or route function
-        if self.authentication_scheme:
+        skip_auth: t.Any = False
+        if route:
+            skip_auth = self.reflector.get_all_and_override(
+                constants.SKIP_AUTH, route.endpoint, route.get_controller_type()
+            )
+        if not skip_auth and self.authentication_scheme:
             return {self.authentication_scheme: {}}
 
         return {}

ellar/auth/handlers/schemes/base.py

@@ -12,6 +12,7 @@
 from starlette.status import HTTP_401_UNAUTHORIZED
 
 if t.TYPE_CHECKING:  # pragma: no cover
+    from ellar.common.routing import RouteOperation
     from ellar.core.connection import HTTPConnection
 
 
@@ -36,7 +37,9 @@ async def _authentication_check(
 
     @classmethod
     @abstractmethod
-    def openapi_security_scheme(cls) -> t.Dict:
+    def openapi_security_scheme(
+        cls, route: t.Optional["RouteOperation"] = None
+    ) -> t.Dict:
         """Override and provide OPENAPI Security Scheme"""
 
     async def run_authentication_check(self, context: IHostContext) -> t.Any:
@@ -95,7 +98,9 @@ async def authentication_handler(
         pass  # pragma: no cover
 
     @classmethod
-    def openapi_security_scheme(cls) -> t.Dict:
+    def openapi_security_scheme(
+        cls, route: t.Optional["RouteOperation"] = None
+    ) -> t.Dict:
         assert cls.openapi_in, "openapi_in is required"
         return {
             cls.openapi_name
@@ -143,7 +148,9 @@ def _get_credentials(
         pass  # pragma: no cover
 
     @classmethod
-    def openapi_security_scheme(cls) -> t.Dict:
+    def openapi_security_scheme(
+        cls, route: t.Optional["RouteOperation"] = None
+    ) -> t.Dict:
         assert cls.scheme, "openapi_scheme is required"
         return {
             cls.openapi_name

ellar/auth/handlers/schemes/http.py

@@ -12,6 +12,7 @@
 from .base import BaseHttpAuth
 
 if t.TYPE_CHECKING:  # pragma: no cover
+    from ellar.common.routing import RouteOperation
     from ellar.core.connection import HTTPConnection
 
 
@@ -22,8 +23,10 @@ class HttpBearerAuth(BaseHttpAuth, ABC):
     header: str = "Authorization"
 
     @classmethod
-    def openapi_security_scheme(cls) -> t.Dict:
-        scheme = super().openapi_security_scheme()
+    def openapi_security_scheme(
+        cls, route: t.Optional["RouteOperation"] = None
+    ) -> t.Dict:
+        scheme = super().openapi_security_scheme(route)
         scheme[cls.openapi_name or cls.__name__].update(
             bearerFormat=cls.openapi_bearer_format
         )

ellar/openapi/route_doc_models.py

@@ -200,7 +200,7 @@ def _get_openapi_security_scheme(
         for item in self.guards:
             if not hasattr(item, "openapi_security_scheme"):
                 continue
-            security_scheme = item.openapi_security_scheme()
+            security_scheme = item.openapi_security_scheme(self.route)
             security_definitions.update(security_scheme)
 
             keys = list(security_scheme.keys())

examples/01-carapp/carapp/server.py

@@ -5,8 +5,8 @@
 from ellar.openapi import (
     OpenAPIDocumentBuilder,
     OpenAPIDocumentModule,
-    ReDocDocumentGenerator,
-    SwaggerDocumentGenerator,
+    ReDocsUI,
+    SwaggerUI,
 )
 
 from .root_module import ApplicationModule
@@ -25,7 +25,7 @@
 
 document = document_builder.build_document(application)
 module = OpenAPIDocumentModule.setup(
-    document_generator=[SwaggerDocumentGenerator(), ReDocDocumentGenerator()],
+    docs_ui=[ReDocsUI(), SwaggerUI()],
     document=document,
     guards=[],
 )

examples/02-socketio-app/socketio_app/server.py

@@ -3,7 +3,7 @@
 from ellar.common.constants import ELLAR_CONFIG_MODULE
 from ellar.core.factory import AppFactory
 
-# from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder, SwaggerDocumentGenerator
+# from ellar.openapi import OpenAPIDocumentModule, OpenAPIDocumentBuilder, SwaggerUI
 from .root_module import ApplicationModule
 
 application = AppFactory.create_from_app_module(
@@ -25,7 +25,7 @@
 # document = document_builder.build_document(application)
 # module = OpenAPIDocumentModule.setup(
 #    document=document,
-#    document_generator=SwaggerDocumentGenerator(),
+#    docs_ui=SwaggerUI(),
 #    guards=[]
 # )
 # application.install_module(module)

examples/03-auth-with-guards/auth_project/auth/controllers.py

@@ -8,23 +8,29 @@ class MyController(ControllerBase):
     def index(self):
         return {'detail': "Welcome Dog's Resources"}
 """
-from ellar.common import Body, Controller, ControllerBase, UseGuards, get, post
+from ellar.common import Body, Controller, ControllerBase, get, post
+from ellar.openapi import ApiTags
 
-from .guards import AllowAnyGuard
-from .schemas import UserCredentials
+from .guards import allow_any
 from .services import AuthService
 
 
-@Controller("/auth")
+@Controller
+@ApiTags(name="Authentication", description="User Authentication Endpoints")
 class AuthController(ControllerBase):
     def __init__(self, auth_service: AuthService) -> None:
         self.auth_service = auth_service
 
-    @post("/sign-in")
-    @UseGuards(AllowAnyGuard)
-    async def sign_in(self, payload: UserCredentials = Body()):
-        return await self.auth_service.sign_in(payload)
+    @post("/login")
+    @allow_any()
+    async def sign_in(self, username: Body[str], password: Body[str]):
+        return await self.auth_service.sign_in(username=username, password=password)
 
     @get("/profile")
-    def get_profile(self):
+    async def get_profile(self):
         return self.context.user
+
+    @allow_any()
+    @post("/refresh")
+    async def refresh_token(self, payload: str = Body(embed=True)):
+        return await self.auth_service.refresh_token(payload)

examples/03-auth-with-guards/auth_project/auth/guards.py

@@ -1,17 +1,28 @@
 import typing as t
 
 from ellar.auth import UserIdentity
-from ellar.common import GuardCanActivate, IExecutionContext
+from ellar.common import (
+    GuardCanActivate,
+    IExecutionContext,
+    constants,
+    logger,
+    set_metadata,
+)
 from ellar.common.serializer.guard import (
     HTTPAuthorizationCredentials,
-    HTTPBasicCredentials,
 )
 from ellar.core.guards import GuardHttpBearerAuth
 from ellar.di import injectable
 from ellar_jwt import JWTService
 
-if t.TYPE_CHECKING:
-    from ellar.core import HTTPConnection
+
+def allow_any() -> t.Callable:
+    return set_metadata(constants.GUARDS_KEY, [AllowAny()])
+
+
+class AllowAny(GuardCanActivate):
+    async def can_activate(self, context: IExecutionContext) -> bool:
+        return True
 
 
 @injectable
@@ -21,17 +32,12 @@ def __init__(self, jwt_service: JWTService) -> None:
 
     async def authentication_handler(
         self,
-        connection: "HTTPConnection",
-        credentials: t.Union[HTTPBasicCredentials, HTTPAuthorizationCredentials],
+        context: IExecutionContext,
+        credentials: HTTPAuthorizationCredentials,
     ) -> t.Optional[t.Any]:
         try:
             data = await self.jwt_service.decode_async(credentials.credentials)
-            return UserIdentity(auth_type="bearer", **dict(data))
-        except Exception:
+            return UserIdentity(auth_type="bearer", **data)
+        except Exception as ex:
+            logger.logger.error(f"[AuthGuard] Exception: {ex}")
             self.raise_exception()
-
-
-@injectable
-class AllowAnyGuard(GuardCanActivate):
-    async def can_activate(self, context: IExecutionContext) -> bool:
-        return True

examples/03-auth-with-guards/auth_project/auth/guards_case_2.py

@@ -0,0 +1,43 @@
+import typing as t
+
+from ellar.auth import UserIdentity
+from ellar.common import IExecutionContext, logger, set_metadata
+from ellar.common.serializer.guard import (
+    HTTPAuthorizationCredentials,
+)
+from ellar.core import Reflector
+from ellar.core.guards import GuardHttpBearerAuth
+from ellar.di import injectable
+from ellar_jwt import JWTService
+
+IS_ANONYMOUS = "is_anonymous"
+
+
+def allow_any() -> t.Callable:
+    return set_metadata(IS_ANONYMOUS, True)
+
+
+@injectable
+class AuthGuard(GuardHttpBearerAuth):
+    def __init__(self, jwt_service: JWTService, reflector: Reflector) -> None:
+        self.jwt_service = jwt_service
+        self.reflector = reflector
+
+    async def authentication_handler(
+        self,
+        context: IExecutionContext,
+        credentials: HTTPAuthorizationCredentials,
+    ) -> t.Optional[t.Any]:
+        is_anonymous = self.reflector.get_all_and_override(
+            IS_ANONYMOUS, context.get_handler(), context.get_class()
+        )
+
+        if is_anonymous:
+            return True
+
+        try:
+            data = await self.jwt_service.decode_async(credentials.credentials)
+            return UserIdentity(auth_type=self.scheme, **data)
+        except Exception as ex:
+            logger.logger.error(f"[AuthGuard] Exception: {ex}")
+            self.raise_exception()

examples/03-auth-with-guards/auth_project/auth/module.py

@@ -17,23 +17,30 @@ def register_providers(self, container: Container) -> None:
         pass
 
 """
-from ellar.common import Module
+from datetime import timedelta
+
+from ellar.common import GlobalGuard, Module
 from ellar.core import ModuleBase
-from ellar.di import Container
+from ellar.di import ProviderConfig
+from ellar_jwt import JWTModule
 
+from ..users.module import UsersModule
 from .controllers import AuthController
+from .guards import AuthGuard
 from .services import AuthService
 
 
 @Module(
+    modules=[
+        UsersModule,
+        JWTModule.setup(
+            signing_secret_key="my_poor_secret_key_lol", lifetime=timedelta(minutes=5)
+        ),
+    ],
     controllers=[AuthController],
-    providers=[AuthService],
-    routers=[],
+    providers=[AuthService, ProviderConfig(GlobalGuard, use_class=AuthGuard)],
 )
 class AuthModule(ModuleBase):
     """
     Auth Module
     """
-
-    def register_providers(self, container: Container) -> None:
-        """for more complicated provider registrations, use container.register_instance(...)"""