auth0-server-python 1.0.0b9

Auth0 server-side Python SDK

The Auth0 Server Python SDK is a library for implementing user authentication in Python applications.

📚 Documentation - 🚀 Getting Started - 💬 Feedback

Documentation

• Examples - examples for your different use cases.
• Docs Site - explore our docs site and learn more about Auth0.

Getting Started

1. Install the SDK

pip install auth0-server-python

If you’re using Poetry:

poetry install auth0-server-python

2. Create the Auth0 SDK client

Create an instance of the Auth0 client. This instance will be imported and used in anywhere we need access to the authentication methods.

from auth0_server_python.auth_server.server_client import ServerClient

auth0 = ServerClient(
    domain='<AUTH0_DOMAIN>',
    client_id='<AUTH0_CLIENT_ID>',
    client_secret='<AUTH0_CLIENT_SECRET>',
    secret='<AUTH0_SECRET>',
    authorization_params= {
      redirect_uri: '<AUTH0_REDIRECT_URI>',
    }
)

The AUTH0_DOMAIN, AUTH0_CLIENT_ID, and AUTH0_CLIENT_SECRET can be obtained from the Auth0 Dashboard once you've created an application. This application must be a Regular Web Application.

The AUTH0_REDIRECT_URI tells Auth0 what URL to use while redirecting the user back after successful authentication, e.g. http://localhost:3000/auth/callback. Note: your application needs to handle this endpoint and call the SDK's complete_interactive_login(url: string) to finish the authentication process. See below for more information.

The AUTH0_SECRET is the key used to encrypt the session and transaction cookies. You can generate a secret using openssl:

openssl rand -hex 64

3. Add login to your Application (interactive)

Before using redirect-based login, ensure the redirect_uri is configured when initializing the SDK:

auth0 = ServerClient(
    # ...
    redirect_uri='<AUTH0_REDIRECT_URI>',
    # ...
)

[!IMPORTANT]
You will need to register the AUTH0_REDIRECT_URI in your Auth0 Application as an Allowed Callback URLs via the Auth0 Dashboard.

In order to add login to any application, call start_interactive_login(), and redirect the user to the returned URL.

The implementation will vary based on the framework being used, but here is an example of what this would look like in FastAPI:

from fastapi import FastAPI, Request, Response
from starlette.responses import RedirectResponse

app = FastAPI()


@app.get("/auth/login")
async def login(request: Request):
    authorization_url = await auth0.start_interactive_login()
    return RedirectResponse(url=authorization_url)

Once the user has successfully authenticated, Auth0 will redirect the user back to the provided redirect_uri which needs to be handled in the application.

This implementation will also vary based on the framework used, but what needs to happen is:

• register an endpoint that will handle the configured redirect_uri.
• call the SDK's complete_interactive_login(url), passing it the full URL, including query parameters.

Here is an example of what this would look like in FastAPI, with redirect_uri configured as http://localhost:3000/auth/callback:

@app.get("/auth/callback")
async def callback(request: Request):
    result = await auth0.complete_interactive_login(str(request.url))
    # Store session or set cookies as needed
    return RedirectResponse(url="/")

4. Login with Custom Token Exchange

If you're migrating from a legacy authentication system or integrating with a custom identity provider, you can exchange external tokens for Auth0 tokens using the OAuth 2.0 Token Exchange specification (RFC 8693):

from auth0_server_python.auth_types import LoginWithCustomTokenExchangeOptions

# Exchange a custom token and establish a session
result = await auth0.login_with_custom_token_exchange(
    LoginWithCustomTokenExchangeOptions(
        subject_token="your-custom-token",
        subject_token_type="urn:acme:mcp-token",
        audience="https://api.example.com"
    ),
    store_options={"request": request, "response": response}
)

# Access the user session
user = result.state_data["user"]

For advanced token exchange scenarios (without creating a session), use custom_token_exchange() directly:

from auth0_server_python.auth_types import CustomTokenExchangeOptions

# Exchange a custom token for Auth0 tokens
response = await auth0.custom_token_exchange(
    CustomTokenExchangeOptions(
        subject_token="your-custom-token",
        subject_token_type="urn:acme:mcp-token",
        audience="https://api.example.com",
        scope="read:data write:data"
    )
)

print(response.access_token)

For more details and examples, see examples/CustomTokenExchange.md.

5. Multiple Custom Domains (MCD)

For applications that use multiple custom domains on the same Auth0 tenant, pass a domain resolver function instead of a static domain string:

from auth0_server_python.auth_server.server_client import ServerClient
from auth0_server_python.auth_types import DomainResolverContext

async def domain_resolver(context: DomainResolverContext) -> str:
    host = context.request_headers.get('host', '').split(':')[0]
    domain_map = {
        "acme.yourapp.com": "acme.auth0.com",
        "globex.yourapp.com": "globex.auth0.com",
    }
    return domain_map.get(host, "default.auth0.com")

auth0 = ServerClient(
    domain=domain_resolver,  # Callable enables MCD mode
    client_id='<AUTH0_CLIENT_ID>',
    client_secret='<AUTH0_CLIENT_SECRET>',
    secret='<AUTH0_SECRET>',
)

The SDK handles per-domain OIDC discovery, JWKS fetching, issuer validation, and session isolation automatically. Static string domains continue to work unchanged.

For more details and examples, see examples/MultipleCustomDomains.md.

Feedback

Contributing

We appreciate feedback and contribution to this repo! Before you get started, please read the following:

• Auth0's general contribution guidelines
• Auth0's code of conduct guidelines
• This repo's contribution guide

Raise an issue

To provide feedback or report a bug, please raise an issue on our issue tracker.

Vulnerability Reporting

Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

What is Auth0?

Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout Why Auth0?

This project is licensed under the MIT license. See the LICENSE file for more info.