agr-cognito-py
AWS Cognito JWT authentication library for FastAPI applications, designed for the Alliance of Genome Resources (AGR) ecosystem.
Features
- JWT token validation for AWS Cognito ID and access tokens
- FastAPI dependencies for easy authentication integration
- Support for both user authentication (ID tokens) and machine-to-machine auth (access tokens)
- Admin token generation using OAuth client_credentials flow
- MOD-based permission utilities for AGR applications
- Token caching for improved performance
Installation
pip install agr-cognito-py
Quick Start
Environment Variables
Set the following environment variables:
# Required for token validation
export COGNITO_REGION="us-east-1"
export COGNITO_USER_POOL_ID="us-east-1_xxxxx"
export COGNITO_CLIENT_ID="your-client-id"
# Optional: Additional allowed client IDs (comma-separated)
export COGNITO_ALLOWED_CLIENT_IDS="client1,client2"
# Required for admin token generation
export COGNITO_ADMIN_CLIENT_ID="admin-client-id"
export COGNITO_ADMIN_CLIENT_SECRET="admin-client-secret"
export COGNITO_TOKEN_URL="https://your-domain.auth.region.amazoncognito.com/oauth2/token"
export COGNITO_ADMIN_SCOPE="your-api/scope"
FastAPI Integration
Use Security (recommended) or Depends to protect your endpoints. Security integrates
with Swagger UI's "Authorize" button for easy testing.
from typing import Dict, Any
from fastapi import APIRouter, Depends, HTTPException, Response, Security, status
from sqlalchemy.orm import Session
from agr_cognito_py import get_cognito_user_swagger, get_mod_access, ModAccess
router = APIRouter(prefix="/reference", tags=["Reference"])
@router.post("/", status_code=status.HTTP_201_CREATED)
def create(
request: ReferenceSchemaPost,
user: Dict[str, Any] = Security(get_cognito_user_swagger),
db: Session = Depends(get_db)
):
# user contains: email, name, cognito:groups, cognito:username, token_type
return reference_crud.create(db, request)
@router.delete("/{tag_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_tag(
tag_id: int,
user: Dict[str, Any] = Security(get_cognito_user_swagger),
db: Session = Depends(get_db)
):
# Check MOD-based permissions before deleting
mod_access = get_mod_access(user)
if mod_access == ModAccess.NO_ACCESS:
raise HTTPException(status_code=403, detail="No access")
tag_crud.destroy(db, tag_id, mod_access)
return Response(status_code=status.HTTP_204_NO_CONTENT)
Token Validation
from agr_cognito_py import CognitoAuth, CognitoConfig
# Configure with environment variables
auth = CognitoAuth()
# Or configure explicitly
config = CognitoConfig(
region="us-east-1",
user_pool_id="us-east-1_xxxxx",
client_id="your-client-id"
)
auth = CognitoAuth(config)
# Validate a token
try:
user = auth.validate_token(token)
print(f"User email: {user['email']}")
print(f"User groups: {user['cognito:groups']}")
except JWTError as e:
print(f"Invalid token: {e}")
Admin Token Generation
For machine-to-machine authentication using client credentials:
from agr_cognito_py import get_admin_token, generate_headers, CognitoAdminConfig
import requests
# Get admin token (uses caching automatically)
token = get_admin_token()
# Generate headers for API requests
headers = generate_headers(token)
# Make authenticated request
response = requests.get("https://api.example.com/data", headers=headers)
MOD-based Permissions
For AGR applications requiring Model Organism Database access control:
from agr_cognito_py import get_mod_access, has_mod_access, ModAccess
# Get user's MOD access level
access = get_mod_access(user)
if access == ModAccess.ALL_ACCESS:
print("User has full access")
elif access == ModAccess.WB:
print("User is a WormBase curator")
# Check specific MOD access
if has_mod_access(user, "WB"):
print("User can access WormBase data")
API Reference
Classes
CognitoAuth
Main class for JWT token validation.
CognitoConfig
Configuration for token validation (region, user pool, client ID).
CognitoAdminConfig
Configuration for admin token generation (client credentials flow).
Functions
Token Validation
get_cognito_user_swagger()- FastAPI dependency with Swagger UI integrationget_cognito_user()- FastAPI dependency supporting headers and cookiesrequire_groups(*groups)- FastAPI dependency requiring specific Cognito groups
Admin Tokens
get_admin_token(config, force_refresh)- Get admin access token with cachingget_authentication_token(config)- Alias for get_admin_tokengenerate_headers(token)- Generate Authorization headersclear_token_cache()- Clear the cached admin token
Permissions
get_mod_access(user)- Get ModAccess enum for a userhas_mod_access(user, mod)- Check if user has access to a specific MOD
Enums
ModAccess
NO_ACCESS- No MOD accessALL_ACCESS- Full access to all MODsSGD,RGD,MGI,ZFIN,XB,FB,WB- Specific MOD access
Development
# Clone the repository
git clone https://github.com/alliance-genome/agr_cognito_py.git
cd agr_cognito_py
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run linting
ruff check src tests
ruff format src tests
# Type checking
mypy src
License
MIT License - see LICENSE file for details.
Metadata
Release files for agr-cognito-py 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agr_cognito_py-0.1.0.tar.gz | 10.2 kB | Without provenance | Details for agr_cognito_py-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agr_cognito_py-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agr_cognito_py-0.1.0-py3-none-any.whl |
Total release size: 22.4 kB
Release files / agr_cognito_py-0.1.0.tar.gz
| Download URL | agr_cognito_py-0.1.0.tar.gz |
|---|---|
| Size | 10.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9ad30322e0f5558428190152a4b8814bc59fc3c71922b6aca779e101829f514a
|
|
BLAKE2b-256 checksum How to use checksums |
7f12eb6de9e10b26f3b587f9acd256d43e5cec6319686b9206b28e119c8889af
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.8.8
|
Release files / agr_cognito_py-0.1.0-py3-none-any.whl
| Download URL | agr_cognito_py-0.1.0-py3-none-any.whl |
|---|---|
| Size | 12.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
82474fdea443e717970ba114d512c7fc912220d1a56473ecabe67c37c52b2f40
|
|
BLAKE2b-256 checksum How to use checksums |
de727957dfaf5e0544793a5218e828db4c5dd7cb5173cbe7719546fb1256675d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.8.8
|
Security for agr-cognito-py 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.