cognito-auth

Unified authentication and authorisation for AWS Cognito-protected web applications. Supports Streamlit, Dash, FastAPI, and Gradio with minimal configuration.

Installation

Available extras: streamlit, dash, fastapi, gradio, all

# uv (preferred)
uv add cognito-auth[streamlit] --git https://github.com/co-cddo/gds-idea-app-auth.git

# pip
pip install "cognito-auth[streamlit] @ git+https://github.com/co-cddo/gds-idea-app-auth.git"

Quick Start

from cognito_auth.streamlit import StreamlitAuth

auth = StreamlitAuth.from_config()
user = auth.get_auth_user()

Documentation

Full documentation available at co-cddo.github.io/gds-idea-app-auth.

Contributing

Setup

# Clone and install dependencies
git clone https://github.com/co-cddo/gds-idea-app-auth/
cd gds-idea-app-auth
uv sync

Development Commands

• uv run pytest - Run tests
• uv run pytest --cov - Run tests with coverage
• uv run ruff check . - Lint code
• uv run ruff format . - Format code
• uv run mkdocs serve - Preview documentation locally

Testing

Tests use pytest with fixtures and mocks. Add tests for new features in tests/cognito_auth/.

# Run specific test file
uv run pytest tests/cognito_auth/test_user.py -v

# Run tests matching pattern
uv run pytest -k test_authoriser

Code Standards

• Python 3.12+
• Type hints where appropriate
• Ruff for linting and formatting (configured in pyproject.toml)
• 100% test coverage for new features

Project Structure

src/cognito_auth/        # Main package
├── user.py              # User model
├── token_verifier.py    # JWT verification
├── authoriser.py        # Authorisation rules
└── [framework].py       # Framework integrations

tests/cognito_auth/      # Test suite
docs/                    # MkDocs documentation

See AGENTS.md for detailed architecture and development guidance.

License

MIT License - see LICENSE for details.