AuthGate

A lightweight OAuth 2.0 Authorization Server supporting Device Authorization Grant ([RFC 8628][rfc8628]), Authorization Code Flow with PKCE ([RFC 6749][rfc6749] + [RFC 7636][rfc7636]), and Client Credentials Grant for machine-to-machine authentication

Table of Contents

• AuthGate
  • Table of Contents
  • Why AuthGate?
    • The Enterprise Case for AuthGate
      • 1. Fragmented authentication — every service re-inventing LDAP integration
      • 2. No token lifecycle management — tokens issued, never tracked or revoked
      • 3. Service owners have no visibility or control over who is using their service
  • ✨ Key Features
  • 🚀 Quick Start
    • Prerequisites
    • Installation
    • Run the Server
    • Test with Example CLI
  • 📖 Documentation
    • Getting Started
    • Development
    • Operations
    • Advanced Topics
  • 🎯 How It Works
    • Device Code Flow (RFC 8628) — for CLI / IoT
    • Authorization Code Flow (RFC 6749) — for Web / Mobile
    • Client Credentials Grant (RFC 6749 §4.4) — for Machine-to-Machine
  • 🎨 User Interface
    • Login & Authorization Flow
    • Session Management
  • ⚙️ Configuration
    • Basic Configuration (.env)
    • Advanced Features
  • 🏗️ Architecture
    • Technology Stack
    • Project Structure
  • 🚀 Deployment
    • Docker Deployment
    • Production Deployment
  • 🔒 Security
    • Production Checklist
    • What AuthGate Protects
  • 📊 Performance
    • Benchmarks (Reference)
    • Scalability
  • 🔧 Development
    • Build from Source
    • Extending AuthGate
  • ❓ FAQ
    • Q: Why not use OAuth password grant?
    • Q: Can I use this in production?
    • Q: How do I add user registration?
    • Q: Does it support refresh tokens?
    • Q: How do users revoke device access?
    • Q: Does it support Authorization Code Flow for web apps?
    • Q: Does it support machine-to-machine (M2M) authentication?
  • 🤝 Contributing
  • 📄 License
  • 📚 References
  • 🙏 Acknowledgments

---

Why AuthGate?

Modern CLI tools and IoT devices need secure user authentication, but traditional OAuth flows don't work well for devices without browsers or keyboards. AuthGate implements the OAuth 2.0 Device Authorization Grant ([RFC 8628][rfc8628]), allowing users to authenticate on a separate device while keeping credentials secure.

AuthGate also serves as a lightweight centralised identity gateway for internal platforms — unifying login across enterprise tools, giving every user full visibility and control over their active sessions and per-app grants, and providing security teams with a complete audit trail of all authentication events.

Perfect for:

• 🖥️ CLI tools (like gh, aws-cli) — Device Code Flow
• 📺 Smart TVs, IoT devices, gaming consoles — Device Code Flow
• 🌐 Web applications with server-side backends — Authorization Code Flow (confidential)
• 📱 Single-page apps and mobile apps — Authorization Code Flow + PKCE (public)
• 🤖 CI/CD pipelines and automation scripts — Device Code Flow or Client Credentials
• ⚙️ Microservices and server-to-server APIs — Client Credentials Grant
• 🏢 Enterprise teams needing token self-service — users manage and revoke their own active sessions and per-app grants via the built-in web UI (/account/sessions, /account/authorizations), no admin intervention required
• 🔑 Organisations wanting a unified internal SSO portal — centralise login across all internal tools and services through a single OAuth 2.0 gateway, eliminating per-system password management
• 🔍 Security & compliance teams — comprehensive audit logs of every authentication, token, and admin event with filtering and CSV export (/admin/audit), satisfying audit and regulatory requirements

The Enterprise Case for AuthGate

1. Fragmented authentication — every service re-inventing LDAP integration

The problem: Internal platforms (MCPs, skill services, bots, web tools, CLIs) each implement their own authentication logic. Most connect directly to LDAP, but with inconsistent patterns, password-handling rules, and session/token quality — resulting in security risk, duplicated effort, and high maintenance cost:

• Every team reinvents password validation, hashing, and policy enforcement.
• LDAP credentials and bind passwords are scattered across codebases.
• Any LDAP schema change or credential rotation forces simultaneous updates and redeployments across all services.
• There is no single, consistent login record across the organisation for audit purposes.

How AuthGate helps: A single Identity Gateway that all services integrate with as a standard OAuth 2.0 / OIDC client — no more direct LDAP wiring:

• Outward-facing: standard OAuth 2.0 APIs (Device Code, PKCE, Client Credentials).
• Inward-facing: centralised handling of LDAP, GitHub, Microsoft, and other identity sources.
• New services register as OAuth clients and never touch LDAP directly.

2. No token lifecycle management — tokens issued, never tracked or revoked

The problem: Basic OAuth implementations (like many internal MCPs) lack centralised token storage, leaving organisations unable to answer: Who has a valid token? When does it expire? Can it be revoked?

• No central record of issued tokens or active sessions.
• No refresh token rotation, expiry policy, or revocation capability.
• No audit trail: who logged in, when, from where, and which token was used?
• During a security incident, there is no fast path to revoke a token, trace its origin, or force a platform-wide re-login.

How AuthGate helps: Full token lifecycle management out of the box:

• Users self-serve at /account/sessions and /account/authorizations to inspect and revoke active sessions and per-app grants.
• Admins can force all users of any client to re-authenticate with a single action.
• Complete Audit Trails at /admin/audit with CSV export satisfy incident investigation and compliance requirements.

3. Service owners have no visibility or control over who is using their service

The problem: Without a centralised authorisation layer, service owners cannot answer basic operational questions:

• Which users currently have access to this service?
• When was their authorisation granted, and when does it expire?
• What scopes were approved, and can they be narrowed?
• How do I produce a login history, IP list, and token scope report for an audit?

How AuthGate helps: A unified OAuth client management console gives every service owner full visibility, control, and auditability:

• Configure client scopes, redirect URIs, token TTLs, and user authorisation records in one place.
• View all token activity for a service in real time.
• Revoke any user's authorisation instantly.
• Respond to audits and security requests without digging through disparate system logs.

---

✨ Key Features

• Three OAuth 2.0 Grant Types: Device Authorization Grant ([RFC 8628][rfc8628]) for CLI/IoT, Authorization Code Flow with PKCE ([RFC 6749][rfc6749] + [RFC 7636][rfc7636]) for web/mobile apps, and Client Credentials Grant ([RFC 6749][rfc6749] §4.4) for machine-to-machine authentication
• OIDC ID Token & UserInfo: Issues a signed id_token (OIDC Core 1.0) alongside the access token when openid scope is granted. Supports nonce, at_hash, and scope-gated profile/email claims. Includes /.well-known/openid-configuration discovery, /.well-known/jwks.json (JWKS), and /oauth/userinfo endpoints.
• Flexible JWT Signing: Supports HS256 (symmetric), RS256 (RS