-
A robust OAuth2 and OpenID Connect authentication library for Crystal
+
A standards-compliant OAuth 2.0, OpenID Connect, and Resource Server security shard for Crystal
-Authly is a production-ready Crystal library that provides secure, standards-compliant OAuth2 and OpenID Connect authentication capabilities. Built with developer experience in mind, Authly offers a comprehensive suite of grant types, flexible token strategies, and intuitive APIs that make implementing authentication straightforward and maintainable.
+**Authly** is a zero-framework OAuth 2.0 and OpenID Connect library built directly on Crystal's standard `HTTP::Handler`. Mount it as an **Authorization Server** (`Authly::Handler`), protect your API routes as a **Resource Server** (`Authly::Handler::Bearer` and `Authly::Handler::RequireScope`), or run both together in the same process or across microservices.
-## Table of Contents
-
-- [Features](#features)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Configuration](#configuration)
-- [OAuth2 Grant Types](#oauth2-grant-types)
-- [Authentication Endpoints](#authentication-endpoints)
-- [Customization](#customization)
- - [Custom Authorizable Client](#custom-authorizable-client)
- - [Custom Authorizable Owner](#custom-authorizable-owner)
- - [Custom Token Store](#custom-token-store)
-- [Token Strategies](#token-strategies)
-- [Protecting Your API](#protecting-your-api)
- - [Bearer Handler](#bearer-handler)
- - [Requiring Scopes](#requiring-scopes)
- - [JWKS and Metadata](#jwks-and-metadata)
- - [Mounting in an Azu App](#mounting-in-an-azu-app)
-- [Roadmap](#roadmap)
-- [Contributing](#contributing)
-- [License](#license)
-- [Contact](#contact)
-
-## Features
-
-Authly provides a comprehensive authentication solution with the following capabilities:
-
-**OAuth2 Grant Types**
-
-- ✅ Authorization Code Grant (with PKCE support)
-- ✅ Client Credentials Grant
-- ✅ Resource Owner Password Credentials Grant
-- ✅ Implicit Grant
-- ✅ Refresh Token Grant
-- ✅ Device Authorization Grant
-
-**OpenID Connect**
-
-- ✅ ID Token generation and validation
-- ✅ Standard claims support
-- ✅ Custom claims integration
-- ✅ UserInfo endpoint
-- ✅ OpenID Connect Discovery (/.well-known/openid-configuration)
-- ✅ OAuth2 Dynamic Client Registration (RFC 7591)
-
-**Token Management**
-
-- ✅ JWT and Opaque token strategies
-- ✅ Token introspection endpoint
-- ✅ Token revocation endpoint
-- ✅ Configurable token expiration (TTL)
-- ✅ Pluggable token storage backend
-
-**Security**
+---
-- ✅ PKCE (Proof Key for Code Exchange) support with S256 enforcement
-- ✅ Certificate-bound access tokens (mTLS / RFC 8705)
-- ✅ JWT Secured Authorization Response Mode (JARM / RFC 9101)
-- ✅ State parameter validation
-- ✅ Redirect URI validation
-- ✅ Secure token generation
-- ✅ Multiple JWT algorithms support (HS256, RS256, etc.)
+## Key Capabilities
-**Developer Experience**
+| Area | Supported Standards & Features |
+| :--- | :--- |
+| **OAuth 2.0 Grants** | Authorization Code (`authorization_code`), Client Credentials (`client_credentials`), Refresh Token (`refresh_token` with rotation & family reuse detection), Device Authorization (`urn:ietf:params:oauth:grant-type:device_code`), Cryptographic Challenge-Response (`challenge_response` / `urn:ietf:params:oauth:grant-type:challenge`), Password (`password`), Implicit (`implicit`) |
+| **OpenID Connect** | `id_token` issuance (`nonce`, `acr`, `amr`, `auth_time`), `GET /oauth/userinfo`, OIDC Discovery (`/.well-known/openid-configuration`), OAuth 2.0 Authorization Server Metadata (`/.well-known/oauth-authorization-server` — RFC 8414), JWKS (`/.well-known/jwks.json` — RFC 7517) |
+| **FAPI & Advanced Security** | PKCE with `S256` enforcement (RFC 7636), Pushed Authorization Requests (`POST /oauth/par` — RFC 9126), JWT Secured Authorization Response Mode (JARM — RFC 9101), Certificate-Bound Access Tokens (`cnf.x5t#S256` mTLS — RFC 8705), Dynamic Client Registration (`POST /oauth/register` — RFC 7591) |
+| **Token Lifecycle** | `:jwt` (`HS*`, `RS*`, `ES*`) and `:opaque` token strategies, asymmetric key rotation (`signing_key_id` + `verification_keys`), Token Introspection (`POST /oauth/introspect` — RFC 7662), Token Revocation (`POST /oauth/revoke` — RFC 7009), host-controlled `IssuanceOptions` |
+| **Resource Server Protection** | `Authly::Handler::Bearer` (RFC 6750 verification, audience checking, `context.authly_claims!`) and `Authly::Handler::RequireScope` (route-level `all` / `any` scope enforcement) |
-- ✅ Intuitive, type-safe API
-- ✅ Comprehensive documentation
-- ✅ Easy-to-configure HTTP handlers
-- ✅ Flexible customization points
-- ✅ Built-in middleware support
+---
## Installation
-Add Authly to your `shard.yml`:
+Add `authly` to your `shard.yml`:
```yaml
dependencies:
@@ -96,1406 +40,171 @@ Then run:
shards install
```
-**Requirements:**
+**Requirements:** Crystal `>= 1.22.0`
-- Crystal 1.22.0 or higher (CI runs 1.22.1)
-- A supported operating system (Linux, macOS, or Windows)
+---
## Quick Start
-Get up and running with Authly in minutes:
+Create a working OAuth 2.0 Authorization Server and protected Resource API in a single file:
```crystal
+require "http/server"
+require "json"
require "authly"
-# Configure Authly
Authly.configure do |config|
- config.issuer = "https://your-app.com"
- config.secret_key = ENV["AUTHLY_SECRET_KEY"]
- config.access_ttl = 1.hour
- config.refresh_ttl = 1.day
- config.token_strategy = :jwt
+ config.issuer = "http://localhost:8080"
+ config.base_url = "http://localhost:8080"
+ config.secret_key = ENV.fetch("AUTHLY_SECRET_KEY", "dev-secret-change-in-production-32b")
config.algorithm = JWT::Algorithm::HS256
-end
-
-# Start the authentication server
-server = HTTP::Server.new([
- Authly::Handler.new,
-])
-
-server.bind_tcp("0.0.0.0", 8080)
-puts "Authly server listening on http://0.0.0.0:8080"
-server.listen
-```
-
-This minimal setup provides a working OAuth2 server with JWT token support. For production use, you'll want to implement custom clients, owners, and token storage (see [Customization](#customization)).
-
-## Configuration
-
-Authly offers extensive configuration options to tailor authentication to your application's needs:
-
-```crystal
-Authly.configure do |config|
- # Issuer Configuration
- config.issuer = "https://your-app.com"
- config.base_url = "https://your-app.com" # Base URL for OpenID Connect Discovery
-
- # Security Keys
- config.secret_key = ENV["AUTHLY_SECRET_KEY"] # Required for JWT signing
- config.public_key = ENV["AUTHLY_PUBLIC_KEY"] # Optional, for asymmetric algorithms
-
- # Token Time-to-Live (TTL)
- config.access_ttl = 1.hour # Access token expiration
- config.refresh_ttl = 1.day # Refresh token expiration
- config.code_ttl = 5.minutes # Authorization code expiration
-
- # Token Strategy
- config.token_strategy = :jwt # Options: :jwt or :opaque
- config.algorithm = JWT::Algorithm::HS256 # JWT signing algorithm
-
- # Resource-owner login (REQUIRED for /oauth/authorize and /device, see "Authorization Endpoint")
- config.authenticate_user = ->(context : HTTP::Server::Context) { MySession.user_id(context) }
- config.login_url = ->(context : HTTP::Server::Context) { "/login?return_to=#{URI.encode_www_form(context.request.resource)}" }
-
- # PKCE Enforcement
- config.enforce_pkce = false # Require PKCE for all authorization code flows
- config.enforce_pkce_s256 = false # Enforce S256 method only (reject plain)
-
- # Dynamic Client Registration
- config.allow_dynamic_registration = false
- config.client_store = InMemoryClientStore.new
-
- # Certificate-Bound Tokens (mTLS)
- config.require_certificate_bound_tokens = false
- config.trusted_ca_certificates = [] of String
-
- # Custom Implementations (see Customization section)
- config.owners = CustomAuthorizableOwner.new
- config.clients = CustomAuthorizableClient.new
- config.token_store = CustomTokenStore.new
- config.state_store = CustomStateStore.new
- config.device_code_store = CustomDeviceCodeStore.new
-end
-```
-
-### Configuration Options
-
-| Option | Type | Description | Default |
-| ---------------- | ------------------ | ------------------------------------ | ----------- |
-| `issuer` | String | The issuer identifier for tokens | Required |
-| `secret_key` | String | Secret key for JWT signing | Required |
-| `public_key` | String | Public key for asymmetric algorithms | `nil` |
-| `access_ttl` | Time::Span | Access token lifetime | `1.hour` |
-| `refresh_ttl` | Time::Span | Refresh token lifetime | `1.day` |
-| `refresh_absolute_ttl` | Time::Span | Longest a sign-in can be renewed by rotating refresh tokens | `30.days` |
-| `code_ttl` | Time::Span | Authorization code lifetime | `5.minutes` |
-| `token_strategy` | Symbol | Token type (`:jwt` or `:opaque`) | `:jwt` |
-| `algorithm` | JWT::Algorithm | JWT signing algorithm | `HS256` |
-| `owners` | AuthorizableOwner | Resource owner authentication | Required |
-| `clients` | AuthorizableClient | Client authentication | Required |
-| `token_store` | TokenStore | Token persistence layer | In-memory |
-
-## OAuth2 Grant Types
-
-Authly implements all standard OAuth2 grant types, allowing you to choose the appropriate authentication flow for your use case:
-
-### Authorization Code Grant
-
-The most secure OAuth2 flow, recommended for server-side applications. Supports PKCE for enhanced security.
-
-**Use Case:** Web applications with a backend server, mobile applications
-
-**Endpoint:** `POST /oauth/token`
-
-```crystal
-# Request parameters
-{
- "grant_type": "authorization_code",
- "code": "AUTH_CODE",
- "redirect_uri": "https://your-app.com/callback",
- "client_id": "CLIENT_ID",
- "client_secret": "CLIENT_SECRET",
- "code_verifier": "CODE_VERIFIER" # Optional, for PKCE
-}
-```
-
-### Client Credentials Grant
-
-Used for server-to-server authentication where the client acts on its own behalf.
-
-**Use Case:** Microservices, background jobs, API integrations
-
-**Endpoint:** `POST /oauth/token`
-
-```crystal
-# Request parameters
-{
- "grant_type": "client_credentials",
- "client_id": "CLIENT_ID",
- "client_secret": "CLIENT_SECRET",
- "scope": "read write" # Optional
-}
-```
-
-### Resource Owner Password Credentials Grant
-
-Allows exchanging username and password directly for tokens. Only use for highly trusted applications.
-
-**Use Case:** First-party applications, legacy system migrations
-
-**Endpoint:** `POST /oauth/token`
-
-```crystal
-# Request parameters
-{
- "grant_type": "password",
- "username": "USER_NAME",
- "password": "PASSWORD",
- "client_id": "CLIENT_ID",
- "client_secret": "CLIENT_SECRET",
- "scope": "read write" # Optional
-}
-```
-
-### Implicit Grant
-
-Returns tokens directly from the authorization endpoint without an intermediate code exchange.
-
-**Use Case:** Single-page applications (deprecated in favor of Authorization Code with PKCE)
-
-**Endpoint:** `GET /oauth/authorize`
-
-### Refresh Token Grant
-
-Allows obtaining a new access token without requiring user interaction.
-
-**Use Case:** Maintaining user sessions, token renewal
-
-**Endpoint:** `POST /oauth/token`
-
-```crystal
-# Request parameters
-{
- "grant_type": "refresh_token",
- "refresh_token": "REFRESH_TOKEN",
- "client_id": "CLIENT_ID",
- "client_secret": "CLIENT_SECRET",
- "scope": "read" // optional; may only narrow the scope of the original grant
-}
-```
-
-A refresh token is **single use**. The answer carries a new refresh token (same family) and the old one stops working.
-Presenting an already used refresh token revokes the whole family, so a leaked token is detected the first time
-either party uses it: the client must sign in again. A refresh token must be a `refresh_token`-typed token issued to
-the authenticating client, unexpired and not revoked; the access token it yields keeps the original scope, and the
-client must still be allowed that scope (`invalid_scope` otherwise, the token is not consumed). Rotation cannot renew a
-sign-in for ever: the family ends `refresh_absolute_ttl` (30 days) after the sign-in (`fexp` claim, which no token
-outlives), then the user signs in again. Revoking a refresh token revokes its whole family. Refresh tokens are not
-access tokens: `Authly.valid?`, introspection and the bearer handler refuse them.
-
-**Upgrading:** refresh tokens issued by earlier versions (without `cid`, `fid` and `scope`) are refused: users sign in
-again. A custom `Authly::TokenGenerator` must override `generate_refresh_token(client_id, jti, sub, scope, family)`
-and put `cid`, `scope`, `fid` and `token_type: "refresh_token"` in the token, otherwise its refresh tokens cannot be
-redeemed. A custom `TokenStore` needs an atomic `consume` (see "Custom Token Store"); the family is revoked through
-`revoke("refresh-family: