Merge pull request #104 from eadwinCode/auth_shield

Authentication and Authorization

Author: eadwinCode

docs/index.md

@@ -25,9 +25,6 @@ Also, Ellar took some concepts from [FastAPI](https://fastapi.tiangolo.com/){tar
 The objective of Ellar is to provide a high level of abstracted interface to the web, along with a well-structured project setup, give room for object-oriented approach to web application design, 
 allow you chose your desired application architecture, and ultimately, deliver speedy handling to requests.
 
-As developers, we never know how big a project can become or evolve over time but following some design patterns and architecture makes it easier to build a more testable and maintainable application.
-
-
 
 ## **Features Summary**
 

docs/stylesheets/extra.css

@@ -1,5 +1,5 @@
 .md-header {
-    background-color: #212529 !important;
+    background-color: #a50a3e !important;
 }
 nav.md-nav--primary ul.md-nav__list {
     text-transform: uppercase;

docs/techniques/caching.md

@@ -413,7 +413,8 @@ For example, lets make `CacheService` available in our route function.
 
 
 ## **Using Cache Decorator**
-Ellar provides a cache decorator that can be used to cache the responses of route functions. The cache decorator can be applied to a route function to automatically cache its response data for a specified amount of time.
+Ellar provides a cache decorator that can be used to cache the responses of route functions. 
+The cache decorator can be applied to a route function to automatically cache its response data for a specified amount of time.
 
 The cache decorator takes the following arguments:
 
@@ -423,25 +424,30 @@ The cache decorator takes the following arguments:
 - `backend` (optional): the name of the cache backend to use for storing the cached data. By default, the `default` cache backend is used.
 - `make_key_callback` (optional): a callback function that can be used to generate a custom cache key. This function takes an `IExecutionContext` instance (which contains information about the request context) and key prefix, and should return the custom cache key to use.
 
+!!! info
+    `Cache` Decorator can also be applied to any controller class. 
+    When this is done, all the routes response of that controller will be cached
+
 We can rewrite the above example using `cache` decorator:
 === "Synchronous Route Function"
     ```python
     from ellar.common import get
-    from ellar.cache import cache
+    from ellar.cache import Cache
     ...
     @get('/cache-test')
-    @cache(ttl=300, version='v1', key_prefix='project_name')
+    @Cache(ttl=300, version='v1', key_prefix='project_name')
     def my_route_function(self):
         processed_value = 'some-value'
         return processed_value
     ```
 === "Asynchronous Route Function"
     ```python
-    from ellar.common import get, cache
+    from ellar.common import get
+    from ellar.cache import Cache
 
     ...
     @get('/cache-test')
-    @cache(ttl=300, version='v1', key_prefix='project_name')
+    @Cache(ttl=300, version='v1', key_prefix='project_name')
     async def my_route_function(self):
         processed_value = 'some-value'
         return processed_value
@@ -457,7 +463,7 @@ Here's an example of how to use a custom `make_key_callback` function with the c
 === "Synchronous Route Function"
     ```python
     from ellar.common import get
-    from ellar.cache import cache
+    from ellar.cache import Cache
     from ellar.core import ExecutionContext
     from ellar.common.helper import get_name
 
@@ -467,7 +473,7 @@ Here's an example of how to use a custom `make_key_callback` function with the c
 
     ...
     @get("/my_endpoint")
-    @cache(ttl=60, make_key_callback=make_key_function)
+    @Cache(ttl=60, make_key_callback=make_key_function)
     def my_endpoint(self):
         # Code to generate response data here
         processed_value = 'some-value'
@@ -478,7 +484,7 @@ Here's an example of how to use a custom `make_key_callback` function with the c
 
     ```python
     from ellar.common import get
-    from ellar.cache import cache
+    from ellar.cache import Cache
     from ellar.core import ExecutionContext
     from ellar.common.helper import get_name
 
@@ -488,7 +494,7 @@ Here's an example of how to use a custom `make_key_callback` function with the c
 
     ...
     @get("/my_endpoint")
-    @cache(ttl=60, make_key_callback=make_key_function)
+    @Cache(ttl=60, make_key_callback=make_key_function)
     async def my_endpoint(self):
         # Code to generate response data here
         processed_value = 'some-value'

ellar/auth/__init__.py

@@ -0,0 +1,27 @@
+from .decorators import CheckPolicies
+from .guard import AuthorizationGuard
+from .handlers import BaseAuthenticationHandler
+from .identity import UserIdentity
+from .interfaces import IIdentitySchemes
+from .policy import (
+    BasePolicyHandler,
+    BasePolicyHandlerWithRequirement,
+    RequiredClaimsPolicy,
+    RequiredRolePolicy,
+)
+from .services import AppIdentitySchemes, IdentityAuthenticationService
+
+__all__ = [
+    "CheckPolicies",
+    "AuthorizationGuard",
+    "BaseAuthenticationHandler",
+    "CheckPolicies",
+    "BasePolicyHandler",
+    "BasePolicyHandlerWithRequirement",
+    "IIdentitySchemes",
+    "UserIdentity",
+    "RequiredClaimsPolicy",
+    "RequiredRolePolicy",
+    "AppIdentitySchemes",
+    "IdentityAuthenticationService",
+]

ellar/auth/constants.py

@@ -0,0 +1 @@
+POLICY_KEYS = "controller_and_route_function_policies"

ellar/auth/decorators.py

@@ -0,0 +1,21 @@
+import typing as t
+
+from ellar.common import set_metadata as set_meta
+
+from .constants import POLICY_KEYS
+from .policy import PolicyType
+
+
+def CheckPolicies(*policies: t.Union[str, PolicyType]) -> t.Callable:
+    """
+    ========= CONTROLLER AND ROUTE FUNCTION DECORATOR ==============
+
+    :param policies:
+    :return:
+    """
+
+    def _decorator(target: t.Callable) -> t.Union[t.Callable, t.Any]:
+        set_meta(POLICY_KEYS, list(policies))(target)
+        return target
+
+    return _decorator

ellar/auth/guard.py

@@ -0,0 +1,55 @@
+import typing as t
+from functools import partial
+
+from starlette import status
+
+from ellar.common import APIException, GuardCanActivate, IExecutionContext
+from ellar.di import injectable
+
+from .constants import POLICY_KEYS
+from .policy import BasePolicyHandler, PolicyType
+
+
+@injectable
+class AuthorizationGuard(GuardCanActivate):
+    status_code = status.HTTP_403_FORBIDDEN
+    exception_class = APIException
+
+    __slots__ = ()
+
+    @t.no_type_check
+    def get_route_handler_policy(
+        self, context: IExecutionContext
+    ) -> t.Optional[t.List[t.Union[PolicyType, str]]]:
+        return context.get_app().reflector.get_all_and_override(
+            POLICY_KEYS, context.get_handler(), context.get_class()
+        )
+
+    def _get_policy_instance(
+        self, context: IExecutionContext, policy: t.Union[t.Type, t.Any, str]
+    ) -> t.Union[BasePolicyHandler, t.Any]:
+        if isinstance(policy, type):
+            return context.get_service_provider().get(policy)
+        return policy
+
+    async def can_activate(self, context: IExecutionContext) -> bool:
+        if not context.user.is_authenticated:
+            raise self.exception_class(status_code=401)
+
+        policies = self.get_route_handler_policy(context)
+
+        if not policies:
+            return True
+
+        partial_get_policy_instance = partial(self._get_policy_instance, context)
+
+        for policy in map(partial_get_policy_instance, policies):
+            result = await policy.handle(context)
+
+            if not result:
+                self.raise_exception()
+
+        return True
+
+    def raise_exception(self) -> None:
+        raise self.exception_class(status_code=self.status_code)

ellar/auth/handlers/__init__.py

@@ -0,0 +1,17 @@
+from .api_key import (
+    CookieAPIKeyAuthenticationHandler,
+    HeaderAPIKeyAuthenticationHandler,
+    QueryAPIKeyAuthenticationHandler,
+)
+from .http import HttpBasicAuthenticationHandler, HttpBearerAuthenticationHandler
+from .model import AuthenticationHandlerType, BaseAuthenticationHandler
+
+__all__ = [
+    "AuthenticationHandlerType",
+    "BaseAuthenticationHandler",
+    "HeaderAPIKeyAuthenticationHandler",
+    "QueryAPIKeyAuthenticationHandler",
+    "CookieAPIKeyAuthenticationHandler",
+    "HttpBasicAuthenticationHandler",
+    "HttpBearerAuthenticationHandler",
+]

ellar/auth/handlers/api_key.py

@@ -0,0 +1,23 @@
+from abc import ABC
+
+from .mixin import BaseAuthenticationHandlerMixin
+from .model import BaseAuthenticationHandler
+from .schemes import APIKeyCookie, APIKeyHeader, APIKeyQuery
+
+
+class QueryAPIKeyAuthenticationHandler(
+    BaseAuthenticationHandlerMixin, APIKeyQuery, BaseAuthenticationHandler, ABC
+):
+    scheme: str = "query"
+
+
+class CookieAPIKeyAuthenticationHandler(
+    BaseAuthenticationHandlerMixin, APIKeyCookie, BaseAuthenticationHandler, ABC
+):
+    scheme: str = "cookie"
+
+
+class HeaderAPIKeyAuthenticationHandler(
+    BaseAuthenticationHandlerMixin, APIKeyHeader, BaseAuthenticationHandler, ABC
+):
+    scheme: str = "header"

ellar/auth/handlers/http.py

@@ -0,0 +1,17 @@
+from abc import ABC
+
+from .mixin import BaseAuthenticationHandlerMixin
+from .model import BaseAuthenticationHandler
+from .schemes import HttpBasicAuth, HttpBearerAuth
+
+
+class HttpBearerAuthenticationHandler(
+    BaseAuthenticationHandlerMixin, HttpBearerAuth, BaseAuthenticationHandler, ABC
+):
+    scheme: str = "bearer"
+
+
+class HttpBasicAuthenticationHandler(
+    BaseAuthenticationHandlerMixin, HttpBasicAuth, BaseAuthenticationHandler, ABC
+):
+    scheme: str = "basic"