Oauth

Perform authentication for incoming and outgoing requests in an Oauth context.

Overview
auth_url
jwks_url
audience
issuer
algorithms
jwks_cache_time
authentication_url
additional_authentication_request_headers
client_credentials_in_secret_manager
secret_manager
secret_manager_secret_name
env_client_id_name
env_client_secret_name
secret_manager_client_id_key
secret_manager_client_secret_key
expiration_key
token_key
jwt_refresh_ttl_sec
documentation_security_name

Overview

This can be used in two different ways:

Attached to an endpoint to enforce authentication via the JWKS class
Attached to an API backend to specify how to authenticate to an API endpoint.

To understand how to authenticate incoming requests, see the JWKS class, which this extends.

This additionally adds authentication to outgoing requests for the API (and other related) backends. It does this by fetching a client id and secret from your secret manager, exchanging them for a JWT with the authentication endpoint of your OAuth server, and then attaching the resulting JWT on all outgoing calls.

auth_url

Optional

jwks_url

Optional

The JWKS url to use to verify incoming JWTs

audience

Optional

The audience to accept JWTs for.

If provided, JWTs will be rejected if their aud claim doesn’t exactly match the value given here. If you do not provide an audience, then all audiences will be accepted.

issuer

Optional

The expected issuer of the JWTs.

If provided, JWTs will be rejected if their iss claim doesn’t exactly match the value given here. If you do not provide an issuer, then all audiences will be accepted.

algorithms

Optional

The allowed algorithms.

jwks_cache_time

Optional

The number of seconds for which the JWKS URL contents can be cached.

authentication_url

Optional

The authentication URL that exchanges client id/secret for the JWT to attach to requests.

You must provide the authentication URL if attaching this auth method to an API backend to authenticate outgoing requests.

So for instance, this:

class MyModel(clearskies.Model):
    id_column_name = "id"
    backend = clearskies.backends.ApiBackend(
        base_url="https://example.com",
        authentication=clearskies.authentication.Oauth(
            authentication_url="https://auth.example.com",
            secret_manager_secret_name="/path/to/client/credentials"
        )
    )

would make the following API call when a JWT is required to authenticate via the API backend:

requests.post(
    "https://auth.example.com",
    data={
        "grant_type": "client_credentials",
        "client_id": "CLIENT_ID_FROM_SECRET_MANAGER",
        "client_secret": "CLIENT_SECRET_FROM_SECRET_MANAGER",
    }
)

additional_authentication_request_headers

Optional

Additional request headers to include when authenticating to the auth endpoint.

This accepts either a dictionary of the headers, or a callable that returns the desired headers. Per clearskies norms, a callable can request any configured dependencies. So for instance, this:

class MyModel(clearskies.Model):
    id_column_name = "id"
    backend = clearskies.backends.ApiBackend(
        base_url="https://example.com",
        authentication=clearskies.authentication.Oauth(
            authentication_url="https://auth.example.com",
            secret_manager_secret_name="/path/to/client/credentials",
            additional_authentication_request_headers={
                "audience": "my-audience",
                "scopes" ["read", "write"],
            },
        ),
    )

would make the following API call when a JWT is required to authenticate via the API backend:

requests.post(
    "https://auth.example.com",
    data={
        "grant_type": "client_credentials",
        "client_id": "CLIENT_ID_FROM_SECRET_MANAGER",
        "client_secret": "CLIENT_SECRET_FROM_SECRET_MANAGER",
        "audience": "my-audience",
        "scopes": ["read", "write"],
    }
)

client_credentials_in_secret_manager

Optional

Fetch the client credentials from the secret manager.

If this is set to True (the default) then this authentication method will look for the client id/secret in the secret manager, and you must additionally set the credentials_key_name configuration setting. By default, it will look for a secret manager registered to the dependency injection name of secrets, but you can also explicitly attach a secret manager to this class via the secret_manager configuration setting.

If this is set to False then the client credentials will be fetched from environment variables. The specific environment variables are controlled by the env_client_key_name and env_client_secret_name configuration settings. These default to OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET, respectively.

secret_manager

Optional

The secret manager to use.

When client_credentials_in_secret_manager is set to True, you must provide a secret manager. This can be done by setting an instance of clearskies.Secrets in a dependency named secrets, or by attaching one directly to this configuration setting:

import clearskies
from from clearskies.secrets.akeyless import AkeylessAwsIam

class MyModel(clearskies.Model):
    id_column_name = "id"
    backend = clearskies.backends.ApiBackend(
        base_url="https://example.com",
        authentication=clearskies.authentication.Oauth(
            authentication_url="https://auth.example.com",
            secret_manager=clearskies_aws.secrets.SecretManager(),
        )
    )

    id = clearskies.columns.String()

secret_manager_secret_name

Optional

The path/name of the secret in your secret manager that contains the client credentials.

This assumes that the secret is a multi-valued/json secret that contains both the client id and client secret. By default, the keys for these (in the JSON object) should be client_id and client_secret, but those names are controlled via secret_manager_client_id_key and secret_manager_client_secret_key.

env_client_id_name

Optional

The name of the environment key to fetch the client id from (only relevant for client_credentials_in_secret_manager=False).

env_client_secret_name

Optional

The name of the environment key to fetch the client secret from (only relevant for client_credentials_in_secret_manager=False)

secret_manager_client_id_key

Optional

The json key inside the secret where the client id is found (default: client_id)

secret_manager_client_secret_key

Optional

The json key inside the secret where the client secret is found

expiration_key

Optional

The name of the key in the authentication response where the JWT TTL is found (in seconds).

token_key

Optional

The name of the key in the authentication response where the JWT is found

jwt_refresh_ttl_sec

Optional

The number of seconds before the JWT expiration to refresh it

documentation_security_name

Optional

The name of the security scheme in the auto-generated documentation.