docs: update to reflect changes in interface

Author: samedii

README.md

@@ -50,6 +50,11 @@ pip install fastapi-oidc
 
 ## Usage
 
+See this example for how to use `docker-compose` to set up authentication with
+fastapi-oidc + keycloak.
+
+### Standard usage
+
 ```python3
 from typing import Optional
 
@@ -72,7 +77,12 @@ auth = Auth(
 app = FastAPI(
     title="Example",
     version="dev",
-    dependencies=[Depends(auth.implicit_scheme)],  # multiple schemes available
+    dependencies=[Depends(auth.implicit_scheme)],
+    # multiple available schemes:
+    # - oidc_scheme (displays all schemes supported by the auth server in docs)
+    # - password_scheme
+    # - implicit_scheme
+    # - authcode_scheme
 )
 
 @app.get("/protected")
@@ -90,12 +100,8 @@ class MyAuthenticatedUser(IDToken):
     custom_field: str
     custom_default: float = 3.14
 
-
-app = FastAPI()
-
-authenticate_user = get_auth(...)
-
-@app.get("/protected")
-def protected(user: MyAuthenticatedUser = Depends(authenticate_user)):
-    return {"Hello": "World", "custom_field": user.custom_field}
+auth = Auth(
+    ...,
+    idtoken_model=MyAuthenticatedUser,
+)
 ```

docs/index.rst

@@ -46,25 +46,38 @@ Basic configuration for verifying OIDC tokens.
 
 .. code-block:: python3
 
+   from typing import Optional
+
    from fastapi import Depends
    from fastapi import FastAPI
+   from fastapi import Security
+   from fastapi import status
+
+   from fastapi_oidc import Auth
+   from fastapi_oidc import KeycloakIDToken
+
+   auth = Auth(
+      openid_connect_url="http://localhost:8080/auth/realms/my-realm/.well-known/openid-configuration",
+      issuer="http://localhost:8080/auth/realms/my-realm",  # optional, verification only
+      client_id="my-client",  # optional, verification only
+      scopes=["email"],  # optional, verification only
+      idtoken_model=KeycloakIDToken,  # optional, verification only
+   )
 
-   from fastapi_oidc import IDToken
-   from fastapi_oidc import get_auth
-
-
-   app = FastAPI()
-
-   authenticate_user = get_auth(
-      openid_connect_url="https://dev-123456.okta.com/.well-known/openid-configuration",
-      issuer="dev-126594.okta.com",  # optional, verification only
-      audience="https://yourapi.url.com/api",  # optional, verification only
-      signature_cache_ttl=3600,  # optional
+   app = FastAPI(
+      title="Example",
+      version="dev",
+      dependencies=[Depends(auth.implicit_scheme)],
+      # multiple available schemes:
+      # - oidc_scheme (displays all schemes supported by the auth server in docs)
+      # - password_scheme
+      # - implicit_scheme
+      # - authcode_scheme
    )
 
    @app.get("/protected")
-   def protected(id_token: IDToken = Depends(authenticate_user)):
-      return {"Hello": "World", "user_email": id_token.email}
+   def protected(id_token: KeycloakIDToken = Security(auth.required)):
+      return dict(message=f"You are {id_token.email}")
 
 
 API Reference

example/__init__.py

@@ -1,19 +1,18 @@
 # -*- coding: utf-8 -*-
 """
-Module for validating Open ID Connect ID Tokens.
+Module for validating Open ID Connect tokens.
 
 Usage
 =====
 
 .. code-block:: python3
 
     # This assumes you've already configured get_auth in your_app.py
-    from your_app.auth import authenticate_user
+    from your_app.auth import auth
 
     @app.get("/auth")
-    def test_auth(authenticated_user: AuthenticatedUser = Depends(authenticate_user)):
-        name = authenticated_user.preferred_username
-        return f"Hello {name}"
+    def test_auth(authenticated_user: IDToken = Depends(auth.required)):
+        return f"Hello {authenticated_user.preferred_username}"
 """
 
 from typing import List
@@ -65,8 +64,8 @@ def __init__(
             issuer (URL): (Optional) The issuer URL from your auth server.
             client_id (str): (Optional) The client_id configured by your auth server.
             scopes (Dict[str, str]): (Optional) A dictionary of scopes and their descriptions.
-            signature_cache_ttl (int): How many seconds your app should cache the
-                authorization server's public signatures.
+            signature_cache_ttl (int): (Optional) How many seconds your app should
+                cache the authorization server's public signatures.
             idtoken_model (Type): (Optional) The model to use for validating the ID Token.
 
         Raises:
@@ -123,7 +122,7 @@ def required(
             HTTPBearer()
         ),
     ) -> IDToken:
-        """Validate and parse OIDC ID token against issuer in config.
+        """Validate and parse OIDC ID token against configuration.
         Note this function caches the signatures and algorithms of the issuing
         server for signature_cache_ttl seconds.
 
@@ -157,7 +156,7 @@ def optional(
             HTTPBearer(auto_error=False)
         ),
     ) -> Optional[IDToken]:
-        """Optionally validate and parse OIDC ID token against issuer in config.
+        """Optionally validate and parse OIDC ID token against configuration.
         Will not raise if the user is not authenticated. Note this function
         caches the signatures and algorithms of the issuing server for
         signature_cache_ttl seconds.
@@ -186,7 +185,7 @@ def authenticate_user(
         authorization_credentials: Optional[HTTPAuthorizationCredentials],
         auto_error: bool,
     ) -> Optional[IDToken]:
-        """Validate and parse OIDC ID token against issuer in config.
+        """Validate and parse OIDC ID token against against configuration.
         Note this function caches the signatures and algorithms of the issuing server
         for signature_cache_ttl seconds.
 

example/main.py

@@ -37,4 +37,4 @@ build-backend = "poetry.masonry.api"
 profile = "black"
 force_single_line = "True"
 known_first_party = []
-known_third_party = ["cachetools", "cryptography", "fastapi", "jose", "jwt", "pydantic", "pytest", "requests", "starlette", "uvicorn"]
+known_third_party = ["cachetools", "cryptography", "fastapi", "jose", "jwt", "pydantic", "pytest", "requests"]

fastapi_oidc/auth.py

@@ -29,7 +29,6 @@ def test__authenticate_user(
     assert id_token.aud == config_w_aud["client_id"]
 
 
-# Ensure that when no audience is supplied, that the audience defaults to client ID
 def test__authenticate_user_no_aud(
     monkeypatch,
     mock_discovery,