Skip to main content

AWS Cognito JWT authentication library for FastAPI

Project description

FastAPI - Cognito

FastAPI library that ease usage of AWS Cognito Auth. This library provides basic functionalities for decoding, validation and parsing Cognito JWT tokens and for now it does not support sign up and sign in features.

Requirements

  • Python >=3.8
  • FastAPI
  • AWS Cognito Service

How to install

Pip Command

pip install fastapi-cognito

How to use

This is the simple example of how to use this package:

  • Create app
from fastapi import FastAPI

app = FastAPI()

All mandatory fields are added in CognitoSettings BaseSettings object. Settings can be added in different ways. You can provide all required settings in .yaml or .json files, or your global BaseSettings object. Note that userpools field is Dict and FIRST user pool in a dict will be set as default automatically if userpool_name is not provided in CognitoAuth object. All fields shown in example below, are also required in .json or .yaml file (with syntax matching those files.)

  • Provide settings that are mandatory for CognitoAuth to work. You can provide one or more userpools.
    • app_client_id field for userpool besides string, can contain multiple string values provided within list, tuple or set
from pydantic_settings import BaseSettings
from pydantic.types import Any

class Settings(BaseSettings):
    check_expiration: bool = True
    jwt_header_prefix: str = "Bearer"
    jwt_header_name: str = "Authorization"
    userpools: dict[str, dict[str, Any]] = {
        "eu": {
            "region": "USERPOOL_REGION",
            "userpool_id": "USERPOOL_ID",
            "app_client_id": ["APP_CLIENT_ID_1", "APP_CLIENT_ID_2"] # Example with multiple ids
        },
        "us": {
            "region": "USERPOOL_REGION",
            "userpool_id": "USERPOOL_ID",
            "app_client_id": "APP_CLIENT_ID"
        },
        ...
    }

settings = Settings()

This example below shows how global BaseSettings object can be mapped to CognitoSettings and passed as param to CognitoAuth. If we were using .yaml or .json, we should call .from_yaml(path) or .from_json(path) methods on CognitoSettings object.

  • Instantiate CognitoAuth and pass previously created settings as settings param.
from fastapi_cognito import CognitoAuth, CognitoSettings

# default userpool(eu) will be used if there is no userpool_name param provided.
cognito_eu = CognitoAuth(
  settings=CognitoSettings.from_global_settings(settings)
)
cognito_us = CognitoAuth(
  settings=CognitoSettings.from_global_settings(settings), userpool_name="us"
)
  • This is a simple endpoint that requires authentication, it uses FastAPI dependency injection to resolve all required operations and get Cognito JWT.
from fastapi_cognito import CognitoToken
from fastapi import Depends

@app.get("/")
def hello_world(auth: CognitoToken = Depends(cognito_eu.auth_required)):
    return {"message": "Hello world"}

Optional authentication

If authentication should be optional, we can use cognito_eu.auth_optional

Example:

from fastapi_cognito import CognitoToken
from fastapi import Depends

@app.get("/")
def hello_world(auth: CognitoToken = Depends(cognito_eu.auth_optional)):
    return {"message": "Hello world"}

Custom Token Model

This feature adds possiblity to use any token type for authentication(e.g. parsing ID token).

In case your token payload contains additional values, you can provide custom token model instead of CognitoToken. If there is no custom token model provided, CognitoToken will be set as a default model. Custom model should be provided to CognitoAuth object, and should be set as type of auth variable for endpoint dependency.

Example:

class CustomTokenModel(CognitoToken):
    custom_value: Optional[str] = None


cognito = CognitoAuth(
    settings=CognitoSettings.from_global_settings(settings),
    # Here we provide custom token model
    custom_model=CustomTokenModel
)

@app.get("/")
# Type of `auth` should be custom token Class
def hello_world(auth: CustomTokenModel = Depends(cognito.auth_required)):
    return {"message": f"Hello {auth.custom_value}"}

Custom Cognito attributes

