Add OIDC examples ✨

Author: RobertoPrevato

oidc/README.md

@@ -0,0 +1,70 @@
+# OIDC Examples
+Working examples of OpenID Connect integrations in BlackSheep applications.
+
+---
+
+This repository contains examples of OpenID Connect integration with three
+identity providers:
+
+- [Auth0](https://auth0.com)
+- [Okta](https://www.okta.com)
+- [Azure Active Directory](https://azure.microsoft.com/en-us/products/active-directory)
+
+## Basic examples (id_token only)
+
+The files whose names start with "basic_" are configured to obtain only
+an `id_token`. This is useful when the same application that integrates with
+OpenID Connect does not need an access token for another API and all it needs
+is to _identify_ users. The values in these files describe real applications
+configured in tenants owned by the owner of this repository.
+
+App registrations for these examples only need to be configured with authentication
+URL `http://localhost:5000/authorization-callback` and enable issuing `id_token`s.
+
+## Running the examples
+
+1. create a Python virtual environment, and activate it
+2. install dependencies `pip install -r requirements.txt`
+3. run one of the basic examples `python basic_auth0.py`
+4. navigate to [http://localhost:5000](http://localhost:5000)
+5. click on the sign-in link, follow the instructions to sign-up / sign-in
+
+:warning: these examples only work with `localhost`!!!
+
+### Azure Active Directory
+
+This example can be tested using any Microsoft account, signing-in in the
+demo app inside the Azure tenant Neoteroi.
+
+![AAD demo](./docs/aad-demo.png)
+
+After sign-in, the application shows user claims.
+
+![AAD demo claims](./docs/aad-demo-claims.png)
+
+### Auth0
+
+This example can be tested by anyone, since the application in Auth0 enable
+creating an account in the Neoteroi account in Auth0.
+
+![Auth0 demo](./docs/auth0-demo.png)
+
+![Auth0 demo with Google](./docs/auth0-demo-with-google.png)
+
+### Okta
+
+This example illustrates navigating to a sign-in page, but cannot be tested
+fully because the Okta account is not configured to enable sign-up.
+
+![Okta demo](./docs/okta-demo.png)
+
+## Examples with scopes (id_token and access_token)
+
+The files whose names start with "scopes_" are configured to obtain, together
+with an `id_token`, an `access_token` for an API. These require secrets which,
+of course, are not exposed in this repository.
+
+App registrations for these examples are slightly more complex, since they
+require configuring an API with scopes. Describing these details is beyond the
+scope of this repository. For more information on this subject, refer to the
+documentation of the identity providers (for example, for [Auth0 here](https://auth0.com/docs/get-started/apis/api-settings))

oidc/basic_aad.py

@@ -0,0 +1,28 @@
+import uvicorn
+from blacksheep.server.application import Application
+from blacksheep.server.authentication.oidc import (
+    OpenIDSettings,
+    use_openid_connect,
+    CookiesTokensStore,
+)
+
+from common.routes import register_routes
+
+app = Application(show_error_details=True)
+
+
+# basic AAD integration that handles only an id_token
+use_openid_connect(
+    app,
+    OpenIDSettings(
+        authority="https://login.microsoftonline.com/b62b317a-19c2-40c0-8650-2d9672324ac4/v2.0/",
+        client_id="499adb65-5e26-459e-bc35-b3e1b5f71a9d",
+    ),
+    tokens_store=CookiesTokensStore(),
+)
+
+register_routes(app)
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="127.0.0.1", port=5000, log_level="debug")

oidc/basic_auth0.py

@@ -0,0 +1,29 @@
+import uvicorn
+from blacksheep.server.application import Application
+from blacksheep.server.authentication.oidc import (
+    OpenIDSettings,
+    use_openid_connect,
+    CookiesTokensStore,
+)
+
+from common.routes import register_routes
+
+app = Application(show_error_details=True)
+
+
+# basic Auth0 integration that handles only an id_token
+use_openid_connect(
+    app,
+    OpenIDSettings(
+        authority="https://neoteroi.eu.auth0.com",
+        client_id="OOGPl4dgG7qKsm2IOWq72QhXV4wsLhbQ",
+        callback_path="/signin-oidc",
+    ),
+    tokens_store=CookiesTokensStore(),
+)
+
+register_routes(app)
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="127.0.0.1", port=5000, log_level="debug")

oidc/basic_okta.py

@@ -0,0 +1,29 @@
+import uvicorn
+from blacksheep.server.application import Application
+from blacksheep.server.authentication.oidc import (
+    OpenIDSettings,
+    use_openid_connect,
+    CookiesTokensStore,
+)
+
+from common.routes import register_routes
+
+app = Application(show_error_details=True)
+
+
+# basic Okta integration that handles only an id_token
+use_openid_connect(
+    app,
+    OpenIDSettings(
+        authority="https://dev-34685660.okta.com",
+        client_id="0oa2gy88qiVyuOClI5d7",
+        callback_path="/authorization-code/callback",
+    ),
+    tokens_store=CookiesTokensStore(),
+)
+
+register_routes(app)
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="127.0.0.1", port=5000, log_level="debug")

oidc/common/__init__.py

@@ -0,0 +1,10 @@
+import logging
+
+from blacksheep.baseapp import get_logger
+from blacksheep.server.authentication.oidc import get_logger as get_oidc_logger
+
+logging.basicConfig(level=logging.DEBUG, format="%(message)s")
+
+for logger in {get_logger(), get_oidc_logger()}:
+    logger.setLevel(logging.DEBUG)
+    logger.addHandler(logging.StreamHandler())

oidc/common/logs.py

@@ -0,0 +1,85 @@
+import jwt
+from textwrap import dedent
+
+from blacksheep.messages import Request
+from blacksheep.server.application import Application
+from blacksheep.server.authorization import allow_anonymous
+from blacksheep.server.responses import html, redirect
+from essentials.json import dumps
+from guardpost.authentication import Identity
+
+
+def _render_access_token(user: Identity) -> str:
+    if not user.access_token:
+        return ""
+
+    # parse without validating the access token
+    # (the id_token was validated upon sign-in!)
+    claims = jwt.decode(user.access_token, options={"verify_signature": False})
+
+    return dedent(
+        f"""
+        <h3>You also have an access token for an API</h3>
+        <p>These are the claims, from your <strong>access_token</strong>:</p>
+        <pre>{dumps(claims, indent=4)}</pre>
+        """
+    )
+
+
+def register_routes(app: Application) -> None:
+    @allow_anonymous()
+    @app.route("/sign-in-error")
+    async def error_handler(request: Request, error: str):
+        if error == "access_denied":
+            # the user declined consents to the app
+            return html("<h1>OK, but you won't be able to use our wonderful app.</h1>")
+        return html(f"<h1>Oh, no! {error}</h1>")
+
+    @app.route("/")
+    async def home(request: Request, user: Identity):
+        host = request.get_first_header(b"Host")
+        if b"localhost" not in host:
+            return redirect("http://localhost:5000/")
+
+        if user.is_authenticated():
+            id_claims = dumps(user.claims, indent=4)
+
+            return html(
+                dedent(
+                    f"""
+                    <!DOCTYPE html>
+                    <html>
+                    <head>
+                    <style>
+                    pre {{
+                        border: 1px dotted darkred;
+                        padding: 1rem;
+                    }}
+                    </style>
+                    </head>
+                    <body>
+                        <h1>Welcome!</h1>
+                        <p>These are your claims, from your <strong>id_token</strong>:</p>
+                        <pre>{id_claims}</pre>
+                        {_render_access_token(user)}
+                    </body>
+                    </html>
+                """
+                )
+            )
+
+        return html(
+            dedent(
+                f"""
+                <!DOCTYPE html>
+                <html>
+                <head>
+                </head>
+                <body>
+                    <h1>You are not authenticated!</h1>
+                    <a href='/sign-in'>Sign in here.</a><br/>
+                </body>
+                </html>
+            """
+            )
+        )

oidc/common/routes.py

@@ -0,0 +1,17 @@
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class Secrets:
+    auth0_client_secret: str
+    okta_client_secret: str
+    aad_client_secret: str
+
+    @classmethod
+    def from_env(cls):
+        return cls(
+            auth0_client_secret=os.environ["AUTH0_CLIENT_SECRET"],
+            okta_client_secret=os.environ["OKTA_CLIENT_SECRET"],
+            aad_client_secret=os.environ["AAD_CLIENT_SECRET"],
+        )