A FastAPI Security object for AWS Cognito - supports both access and id tokens
Project description
fastapi-cognito-security
A micro-library that implements a FastAPI security class for AWS Cognito security.
This library supports receiving the Cogntio access (recommended) or id token in the HTTP Authorization
header using the standard Bearer
mechansism (e.g. - Authorization: Bearer <token>
).
Installation
pip install fastapi-cognito-security
Usage
Securing an individual route
from fastapi import Depends, FastAPI
from fastapi_cognito_security import CognitoBearer
app = FastAPI()
auth = CognitoBearer(
app_client_id="my_app_client_id",
userpool_id="my_userpool_id"
)
@app.get("/", dependencies=[Depends(auth)])
async def root():
return {"message": "Hello World"}
Securing a whole api
from fastapi import Depends, FastAPI
from fastapi_cognito_security import CognitoBearer
auth = CognitoBearer(
app_client_id="my_app_client_id",
userpool_id="my_userpool_id"
)
app = FastAPI(dependencies=[Depends(auth)])
@app.get("/")
async def root():
return {"message": "Hello World"}
When called, the CognitoBearer
object will:
- Get the public keys from your AWS Cognito UserPool.
NOTE - this will only happen once, and will be cached thereafter.
- Validate the JWT by verifying:
- The JWT is correctly constructed and conforms to the public key.
- The JWT has not expired.
- The
client_id
(access token) oraud
(id token) matches theapp_client_id
.
- Return either a
fastapi_cognito_security.AccessToken
orfastapi_cognito_security.IdToken
that contains the claims.NOTE - you can use these claims for further verification either within your API or by subclassing
CognitoBearer
.
Any failure in the above steps will result in a fastapi.HTTPException
being raised.
Claims
The returned AccessToken
or IdToken
will have the standard Cognito claims converted to Python types.
AccessToken
and IdToken
Claim | Python Type |
---|---|
auth_time | datetime.datetime |
exp | datetime.datetime |
iat | datetime.datetime |
iss | pydantic.HttpUrl |
jti | uuid.UUID |
origin_jti | uuid.UUID |
sub | uuid.UUID |
- Username (
username
in access tokens andcognito:username
in id tokens) is canonicalized to the claimusername
. - All additional claims will be converted directly to basic Python types.
- All claim names will have
:
replaced with_
(e.g. -custom:thing
will becomecustom_thing
)
AccessToken
only
Claim | Python Type |
---|---|
device_key | uuid.UUID |
scope | list[str] |
Swagger/OpenAPI 3.0 Support
Because CognitoBearer
is a fastapi.HTTPBearer
, it will operate in the docs that are auotmatically
generated by FastAPI in the same way as it's parent class.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for fastapi-cognito-security-0.0.2.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | f288bd0da53778256763a8200660646f58173201bcf0f440bf84417bee052e9b |
|
MD5 | 9e6cbfd2e1bcf5153141c8d5bd595025 |
|
BLAKE2b-256 | 5adfabfcbaae6014eb0deba523e06ef04537561d6b1f1b89de104175cf8e366c |
Hashes for fastapi_cognito_security-0.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a2cd7bd27e18ad632c2cb339f6690d8d3055b5d7754fb99f2c31042574750a7e |
|
MD5 | 6f2fa3fcf9e06fffd0b2ca5f2e474aa8 |
|
BLAKE2b-256 | fe2a0ddb4ac4e3e96f4896bfffb0ee919e8d5f3d671a4e5ce9e5f75fdcc8e298 |