Merge pull request #32 from djpugh/feature/refactor

djpugh · Dec 14, 2020 · 09b2183 · 09b2183
2 parents 1388f9e + b2d5f35
commit 09b2183
Show file tree

Hide file tree

Showing 66 changed files with 1,598 additions and 1,068 deletions.
diff --git a/docs/source/advanced.rst b/docs/source/advanced.rst
@@ -18,7 +18,7 @@ Customising the User Model
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The authentication state user can be processed within the application methods - the ``Depends`` part of the api route returns an
-:class:`~fastapi_aad_auth.oauth.state.AuthenticationState` object - ``auth_state`` in the ``testapp`` (see :ref:`testing`).
+:class:`~fastapi_aad_auth._base.state.AuthenticationState` object - ``auth_state`` in the ``testapp`` (see :ref:`testing`).
 
 .. literalinclude:: ../../tests/testapp/server.py
     :language: python
@@ -28,26 +28,25 @@ The authentication state user can be processed within the application methods -
 
 The associated user is then available at ``auth_state.user``
 
-The :class:`~fastapi_aad_auth.oauth.aad.AADOAuthBackend` object takes a ``user_klass`` argument:
+The :class:`~fastapi_aad_auth.auth.Authenticator` object takes a ``user_klass`` argument:
 
-.. literalinclude:: ../../src/fastapi_aad_auth/oauth/aad.py
+.. literalinclude:: ../../src/fastapi_aad_auth/auth.py
     :language: python
     :linenos:
