# Authly
[](https://github.com/descoped/authly/actions/workflows/build-test-native.yml)
[](https://github.com/descoped/authly/actions/workflows/full-stack-test-with-docker.yml)
[](https://codecov.io/gh/descoped/authly)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/descoped/authly/releases)
[](https://pypi.org/project/authly/)
[](https://hub.docker.com/r/descoped/authly/tags)
## A Modern OAuth 2.1 & OIDC Server Built with AI Collaboration
An **OAuth 2.1 and OpenID Connect authorization server** in active development. Built with FastAPI, PostgreSQL and Redis, Authly aims to provide standards-compliant authentication and authorization services.
---
Built through close collaboration between human developers and AI assistants (Claude, Gemini, and OpenAI), this authorization server follows a specification-driven development methodology. RFC standards and OpenID specifications guide our implementation choices, ensuring decisions are grounded in established protocols rather than arbitrary preferences.
The project began with traditional development to establish the foundational architecture. As it evolved, we adopted a hybrid approach where human developers maintain full control – reviewing, testing, and refactoring code in partnership with AI assistants. This collaborative workflow has proven particularly effective for navigating complex specifications and achieving compliance.
Through systematic testing and validation, we've achieved 100% conformance with OIDC Core requirements.
---
## ⚠️ Development Status
**This project is a work in progress:**
- Core OAuth 2.1 features are implemented with compliant error handling
- [OpenID Connect support with 100% conformance testing](https://github.com/descoped/authly/actions/workflows/conformance-tests.yml) (40/40 checks pass)
- OAuth 2.0 specification-compliant error responses
- Suitable for development and testing environments
- NOT recommended for production use without extensive testing and security audit
**Known Limitations:**
- UserInfo endpoint doesn't support POST method
- Some advanced OIDC test scenarios not fully implemented
- Edge cases in OAuth flows need more testing
- Not officially certified by OpenID Foundation
---
## 🔐 OAuth 2.1 Implementation
### **Core Features (Working)**
- **Authorization Code Flow** with mandatory PKCE (Proof Key for Code Exchange)
- **Client Management** for confidential and public OAuth clients
- **Token Revocation** (RFC 7009) for immediate token invalidation
- **Server Discovery** (RFC 8414) for automatic client configuration
- **Scope Management** with granular permission control
### **Supported Grant Types**
- **Authorization Code Grant** with PKCE for third-party applications
- **Password Grant** for trusted first-party applications (legacy support)
- **Refresh Token Grant** for token renewal
- **Client Credentials Grant** for service-to-service authentication
### **Standards Compliance (Partial)**
- **RFC 6749** - OAuth 2.0 Authorization Framework ✅ Implemented
- **RFC 7636** - Proof Key for Code Exchange (PKCE) ✅ Implemented
- **RFC 7009** - OAuth 2.0 Token Revocation ✅ Implemented
- **RFC 8414** - OAuth 2.0 Authorization Server Metadata ✅ Implemented
- **Official Certification**: ❌ Not certified
---
## 🆔 OpenID Connect Support
### **Basic OIDC Features (Working)**
- **ID Token Generation** with RS256/HS256 signing algorithms
- **UserInfo Endpoint** (GET method only)
- **JWKS Endpoint** for token signature verification
- **OIDC Discovery** with provider configuration metadata
### **OIDC Compliance Status**
- **Discovery**: 100% compliant ✅
- **JWKS**: 100% compliant ✅
- **Core Endpoints**: 100% compliant ✅
- **Security**: 100% compliant ✅
- **Overall**: 100% conformance (40/40 checks pass) ✅
- **Official Certification**: ❌ Not certified by OpenID Foundation
### **What Still Needs Work**
- UserInfo POST method support
- Advanced OIDC features (claims aggregation, request objects)
- Full end-to-end flow testing
- Official certification process
---
## 🛡️ Security Features
### **Implemented Security**
- **JWT Security** - RS256/HS256 signing with validation
- **Password Security** - bcrypt hashing (Argon2 planned)
- **Token Management** - JTI tracking and blacklisting
- **Rate Limiting** - Basic protection on auth endpoints
- **CORS Protection** - Configurable CORS policies
### **Admin Security Model**
- **Two-Layer Security** - Intrinsic authority + OAuth scopes
- **Bootstrap System** - Solves IAM chicken-and-egg paradox
- **API Restrictions** - Admin API localhost-only by default
### **Security Limitations**
- Not penetration tested
- No security audit performed
- Some edge cases not fully handled
- Performance under attack not tested
---
## 👥 User Management
### **Basic Features (Working)**
- User registration and authentication
- Role-based access control (admin/user)
- Profile management CRUD operations
- Password reset functionality
### **Admin Tools**
- CLI for OAuth client management
- Admin API for user management
- Scope management interface
- Basic monitoring endpoints
---
## 🚀 Quick Start
### **Development Setup**
```bash
# Clone repository
git clone https://github.com/descoped/authly.git
cd authly
# Install dependencies with uv
uv sync --all-groups
# Run with Docker Compose (recommended for development)
docker compose up
# Or run tests
uv run pytest
```
### **Docker Installation**
```bash
# Standard multi-service deployment
docker pull descoped/authly:latest
docker run -p 8000:8000 descoped/authly:latest
# All-in-one standalone container (includes PostgreSQL + Redis)
docker pull descoped/authly-standalone:latest
docker run --rm -p 8000:8000 descoped/authly-standalone:latest
# Enter Interactive Shell to access Authly Admin CLI + End-2-End Testing tools
docker exec -it $(docker ps --filter "ancestor=descoped/authly-standalone" --format "{{.ID}}") /bin/bash
# Using Docker Compose
docker compose up
```
The service will be available at `http://localhost:8000`
---
## 🧪 Testing
The project includes a comprehensive test suite:
- Integration tests with real PostgreSQL
- OAuth flow testing
- Basic OIDC compliance tests
- ~90% specification compliance achieved
```bash
# Run all tests
uv run pytest
# Run specific test category
uv run pytest tests/test_oauth.py -v
# Check conformance (90% compliance)
cd tck && make validate
```
---
## 📚 Documentation
- **[OAuth Implementation Guide](docs/oauth-guide.md)** - OAuth 2.1 features and usage
- **[OIDC Implementation Guide](docs/oidc-guide.md)** - OpenID Connect features
- **[API Reference](docs/api-reference.md)** - Complete API documentation
- **[Security Guide](docs/security-guide.md)** - Security features and best practices
- **[Deployment Guide](docs/deployment-guide.md)** - Deployment instructions
- **[Docker Standalone Guide](docs/docker-standalone.md)** - All-in-one container documentation
---
## 🛠️ Technology Stack
- **Python 3.11+** - Modern async/await with type annotations
- **FastAPI** - High-performance async web framework
- **PostgreSQL** - Primary data store with UUID support
- **Redis** - Optional caching and session storage
- **JWT** - Token-based authentication
- **Docker** - Containerized deployment
---
## 📋 Roadmap
### **Current Focus**
- [ ] Fix token endpoint error response format
- [ ] Add UserInfo POST method support
- [ ] Improve authorization endpoint error handling
- [ ] Complete OIDC test scenario coverage
### **Future Plans**
- [ ] Achieve 100% OIDC specification compliance
- [ ] Self-certification for OIDC compliance testing
- [ ] Argon2 password hashing
- [ ] Advanced OIDC features (prompt, max_age, ACR)
- [ ] GDPR compliance features
- [ ] Performance optimization
- [ ] Security audit
---
## 🤝 Contributing
This project is in active development and welcomes contributions. However, please note:
1. The codebase is evolving rapidly
2. Breaking changes may occur
3. Not all features are fully tested
4. Documentation may lag behind implementation
Please read the [Contributing Guidelines](.github/CONTRIBUTING.md) before submitting PRs.
---
## ⚖️ License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## ⚠️ Disclaimer
**This software is provided as-is, without warranty of any kind.** It is a work in progress and should not be used in production environments without thorough testing and security review. The developers are not responsible for any security breaches or data loss that may occur from using this software.
**Current Status:**
- ✅ Suitable for: Development, testing, learning, prototypes
- ❌ NOT suitable for: Production systems, high-security environments, certified compliance requirements
For production OAuth/OIDC needs, consider established solutions like Keycloak, Auth0, or Okta until this project reaches maturity.
Raw data
{
"_id": null,
"home_page": null,
"name": "authly",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "asyncio, authentication, authorization, fastapi, iam, identity, oauth, oauth2, oidc, security",
"author": null,
"author_email": "Ove Ranheim <oranheim@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ba/ec/76f90cd83f5db42c74b69938c77155cfa25e9cd7c7f6c9a42c40ce76e758/authly-0.5.7.tar.gz",
"platform": null,
"description": "# Authly\n\n[](https://github.com/descoped/authly/actions/workflows/build-test-native.yml)\n[](https://github.com/descoped/authly/actions/workflows/full-stack-test-with-docker.yml)\n[](https://codecov.io/gh/descoped/authly)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/descoped/authly/releases)\n[](https://pypi.org/project/authly/)\n[](https://hub.docker.com/r/descoped/authly/tags)\n\n## A Modern OAuth 2.1 & OIDC Server Built with AI Collaboration\n\nAn **OAuth 2.1 and OpenID Connect authorization server** in active development. Built with FastAPI, PostgreSQL and Redis, Authly aims to provide standards-compliant authentication and authorization services.\n\n---\n\nBuilt through close collaboration between human developers and AI assistants (Claude, Gemini, and OpenAI), this authorization server follows a specification-driven development methodology. RFC standards and OpenID specifications guide our implementation choices, ensuring decisions are grounded in established protocols rather than arbitrary preferences.\n\nThe project began with traditional development to establish the foundational architecture. As it evolved, we adopted a hybrid approach where human developers maintain full control \u2013 reviewing, testing, and refactoring code in partnership with AI assistants. This collaborative workflow has proven particularly effective for navigating complex specifications and achieving compliance.\n\nThrough systematic testing and validation, we've achieved 100% conformance with OIDC Core requirements.\n\n---\n\n## \u26a0\ufe0f Development Status\n\n**This project is a work in progress:**\n- Core OAuth 2.1 features are implemented with compliant error handling\n- [OpenID Connect support with 100% conformance testing](https://github.com/descoped/authly/actions/workflows/conformance-tests.yml) (40/40 checks pass)\n- OAuth 2.0 specification-compliant error responses\n- Suitable for development and testing environments\n- NOT recommended for production use without extensive testing and security audit\n\n**Known Limitations:**\n- UserInfo endpoint doesn't support POST method\n- Some advanced OIDC test scenarios not fully implemented\n- Edge cases in OAuth flows need more testing\n- Not officially certified by OpenID Foundation\n\n---\n\n## \ud83d\udd10 OAuth 2.1 Implementation\n\n### **Core Features (Working)**\n- **Authorization Code Flow** with mandatory PKCE (Proof Key for Code Exchange)\n- **Client Management** for confidential and public OAuth clients\n- **Token Revocation** (RFC 7009) for immediate token invalidation\n- **Server Discovery** (RFC 8414) for automatic client configuration\n- **Scope Management** with granular permission control\n\n### **Supported Grant Types**\n- **Authorization Code Grant** with PKCE for third-party applications\n- **Password Grant** for trusted first-party applications (legacy support)\n- **Refresh Token Grant** for token renewal\n- **Client Credentials Grant** for service-to-service authentication\n\n### **Standards Compliance (Partial)**\n- **RFC 6749** - OAuth 2.0 Authorization Framework \u2705 Implemented\n- **RFC 7636** - Proof Key for Code Exchange (PKCE) \u2705 Implemented\n- **RFC 7009** - OAuth 2.0 Token Revocation \u2705 Implemented\n- **RFC 8414** - OAuth 2.0 Authorization Server Metadata \u2705 Implemented\n- **Official Certification**: \u274c Not certified\n\n---\n\n## \ud83c\udd94 OpenID Connect Support\n\n### **Basic OIDC Features (Working)**\n- **ID Token Generation** with RS256/HS256 signing algorithms\n- **UserInfo Endpoint** (GET method only)\n- **JWKS Endpoint** for token signature verification\n- **OIDC Discovery** with provider configuration metadata\n\n### **OIDC Compliance Status**\n- **Discovery**: 100% compliant \u2705\n- **JWKS**: 100% compliant \u2705\n- **Core Endpoints**: 100% compliant \u2705\n- **Security**: 100% compliant \u2705\n- **Overall**: 100% conformance (40/40 checks pass) \u2705\n- **Official Certification**: \u274c Not certified by OpenID Foundation\n\n### **What Still Needs Work**\n- UserInfo POST method support\n- Advanced OIDC features (claims aggregation, request objects)\n- Full end-to-end flow testing\n- Official certification process\n\n---\n\n## \ud83d\udee1\ufe0f Security Features\n\n### **Implemented Security**\n- **JWT Security** - RS256/HS256 signing with validation\n- **Password Security** - bcrypt hashing (Argon2 planned)\n- **Token Management** - JTI tracking and blacklisting\n- **Rate Limiting** - Basic protection on auth endpoints\n- **CORS Protection** - Configurable CORS policies\n\n### **Admin Security Model**\n- **Two-Layer Security** - Intrinsic authority + OAuth scopes\n- **Bootstrap System** - Solves IAM chicken-and-egg paradox\n- **API Restrictions** - Admin API localhost-only by default\n\n### **Security Limitations**\n- Not penetration tested\n- No security audit performed\n- Some edge cases not fully handled\n- Performance under attack not tested\n\n---\n\n## \ud83d\udc65 User Management\n\n### **Basic Features (Working)**\n- User registration and authentication\n- Role-based access control (admin/user)\n- Profile management CRUD operations\n- Password reset functionality\n\n### **Admin Tools**\n- CLI for OAuth client management\n- Admin API for user management\n- Scope management interface\n- Basic monitoring endpoints\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### **Development Setup**\n\n```bash\n# Clone repository\ngit clone https://github.com/descoped/authly.git\ncd authly\n\n# Install dependencies with uv\nuv sync --all-groups\n\n# Run with Docker Compose (recommended for development)\ndocker compose up\n\n# Or run tests\nuv run pytest\n```\n\n### **Docker Installation**\n\n```bash\n# Standard multi-service deployment\ndocker pull descoped/authly:latest\ndocker run -p 8000:8000 descoped/authly:latest\n\n# All-in-one standalone container (includes PostgreSQL + Redis)\ndocker pull descoped/authly-standalone:latest\ndocker run --rm -p 8000:8000 descoped/authly-standalone:latest\n\n# Enter Interactive Shell to access Authly Admin CLI + End-2-End Testing tools\ndocker exec -it $(docker ps --filter \"ancestor=descoped/authly-standalone\" --format \"{{.ID}}\") /bin/bash\n\n# Using Docker Compose\ndocker compose up\n```\n\nThe service will be available at `http://localhost:8000`\n\n---\n\n## \ud83e\uddea Testing\n\nThe project includes a comprehensive test suite:\n- Integration tests with real PostgreSQL\n- OAuth flow testing\n- Basic OIDC compliance tests\n- ~90% specification compliance achieved\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run specific test category\nuv run pytest tests/test_oauth.py -v\n\n# Check conformance (90% compliance)\ncd tck && make validate\n```\n\n---\n\n## \ud83d\udcda Documentation\n\n- **[OAuth Implementation Guide](docs/oauth-guide.md)** - OAuth 2.1 features and usage\n- **[OIDC Implementation Guide](docs/oidc-guide.md)** - OpenID Connect features\n- **[API Reference](docs/api-reference.md)** - Complete API documentation\n- **[Security Guide](docs/security-guide.md)** - Security features and best practices\n- **[Deployment Guide](docs/deployment-guide.md)** - Deployment instructions\n- **[Docker Standalone Guide](docs/docker-standalone.md)** - All-in-one container documentation\n\n---\n\n## \ud83d\udee0\ufe0f Technology Stack\n\n- **Python 3.11+** - Modern async/await with type annotations\n- **FastAPI** - High-performance async web framework\n- **PostgreSQL** - Primary data store with UUID support\n- **Redis** - Optional caching and session storage\n- **JWT** - Token-based authentication\n- **Docker** - Containerized deployment\n\n---\n\n## \ud83d\udccb Roadmap\n\n### **Current Focus**\n- [ ] Fix token endpoint error response format\n- [ ] Add UserInfo POST method support\n- [ ] Improve authorization endpoint error handling\n- [ ] Complete OIDC test scenario coverage\n\n### **Future Plans**\n- [ ] Achieve 100% OIDC specification compliance\n- [ ] Self-certification for OIDC compliance testing\n- [ ] Argon2 password hashing\n- [ ] Advanced OIDC features (prompt, max_age, ACR)\n- [ ] GDPR compliance features\n- [ ] Performance optimization\n- [ ] Security audit\n\n---\n\n## \ud83e\udd1d Contributing\n\nThis project is in active development and welcomes contributions. However, please note:\n\n1. The codebase is evolving rapidly\n2. Breaking changes may occur\n3. Not all features are fully tested\n4. Documentation may lag behind implementation\n\nPlease read the [Contributing Guidelines](.github/CONTRIBUTING.md) before submitting PRs.\n\n---\n\n## \u2696\ufe0f License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## \u26a0\ufe0f Disclaimer\n\n**This software is provided as-is, without warranty of any kind.** It is a work in progress and should not be used in production environments without thorough testing and security review. The developers are not responsible for any security breaches or data loss that may occur from using this software.\n\n**Current Status:**\n- \u2705 Suitable for: Development, testing, learning, prototypes\n- \u274c NOT suitable for: Production systems, high-security environments, certified compliance requirements\n\nFor production OAuth/OIDC needs, consider established solutions like Keycloak, Auth0, or Okta until this project reaches maturity.",
"bugtrack_url": null,
"license": null,
"summary": "Authorization & User Token Handling Layer for You",
"version": "0.5.7",
"project_urls": {
"Homepage": "https://github.com/descoped/authly",
"Issues": "https://github.com/descoped/authly/issues",
"Repository": "https://github.com/descoped/authly"
},
"split_keywords": [
"asyncio",
" authentication",
" authorization",
" fastapi",
" iam",
" identity",
" oauth",
" oauth2",
" oidc",
" security"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "dc5655f9d2fbee5aec4165cdfb64439442afbec6579f7f192d1105be47d198f7",
"md5": "9c60bd5f7818f5d8480e483f2b3071c9",
"sha256": "f85286e522ea3842634387f7bc3ff1e0eaf48c8e765bbd4c15eed9709ace2a4c"
},
"downloads": -1,
"filename": "authly-0.5.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9c60bd5f7818f5d8480e483f2b3071c9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 233416,
"upload_time": "2025-08-08T12:32:50",
"upload_time_iso_8601": "2025-08-08T12:32:50.678091Z",
"url": "https://files.pythonhosted.org/packages/dc/56/55f9d2fbee5aec4165cdfb64439442afbec6579f7f192d1105be47d198f7/authly-0.5.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "baec76f90cd83f5db42c74b69938c77155cfa25e9cd7c7f6c9a42c40ce76e758",
"md5": "202d14cd83d9cf3c1dc2cdbe57096fa9",
"sha256": "3997cbfa746b24c2131d537b2521e8391243e4c1ea70fb828f3aa8f2f5d125ef"
},
"downloads": -1,
"filename": "authly-0.5.7.tar.gz",
"has_sig": false,
"md5_digest": "202d14cd83d9cf3c1dc2cdbe57096fa9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 649686,
"upload_time": "2025-08-08T12:32:52",
"upload_time_iso_8601": "2025-08-08T12:32:52.495110Z",
"url": "https://files.pythonhosted.org/packages/ba/ec/76f90cd83f5db42c74b69938c77155cfa25e9cd7c7f6c9a42c40ce76e758/authly-0.5.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 12:32:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "descoped",
"github_project": "authly",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "authly"
}
JSON