Custom attributes in Cognito starts with custom:, which is the issue for parsing this variable with pydantic because of the colon. To parse custom attributes, add the full name of Cognito attribute to Pydantic Field alias.

class CustomTokenModel(CognitoToken):
    custom_value: Optional[str] = Field(alias="custom:custom_attr")

Pydantic will automatically parse value by alias if specified. Make sure that you have default value set if attribute is optional.

OpenAPI docs authentication

To use tokens to authenticate requests using OpenAPI docs, you can create wrapper class.

from fastapi.security import HTTPBearer
from starlette.requests import Request
from fastapi_cognito import CognitoToken

class CognitoAuth(HTTPBearer):
    async def __call__(self, request: Request) -> CognitoToken:
        return await cognito.auth_required(request=request)

cognito_auth = CognitoAuth()

@router.get("/")
async def test_endpoint(auth: CognitoToken = Depends(cognito_auth)):
    return JSONResponse(
        status_code=200, content={"detail": "Success"}
    )

This will show button for adding authentication token to the request.

Using custom JWKS URL for userpool

If you need to use custom JWKS URL for userpool, for example when you're running cognito-local for local development, you can specify JWKS_URL configuration per userpool.

class Settings(BaseSettings):
    userpools: dict[str, dict[str, Any]] = {
        "eu": {
            "region": "USERPOOL_REGION",
            "userpool_id": "USERPOOL_ID",
            "app_client_id": "APP_CLIENT_ID",
            "jwks_url": "https://local-cognito-idp:port/jwks.json"
        }
        ...
    }

By setting this configuration, CognitoAuth will automatically use this url to retrieve JWKS for userpool. If configuration is not set, CognitoAuth will generate URL in the following format https://cognito-idp.<region>.amazonaws.com/<userpool_id>/.well-known/jwks.json and will use that URL to retrieve JWKS.

There is global configuration through environment variable AWS_COGNITO_KEYS_URL which is supported for backward compatibility with previous dependency on cognitojwt library. CognitoAuth will prioritise in the following order:

  • jwks_url configuration per userpool,
  • AWS_COGNITO_KEYS_URL environment variable if set,
  • default value of https://cognito-idp.<region>.amazonaws.com/<userpool_id>/.well-known/jwks.json

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

fastapi_cognito-2.7.0.tar.gz (11.1 kB view details)

Uploaded Source

Built Distribution

fastapi_cognito-2.7.0-py3-none-any.whl (11.8 kB view details)

Uploaded Python 3

File details

Details for the file fastapi_cognito-2.7.0.tar.gz.

File metadata

  • Download URL: fastapi_cognito-2.7.0.tar.gz
  • Upload date:
  • Size: 11.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.7.1 CPython/3.12.6 Linux/6.10.10-100.fc39.x86_64

File hashes

Hashes for fastapi_cognito-2.7.0.tar.gz
Algorithm Hash digest
SHA256 16996ff0b0b08287df722aedb69f860ffef7cda8741eb911b6ae52c90b65bef6
MD5 c1030f6e7422d8915e4690f4ec9f9e77
BLAKE2b-256 ec1b3050e0095c59d58a92f5c71f545112369b892719b67765582dc4fc06a23c

See more details on using hashes here.

File details

Details for the file fastapi_cognito-2.7.0-py3-none-any.whl.

File metadata

  • Download URL: fastapi_cognito-2.7.0-py3-none-any.whl
  • Upload date:
  • Size: 11.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.7.1 CPython/3.12.6 Linux/6.10.10-100.fc39.x86_64

File hashes

Hashes for fastapi_cognito-2.7.0-py3-none-any.whl
Algorithm Hash digest
SHA256 d5925699d207a3d3d01f0484752f9002296da54d301fad8f179c54f7a0ba511b
MD5 dcf0e825b11b1064a71f868540b9fd88
BLAKE2b-256 3fed4c991d3b16ba1d896e5fa2670171d554c62fade5c0ee14cf04f78cb0bb55

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page