-    :start-at: class AADOAuthBackend
+    :start-at: class Authenticator
     :end-before: """Initialise
 
 which defaults to the really basic :class:`~fastapi_aad_auth.oauth.state.User` class, but any object with the same 
 interface should work, so you can add e.g. database calls etc. to validate/persist/check the user and any other
 desired behaviours.
 
-You can customise this when initialising the :class:`~fastapi_aad_auth.auth.AADAuth` object by setting
+You can customise this when initialising the :class:`~fastapi_aad_auth.auth.Authenticator` object by setting
 the :class:`~fastapi_aad_auth.config.Config` ``user_klass`` variable (this can also be done by the
-associated environment variable)::
+associated environment variable, or in the argument, which overrides all other settings)::
 
-    from fastapi_aad_auth import AADAuth, Config
+    from fastapi_aad_auth import Authenticator, Config
 
     config = Config()
-    config.user_klass = MyUserClass
 
-    auth = AADAuth(config)
+    auth = Authenticator(config, user_klass=MyUserClass)
 
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -155,7 +155,7 @@
     'repo_name': 'fastapi_aad_auth',
 
     # Visible levels of the global TOC; -1 means unlimited
-    'globaltoc_depth': -1,
+    'globaltoc_depth': 1,
     # If False, expand all TOC entries
     'globaltoc_collapse': False,
     # If True, show hidden TOC entries

diff --git a/docs/source/deprecations.rst b/docs/source/deprecations.rst
@@ -0,0 +1,13 @@
+API Deprecations
+****************
+
+``0.2.0``:
+
+    Refactoring towards a more extensible structure for the Authentication Backend
+     * :class:`fastapi_aad_auth.oauth.state.AuthenticationState` - replaced by :class:`fastapi_aad_auth._base.state.AuthenticationState`
+     * :class:`fastapi_aad_auth.oauth.aad.AADOAuthBackend` - replaced by :class:`fastapi_aad_auth.providers.aad.AADProvider`
+     * :py:attr:`fastapi_aad_auth.config.RoutingConfig.login_path` - replaced by provider based usage of :py:attr:`fastapi_aad_auth.config.RoutingConfig.oauth_base_route`, see :ref:`config-aad-appreg` for how to configure the app registration
+     * :py:attr:`fastapi_aad_auth.config.RoutingConfig.login_redirect_path` - replaced by provider based usage of :py:attr:`fastapi_aad_auth.config.RoutingConfig.oauth_base_route`, see :ref:`config-aad-appreg` for how to configure the app registration
+     * :py:attr:`fastapi_aad_auth.config.Config.aad` - replaced by providers in :py:attr:`fastapi_aad_auth.config.Config.providers`
+     * :class:`fastapi_aad_auth.auth.AADAuth` - replaced by :class:`fastapi_aad_auth.auth.Authenticator`
+     * :py:meth:`fastapi_aad_auth.auth.AADAuth.api_auth_scheme` - replaced by :py:meth:`fastapi_aad_auth._base.backend.BaseOAuthBackend.requires_auth` (includes ``allow_session`` boolean flag)
diff --git a/docs/source/figures/App-Registration-Redirect-URIs.PNG b/docs/source/figures/App-Registration-Redirect-URIs.PNG
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -50,16 +50,23 @@ The repository is open source (MIT Licensed) on |github| `Github <https://github
     Configuration Options <config>
     Basic Usage <usage>
     Advanced Usage <advanced>
+    Deprecations <deprecations>
+
 
 .. toctree::
     :caption: API
-    :maxdepth: 4
+    :maxdepth: 1
 
+    module/fastapi_aad_auth._base
     module/fastapi_aad_auth.auth
     module/fastapi_aad_auth.config
     module/fastapi_aad_auth.errors
+    module/fastapi_aad_auth.mixins
     module/fastapi_aad_auth.oauth
+    module/fastapi_aad_auth.providers
     module/fastapi_aad_auth.ui
+    module/fastapi_aad_auth.utilities
+
 
 .. toctree::
     :caption: Changes and Contributing

diff --git a/docs/source/module/fastapi_aad_auth._base.authenticators.rst b/docs/source/module/fastapi_aad_auth._base.authenticators.rst
@@ -0,0 +1,10 @@
+fastapi_aad_auth._base.authenticators
+*************************************
+
+.. automodule:: fastapi_aad_auth._base.authenticators
+
+.. toctree::
+    :caption: Sub-modules:
+    :maxdepth: 1
+
+    fastapi_aad_auth._base.authenticators.session
diff --git a/docs/source/module/fastapi_aad_auth._base.authenticators.session.rst b/docs/source/module/fastapi_aad_auth._base.authenticators.session.rst
@@ -0,0 +1,5 @@
+fastapi_aad_auth._base.authenticators.session
+*********************************************
+
+.. automodule:: fastapi_aad_auth._base.authenticators.session
+    :members:
diff --git a/docs/source/module/fastapi_aad_auth._base.backend.rst b/docs/source/module/fastapi_aad_auth._base.backend.rst
@@ -0,0 +1,5 @@
+fastapi_aad_auth._base.backend
+******************************
+
+.. automodule:: fastapi_aad_auth._base.backend
+    :members:
diff --git a/docs/source/module/fastapi_aad_auth._base.provider.rst b/docs/source/module/fastapi_aad_auth._base.provider.rst
@@ -0,0 +1,5 @@
+fastapi_aad_auth._base.provider
+*******************************
+
+.. automodule:: fastapi_aad_auth._base.provider
+    :members:
diff --git a/docs/source/module/fastapi_aad_auth._base.rst b/docs/source/module/fastapi_aad_auth._base.rst
@@ -0,0 +1,14 @@
+fastapi_aad_auth._base
+**********************
+
+.. automodule:: fastapi_aad_auth._base
+
+.. toctree::
+    :caption: Sub-modules:
+    :maxdepth: 1
+
+    fastapi_aad_auth._base.backend
+    fastapi_aad_auth._base.provider
+    fastapi_aad_auth._base.authenticators
+    fastapi_aad_auth._base.state
+    fastapi_aad_auth._base.validators
diff --git a/docs/source/module/fastapi_aad_auth._base.state.rst b/docs/source/module/fastapi_aad_auth._base.state.rst
@@ -0,0 +1,5 @@
+fastapi_aad_auth._base.state
+****************************
+
+.. automodule:: fastapi_aad_auth._base.state
+    :members:
diff --git a/docs/source/module/fastapi_aad_auth._base.validators.base.rst b/docs/source/module/fastapi_aad_auth._base.validators.base.rst
@@ -0,0 +1,5 @@
+fastapi_aad_auth._base.validators.base
+**************************************
+
+.. automodule:: fastapi_aad_auth._base.validators.base
+    :members:
diff --git a/docs/source/module/fastapi_aad_auth._base.validators.rst b/docs/source/module/fastapi_aad_auth._base.validators.rst
@@ -0,0 +1,12 @@
+fastapi_aad_auth._base.validators
+*********************************
+
+.. automodule:: fastapi_aad_auth._base.validators
+
+.. toctree::
+    :caption: Sub-modules:
+    :maxdepth: 1
+
+    fastapi_aad_auth._base.validators.base
+    fastapi_aad_auth._base.validators.session
+    fastapi_aad_auth._base.validators.token
diff --git a/docs/source/module/fastapi_aad_auth._base.validators.session.rst b/docs/source/module/fastapi_aad_auth._base.validators.session.rst
@@ -0,0 +1,5 @@
+fastapi_aad_auth._base.validators.session
+*****************************************
+
+.. automodule:: fastapi_aad_auth._base.validators.session
+    :members:
diff --git a/docs/source/module/fastapi_aad_auth._base.validators.token.rst b/docs/source/module/fastapi_aad_auth._base.validators.token.rst
@@ -0,0 +1,5 @@
+fastapi_aad_auth._base.validators.token
+***************************************
+
+.. automodule:: fastapi_aad_auth._base.validators.token
+    :members:
diff --git a/docs/source/module/fastapi_aad_auth.mixins.logging.rst b/docs/source/module/fastapi_aad_auth.mixins.logging.rst
@@ -0,0 +1,5 @@
+fastapi_aad_auth.mixins.logging
+*******************************
+
+.. automodule:: fastapi_aad_auth.mixins.logging
+    :members:
diff --git a/docs/source/module/fastapi_aad_auth.mixins.not_authenticated.rst b/docs/source/module/fastapi_aad_auth.mixins.not_authenticated.rst
@@ -0,0 +1,5 @@
+fastapi_aad_auth.mixins.not_authenticated
+*****************************************
+
+.. automodule:: fastapi_aad_auth.mixins.not_authenticated
+    :members:
diff --git a/docs/source/module/fastapi_aad_auth.mixins.rst b/docs/source/module/fastapi_aad_auth.mixins.rst
@@ -0,0 +1,12 @@
+fastapi_aad_auth.mixins
+***********************
+
+.. automodule:: fastapi_aad_auth.mixins
+    :members:
+
+.. toctree::
+    :caption: Sub-modules:
+    :maxdepth: 1
+
+    fastapi_aad_auth.mixins.logging
+    fastapi_aad_auth.mixins.not_authenticated
diff --git a/docs/source/module/fastapi_aad_auth.oauth._base.rst b/docs/source/module/fastapi_aad_auth.oauth._base.rst
diff --git a/docs/source/module/fastapi_aad_auth.oauth.aad.rst b/docs/source/module/fastapi_aad_auth.oauth.aad.rst
@@ -1,5 +1,5 @@
 fastapi_aad_auth.oauth.aad
 **************************
-  
+
 .. automodule:: fastapi_aad_auth.oauth.aad
-    :members:
+    :members:
diff --git a/docs/source/module/fastapi_aad_auth.oauth.authenticators.rst b/docs/source/module/fastapi_aad_auth.oauth.authenticators.rst
diff --git a/docs/source/module/fastapi_aad_auth.oauth.authenticators.session.rst b/docs/source/module/fastapi_aad_auth.oauth.authenticators.session.rst
diff --git a/docs/source/module/fastapi_aad_auth.oauth.rst b/docs/source/module/fastapi_aad_auth.oauth.rst
@@ -7,8 +7,5 @@ fastapi_aad_auth.oauth
     :caption: Sub-modules:
     :maxdepth: 1
 
-    fastapi_aad_auth.oauth._base
     fastapi_aad_auth.oauth.aad
-    fastapi_aad_auth.oauth.authenticators
     fastapi_aad_auth.oauth.state
-    fastapi_aad_auth.oauth.validators
diff --git a/docs/source/module/fastapi_aad_auth.oauth.state.rst b/docs/source/module/fastapi_aad_auth.oauth.state.rst
@@ -1,5 +1,5 @@
 fastapi_aad_auth.oauth.state
 ****************************
-  
+
 .. automodule:: fastapi_aad_auth.oauth.state
-    :members:
+    :members:
diff --git a/docs/source/module/fastapi_aad_auth.oauth.validators.rst b/docs/source/module/fastapi_aad_auth.oauth.validators.rst
diff --git a/docs/source/module/fastapi_aad_auth.oauth.validators.session.rst b/docs/source/module/fastapi_aad_auth.oauth.validators.session.rst
diff --git a/docs/source/module/fastapi_aad_auth.oauth.validators.token.rst b/docs/source/module/fastapi_aad_auth.oauth.validators.token.rst
diff --git a/docs/source/module/fastapi_aad_auth.providers.aad.rst b/docs/source/module/fastapi_aad_auth.providers.aad.rst
@@ -0,0 +1,5 @@
+fastapi_aad_auth.providers.aad
+******************************
+
+.. automodule:: fastapi_aad_auth.providers.aad
+    :members:
diff --git a/docs/source/module/fastapi_aad_auth.providers.rst b/docs/source/module/fastapi_aad_auth.providers.rst
@@ -0,0 +1,11 @@
+fastapi_aad_auth.providers
+**************************
+
+.. automodule:: fastapi_aad_auth.providers
+    :members:
+
+.. toctree::
+    :caption: Sub-modules:
+    :maxdepth: 1
+
+    fastapi_aad_auth.providers.aad
diff --git a/docs/source/module/fastapi_aad_auth.utilities.logging.rst b/docs/source/module/fastapi_aad_auth.utilities.logging.rst
@@ -0,0 +1,5 @@
+fastapi_aad_auth.utilities.logging
+**********************************
+
+.. automodule:: fastapi_aad_auth.utilities.logging
+    :members:
diff --git a/docs/source/module/fastapi_aad_auth.utilities.rst b/docs/source/module/fastapi_aad_auth.utilities.rst
@@ -0,0 +1,12 @@
+fastapi_aad_auth.utilities
+**************************
+
+.. automodule:: fastapi_aad_auth.utilities
+    :members:
+
+.. toctree::
+    :caption: Sub-modules:
+    :maxdepth: 1
+
+    fastapi_aad_auth.utilities.logging
+    fastapi_aad_auth.utilities.urls
diff --git a/docs/source/module/fastapi_aad_auth.utilities.urls.rst b/docs/source/module/fastapi_aad_auth.utilities.urls.rst
@@ -0,0 +1,5 @@
+fastapi_aad_auth.utilities.urls
+*******************************
+
+.. automodule:: fastapi_aad_auth.utilities.urls
+    :members:
diff --git a/docs/source/usage.rst b/docs/source/usage.rst
@@ -25,11 +25,16 @@ e.g. for local development::
 
 Configure a web platform for the UI based redirection (or whatever else is set in the config for the redirect path)::
 
-    https://<hostname>/login/oauth/redirect
+    https://<hostname>/oauth/aad/redirect
 
 e.g. for local development::
     
-    http://localhost:8000/login/oauth/redirect
+    http://localhost:8000/oauth/aad/redirect
+
+.. warning::
+    This is new behaviour that will be the default for version ``0.2.0``. To enable this now, you need to set the
+    :class:`~fastapi_aad_auth.config.RoutingConfig` ``login_path`` and ``login_redirect_path`` variables to the empty string or ``None``
+
 
 Youu also need to decide whether the application is multi-tenant or single-tenant
 
@@ -41,14 +46,14 @@ Youu also need to decide whether the application is multi-tenant or single-tenan
 On the "Expose an API tab", you need to set the Application ID URI
 
 .. figure:: figures/App-Registration-App-ID.PNG
-   :alt: Overview of redirect URI configuration for local testing
+   :alt: Overview of app id URI
 
    An example configuration for api Scopes for testing an application
 
 and add scopes as configured for the application (e.g. the default ``openid`` scope is needed)
 
 .. figure:: figures/App-Registration-Scopes.PNG
-   :alt: Overview of redirect URI configuration for local testing
+   :alt: Overview of app scopes
 
    An example configuration for api Scopes for testing an application
 
@@ -103,7 +108,7 @@ You can use it for fastapi routes::
     router = APIRouter()
 
     @router.get('/hello')
-    async def hello_world(auth_state: AuthenticationState =D epends(auth_provider.api_auth_scheme)):
+    async def hello_world(auth_state: AuthenticationState =D epends(auth_provider.auth_backend.requires_auth(allow_session=True))):
         print(auth_state)
         return {'hello': 'world'}
 
@@ -124,14 +129,7 @@ This middleware will set the request.user object and request.credentials object:
         return PlainTextResponse(f'Hello, you')
 
 
-You can set the swagger_ui_init_oauth using auth_provider.api_auth_scheme.init_oauth::
-
-    from fastapi import FastAPI
-    app = FastAPI(...
-                  swagger_ui_init_oauth=auth_provider.api_auth_scheme.init_oauth)
-
-
-To add the required middleware to the fastapi app use::
+The :class:``fastapi.FastAPI`` ``swagger_ui_init_oauth`` variable is set automatically, along with the routing and required middleware using::
 
     auth_provider.configure_app(app)
 

diff --git a/src/fastapi_aad_auth/__init__.py b/src/fastapi_aad_auth/__init__.py
@@ -1,6 +1,7 @@
-from fastapi_aad_auth.auth import AADAuth  # noqa F401
+from fastapi_aad_auth.auth import Authenticator  # noqa F401
 from fastapi_aad_auth.config import Config  # noqa F401
-from fastapi_aad_auth.oauth import AuthenticationState  # noqa F401
-from ._version import get_versions
+from fastapi_aad_auth._base.state import AuthenticationState  # noqa F401
+from fastapi_aad_auth._version import get_versions
+
 __version__ = get_versions()['version']
 del get_versions
diff --git a/src/fastapi_aad_auth/_base/__init__.py b/src/fastapi_aad_auth/_base/__init__.py