Axioms FastAPI

Common errors

• ModuleNotFoundError: No module named 'axioms_fastapi'

  cause The `axioms-fastapi` package or its dependencies are not installed in the current Python environment.
  fix Run `pip install axioms-fastapi` to install the library.

• HTTPException 401: Unauthorized

  cause The provided access token is missing, invalid, expired, or does not have the necessary scopes/claims, or the OIDC configuration is incorrect.
  fix Check the OIDC client configuration (issuer, audience, client_id). Ensure a valid Bearer token is sent in the 'Authorization' header. Inspect the token's claims (e.g., using jwt.io) to verify its validity, expiration, and audience against your `oidc_config`.

• KeyError: 'preferred_username' (or similar for other token claims)

  cause The decoded JWT token payload does not contain the expected claim, or the claim name differs from what the application expects.
  fix Review your OIDC provider's configuration to ensure it's issuing the desired claims (e.g., `preferred_username`, `email`). Adjust your application code to use available claims (e.g., `user.get('sub')` for the subject ID, which is always present).

Warnings

• breaking The library is currently in `0.0.x` versions, which implies that API stability is not guaranteed. Minor version bumps (e.g., from 0.0.12 to 0.0.13) might introduce breaking changes without a major version increment.
  Fix: Always review the release notes and test thoroughly when upgrading to a new `0.0.x` version. Pin exact versions in `requirements.txt` to avoid unexpected breakage.
• gotcha Incorrect OIDC configuration (e.g., `issuer_url`, `client_id`, `client_secret`, `audience`) is a common source of authentication failures. Misconfiguration can lead to `401 Unauthorized` errors or token validation issues.
  Fix: Carefully verify all OIDC parameters against your Identity Provider's documentation. Pay special attention to the `audience` claim, which often needs to match a specific value configured in your OIDC client or API. Use environment variables for sensitive credentials.
• gotcha If `python-jose` fails to validate tokens with errors like 'Signature has no ECI parameter', it often indicates an issue with the public key, signing algorithm, or token structure.
  Fix: Ensure that your OIDC provider is correctly configured and publishing its public keys via the JWKS endpoint (usually `/.well-known/openid-configuration` provides this URL). Verify the token's signature, issuer, and audience using a JWT debugger (e.g., jwt.io).

Install

• pip install axioms-fastapi Install from PyPI

Imports

• OIDCConfig

  from axioms_fastapi import OIDCConfig

  Used to define the OIDC provider's configuration.
• AxiomsAuth

  from axioms_fastapi import AxiomsAuth

  The main class for integrating authentication and authorization with FastAPI dependencies.
• Depends

  from fastapi import Depends

  FastAPI's dependency injection system, essential for using AxiomsAuth.

Quickstart

This quickstart demonstrates how to set up a FastAPI application with `axioms-fastapi` for OIDC authentication. It configures the OIDC provider using environment variables, initializes `AxiomsAuth`, and protects an endpoint using `Depends(axioms_auth.get_current_user)`. A public endpoint is also included for comparison. Remember to replace placeholder URLs and credentials with your actual OIDC provider details.

import os
from fastapi import FastAPI, Depends, HTTPException, status
from axioms_fastapi import OIDCConfig, AxiomsAuth

app = FastAPI()

# Configure OIDC using environment variables for sensitive data
# Replace with your actual OIDC provider details
oidc_config = OIDCConfig(
    issuer_url=os.environ.get('OIDC_ISSUER_URL', 'https://your-oidc-provider.com/realm'),
    client_id=os.environ.get('OIDC_CLIENT_ID', 'your-client-id'),
    client_secret=os.environ.get('OIDC_CLIENT_SECRET', 'your-client-secret'),
    audience=os.environ.get('OIDC_AUDIENCE', 'api://your-app') # Often the client_id or a specific identifier
)

# Initialize AxiomsAuth with the OIDC configuration
axioms_auth = AxiomsAuth(oidc_config)

@app.get("/protected")
async def protected_route(user: dict = Depends(axioms_auth.get_current_user)):
    """An endpoint protected by OIDC authentication."""
    # The 'user' object will contain decoded token claims if authentication is successful
    username = user.get('preferred_username', user.get('sub', 'anonymous'))
    return {"message": f"Hello, {username}! This is a protected route.", "user_info": user}

@app.get("/public")
async def public_route():
    """A public endpoint that does not require authentication."""
    return {"message": "This is a public route."}

# To run this app (requires uvicorn):
# 1. pip install uvicorn
# 2. Set environment variables:
#    export OIDC_ISSUER_URL="https://your-oidc-provider.com/auth/realms/master" # Example Keycloak
#    export OIDC_CLIENT_ID="your_api_client_id"
#    export OIDC_CLIENT_SECRET="your_client_secret"
#    export OIDC_AUDIENCE="account"
# 3. uvicorn your_file_name:app --reload
# Then access /docs to try it out.