refactor!: remove client_id and more transparent name openid_connect_url

samedii · samedii · commit 392eccbd5de6 · 2021-09-13T19:07:00.000+02:00
base_authorization_server_uri is never used on its own and
openid_connect_url is already used by fastapi and says more
about what is going on

BREAKING CHANGE
diff --git a/README.md b/README.md
@@ -18,70 +18,76 @@
 
 ---
 
-:warning: **See [this issue](https://github.com/HarryMWinters/fastapi-oidc/issues/1) for
-simple role-your-own example of checking OIDC tokens.**
+**Documentation**: <a href="https://fastapi-oidc.readthedocs.io/" target="_blank">https://fastapi-oidc.readthedocs.io/</a>
 
-Verify and decrypt 3rd party OIDC ID tokens to protect your
-[fastapi](https://github.com/tiangolo/fastapi) endpoints.
+**Source Code**: <a href="https://github.com/HarryMWinters/fastapi-oidc" target="_blank">https://github.com/HarryMWinters/fastapi-oidc</a>
 
-**Documentation:** [ReadTheDocs](https://fastapi-oidc.readthedocs.io/en/latest/)
+---
+
+Verify and decrypt 3rd party OpenID Connect tokens to protect your
+[FastAPI](https://github.com/tiangolo/fastapi) endpoints.
 
-**Source code:** [Github](https://github.com/HarryMWinters/fastapi-oidc)
+Easily used with authenticators such as:
+- [Keycloak](https://www.keycloak.org/) (open source)
+- [SuperTokens](https://supertokens.io/) (open source)
+- [Auth0](https://auth0.com/)
+- [Okta](https://www.okta.com/products/authentication/)
+
+FastAPI's generated interactive documentation supports the grant flows
+`authorization_code`, `implicit`, `password` and `client_credentials`.
 
 ## Installation
 
-`pip install fastapi-oidc`
+```
+poetry add fastapi-oidc
+```
 
-## Usage
+Or, for the old-timers:
 
-### Verify ID Tokens Issued by Third Party
+```
+pip install fastapi-oidc
+```
 
-This is great if you just want to use something like Okta or google to handle
-your auth. All you need to do is verify the token and then you can extract user ID info
-from it.
+## Usage
 
 ```python3
 from fastapi import Depends
 from fastapi import FastAPI
 
-# Set up our OIDC
 from fastapi_oidc import IDToken
 from fastapi_oidc import get_auth
 
 
+app = FastAPI()
+
 authenticate_user = get_auth(
-    client_id": "0oa1e3pv9opbyq2Gm4x7",
-    "base_authorization_server_uri": "https://dev-126594.okta.com",
-    "issuer": "dev-126594.okta.com",
-    # Audience can be omitted in which case it defaults to client_id
-    "audience": "https://yourapi.url.com/api",  # optional, verification only
-    "signature_cache_ttl": 3600,  # optional
+    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()
-
 @app.get("/protected")
 def protected(id_token: IDToken = Depends(authenticate_user)):
     return {"Hello": "World", "user_email": id_token.email}
 ```
 
-#### Using your own tokens
+### Optional: Custom token validation
 
-The IDToken class will accept any number of extra field but if you want to craft your
-own token class and validation that's accounted for too.
+The IDToken class will accept any number of extra fields but you can also
+validate fields in the token like this:
 
 ```python3
-class CustomIDToken(fastapi_oidc.IDToken):
+class MyAuthenticatedUser(IDToken):
     custom_field: str
     custom_default: float = 3.14
 
 
-authenticate_user = get_auth(**OIDC_config)
-
 app = FastAPI()
 
+authenticate_user = get_auth(...)
 
 @app.get("/protected")
-def protected(id_token: CustomIDToken = Depends(authenticate_user)):
-    return {"Hello": "World", "user_email": id_token.custom_default}
+def protected(user: MyAuthenticatedUser = Depends(authenticate_user)):
+    return {"Hello": "World", "custom_field": user.custom_field}
 ```
diff --git a/docs/index.rst b/docs/index.rst
@@ -23,13 +23,13 @@ Installation
 
 .. code-block:: bash
 
-   pip install fastapi-oidc
+   poetry add fastapi-oidc
    
-Or, if you you're feeling hip...
+Or, for the old-timers:
 
 .. code-block:: bash
 
-   poetry add fastapi-oidc
+   pip install fastapi-oidc
 
 Example
 -------
@@ -41,21 +41,19 @@ Basic configuration for verifying OIDC tokens.
    from fastapi import Depends
    from fastapi import FastAPI
 
-   # Set up our OIDC
    from fastapi_oidc import IDToken
    from fastapi_oidc import get_auth
 
-   OIDC_config = {
-      "client_id": "0oa1e3pv9opbyq2Gm4x7",
-      "base_authorization_server_uri": "https://dev-126594.okta.com",
-      "issuer": "dev-126594.okta.com",
-      "signature_cache_ttl": 3600,
-   }
-
-   authenticate_user: Callable = get_auth(**OIDC_config)
 
    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.get("/protected")
    def protected(id_token: IDToken = Depends(authenticate_user)):
       return {"Hello": "World", "user_email": id_token.email}
@@ -70,13 +68,6 @@ Auth
 .. automodule:: fastapi_oidc.auth
    :members:
 
-
-Discovery
----------
-
-.. automodule:: fastapi_oidc.discovery
-   :members:
-
 Types
 ------------
 .. automodule:: fastapi_oidc.types
diff --git a/fastapi_oidc/auth.py b/fastapi_oidc/auth.py
@@ -32,9 +32,8 @@ def test_auth(authenticated_user: AuthenticatedUser = Depends(authenticate_user)
 
 
 def get_auth(
-    client_id: str,
-    base_authorization_server_uri: str,
-    issuer: str,
+    openid_connect_url: str,
+    issuer: Optional[str] = None,
     audience: Optional[str] = None,
     signature_cache_ttl: int = 3600,
 ) -> Callable[[str], Dict]:
@@ -44,19 +43,13 @@ def get_auth(
     server code. The function it returns should be used to check user credentials.
 
     Args:
-        client_id (str): This string is provided when you register with your resource
-            server.
-        base_authorization_server_uri(URL): Everything before /.wellknow in your auth
-            server URL. I.E. https://dev-123456.okta.com
+        openid_connect_url (URL): URL to the "well known" openid connect config
+            e.g. https://dev-123456.okta.com/.well-known/openid-configuration
         issuer (URL): Same as base_authorization. This is used to generating OpenAPI3.0
             docs which is broken (in OpenAPI/FastAPI) right now.
+        audience (str): (Optional) The audience string configured by your auth server.
         signature_cache_ttl (int): How many seconds your app should cache the
             authorization server's public signatures.
-        audience (str): (Optional) The audience string configured by your auth server.
-            If not set defaults to client_id
-        token_type (IDToken or subclass): (Optional) An optional class to be returned by
-            the authenticate_user function.
-
 
     Returns:
         func: authenticate_user(auth_header: str) -> Dict
@@ -65,9 +58,7 @@ def get_auth(
         Nothing intentional
     """
 
-    oauth2_scheme = OpenIdConnect(
-        openIdConnectUrl=f"{base_authorization_server_uri}/.well-known/openid-configuration"
-    )
+    oauth2_scheme = OpenIdConnect(openIdConnectUrl=openid_connect_url)
 
     discover = discovery.configure(cache_ttl=signature_cache_ttl)
 
@@ -87,7 +78,7 @@ def authenticate_user(auth_header: str = Depends(oauth2_scheme)) -> Dict:
             HTTPException(status_code=401, detail=f"Unauthorized: {err}")
         """
         id_token = auth_header.split(" ")[-1]
-        OIDC_discoveries = discover.auth_server(base_url=base_authorization_server_uri)
+        OIDC_discoveries = discover.auth_server(openid_connect_url=openid_connect_url)
         key = discover.public_keys(OIDC_discoveries)
         algorithms = discover.signing_algos(OIDC_discoveries)
 
@@ -96,10 +87,14 @@ def authenticate_user(auth_header: str = Depends(oauth2_scheme)) -> Dict:
                 id_token,
                 key,
                 algorithms,
-                audience=audience if audience else client_id,
+                audience=audience,
                 issuer=issuer,
-                # Disabled at_hash check since we aren't using the access token
-                options={"verify_at_hash": False},
+                options={
+                    # Disabled at_hash check since we aren't using the access token
+                    "verify_at_hash": False,
+                    "verify_iss": issuer is not None,
+                    "verify_aud": audience is not None,
+                },
             )
 
         except (ExpiredSignatureError, JWTError, JWTClaimsError) as err:
diff --git a/fastapi_oidc/discovery.py b/fastapi_oidc/discovery.py
@@ -22,11 +22,9 @@ def get_signing_algos(OIDC_spec: Dict):
         return algos
 
     @cached(TTLCache(1, cache_ttl))
-    def discover_auth_server(*_, base_url: str) -> Dict:
-        discovery_url = f"{base_url}/.well-known/openid-configuration"
-        r = requests.get(discovery_url)
-        # If the auth server is failing we can't verify tokens.
-        # Soooo panic I guess?
+    def discover_auth_server(*_, openid_connect_url: str) -> Dict:
+        r = requests.get(openid_connect_url)
+        # Raise if the auth server is failing since we can't verify tokens
         r.raise_for_status()
         configuration = r.json()
         return configuration
diff --git a/tests/conftest.py b/tests/conftest.py
@@ -57,9 +57,8 @@ def public_key(key):
 @pytest.fixture
 def config_w_aud():
     return {
-        "client_id": "CongenitalOptimist",
         "audience": "NeverAgain",
-        "base_authorization_server_uri": "WhatAreTheCivilianApplications?",
+        "openid_connect_url": "WhatAreTheCivilianApplications?",
         "issuer": "PokeItWithAStick",
         "signature_cache_ttl": 6e3,
     }
@@ -68,8 +67,7 @@ def config_w_aud():
 @pytest.fixture
 def no_audience_config():
     return {
-        "client_id": "CongenitalOptimist",
-        "base_authorization_server_uri": "WhatAreTheCivilianApplications?",
+        "openid_connect_url": "WhatAreTheCivilianApplications?",
         "issuer": "PokeItWithAStick",
         "signature_cache_ttl": 6e3,
     }
@@ -107,13 +105,12 @@ def token_with_audience(private_key, config_w_aud, test_email) -> str:
 @pytest.fixture
 def token_without_audience(private_key, no_audience_config, test_email) -> str:
     # Make a token where audience is client_id
-    client_id: str = str(no_audience_config["client_id"])
     issuer: str = str(no_audience_config["issuer"])
     now = int(time.time())
 
     return jwt.encode(
         {
-            "aud": client_id,
+            "aud": "NoAudience",
             "iss": issuer,
             "email": test_email,
             "name": "SweetAndFullOfGrace",
diff --git a/tests/test_auth.py b/tests/test_auth.py
@@ -39,7 +39,6 @@ def test__authenticate_user_no_aud(
     id_token = IDToken(**authenticate_user(auth_header=f"Bearer {token}"))
 
     assert id_token.email == test_email  # nosec
-    assert id_token.aud == no_audience_config["client_id"]
 
 
 def test__authenticate_user_returns_custom_tokens(
