{"id":9537,"library":"axioms-fastapi","title":"Axioms FastAPI","description":"axioms-fastapi provides robust OAuth2/OIDC authentication and authorization for FastAPI APIs, simplifying integration with identity providers. It is currently at version 0.0.13 and sees minor, incremental releases, indicating active development with potential for API changes.","status":"active","version":"0.0.13","language":"en","source_language":"en","source_url":"https://github.com/abhishektiwari/axioms-fastapi","tags":["fastapi","oauth2","oidc","authentication","authorization","security"],"install":[{"cmd":"pip install axioms-fastapi","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Core web framework integration.","package":"fastapi","optional":false},{"reason":"JWT (JSON Web Token) handling and cryptography.","package":"python-jose[cryptography]","optional":false},{"reason":"Asynchronous HTTP client for OIDC discovery.","package":"httpx","optional":false},{"reason":"Data validation and settings management (used by FastAPI internally, and often by auth libraries).","package":"pydantic","optional":false},{"reason":"ASGI server to run FastAPI applications (for quickstart/local development).","package":"uvicorn","optional":true}],"imports":[{"note":"Used to define the OIDC provider's configuration.","symbol":"OIDCConfig","correct":"from axioms_fastapi import OIDCConfig"},{"note":"The main class for integrating authentication and authorization with FastAPI dependencies.","symbol":"AxiomsAuth","correct":"from axioms_fastapi import AxiomsAuth"},{"note":"FastAPI's dependency injection system, essential for using AxiomsAuth.","symbol":"Depends","correct":"from fastapi import Depends"}],"quickstart":{"code":"import os\nfrom fastapi import FastAPI, Depends, HTTPException, status\nfrom axioms_fastapi import OIDCConfig, AxiomsAuth\n\napp = FastAPI()\n\n# Configure OIDC using environment variables for sensitive data\n# Replace with your actual OIDC provider details\noidc_config = OIDCConfig(\n    issuer_url=os.environ.get('OIDC_ISSUER_URL', 'https://your-oidc-provider.com/realm'),\n    client_id=os.environ.get('OIDC_CLIENT_ID', 'your-client-id'),\n    client_secret=os.environ.get('OIDC_CLIENT_SECRET', 'your-client-secret'),\n    audience=os.environ.get('OIDC_AUDIENCE', 'api://your-app') # Often the client_id or a specific identifier\n)\n\n# Initialize AxiomsAuth with the OIDC configuration\naxioms_auth = AxiomsAuth(oidc_config)\n\n@app.get(\"/protected\")\nasync def protected_route(user: dict = Depends(axioms_auth.get_current_user)):\n    \"\"\"An endpoint protected by OIDC authentication.\"\"\"\n    # The 'user' object will contain decoded token claims if authentication is successful\n    username = user.get('preferred_username', user.get('sub', 'anonymous'))\n    return {\"message\": f\"Hello, {username}! This is a protected route.\", \"user_info\": user}\n\n@app.get(\"/public\")\nasync def public_route():\n    \"\"\"A public endpoint that does not require authentication.\"\"\"\n    return {\"message\": \"This is a public route.\"}\n\n# To run this app (requires uvicorn):\n# 1. pip install uvicorn\n# 2. Set environment variables:\n#    export OIDC_ISSUER_URL=\"https://your-oidc-provider.com/auth/realms/master\" # Example Keycloak\n#    export OIDC_CLIENT_ID=\"your_api_client_id\"\n#    export OIDC_CLIENT_SECRET=\"your_client_secret\"\n#    export OIDC_AUDIENCE=\"account\"\n# 3. uvicorn your_file_name:app --reload\n# Then access /docs to try it out.","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Run `pip install axioms-fastapi` to install the library.","cause":"The `axioms-fastapi` package or its dependencies are not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'axioms_fastapi'"},{"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`.","cause":"The provided access token is missing, invalid, expired, or does not have the necessary scopes/claims, or the OIDC configuration is incorrect.","error":"HTTPException 401: Unauthorized"},{"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).","cause":"The decoded JWT token payload does not contain the expected claim, or the claim name differs from what the application expects.","error":"KeyError: 'preferred_username' (or similar for other token claims)"}]}