axum-gate 1.1.0

Flexible authentication and authorization for Axum with JWT cookies or bearer tokens, optional OAuth2, and role/group/permission RBAC. Suitable for single-node and distributed systems.
Documentation

axum-gate

Crates.io Documentation License: MIT Build Status

Flexible, type-safe authentication and authorization for Axum using JWTs and optional OAuth2.

  • Cookie and bearer authentication
  • OAuth2 Authorization Code + PKCE flow that issues first-party JWT cookies
  • Hierarchical roles, groups, and string-based permissions
  • Ready-to-use login/logout handlers
  • Optional anonymous user context and static-token mode for internal services
  • In-memory and optional database-backed repositories
  • Feature-gated audit logging and Prometheus metrics

Install

This crate re-exports jsonwebtoken, cookie, uuid, axum_extra (and optionally prometheus) because those types appear in the public API, and it provides a convenience prelude via axum_gate::prelude::*.

[dependencies]
axum = "0.8"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
axum-gate = { version = "1" }

Optional features:

  • storage-surrealdb — SurrealDB repositories
  • storage-seaorm — SeaORM repositories (mutually exclusive with storage-seaorm-v2)
  • storage-seaorm-v2 — SeaORM v2 repositories (mutually exclusive with storage-seaorm)
  • audit-logging — structured audit events
  • prometheus — metrics for audit (implies audit-logging)
  • insecure-fast-hash — faster Argon2 preset for development only
  • aws_lc_rs — Use AWS Libcrypto for JWT cryptographic operations

Core concepts

  • Gate layer
    • Gate::cookie("issuer", codec): JWT via HTTP-only cookies (web apps)
    • Gate::bearer("issuer", codec): JWT via Authorization: Bearer header (APIs)
    • Gate::bearer(...).with_static_token("..."): shared-secret mode (internal services)
    • Gate::oauth2::<R, G>(): OAuth2 Authorization Code + PKCE flow builder; or use Gate::oauth2_with_jwt("issuer", codec, ttl_secs) to also mint first-party JWT cookies
    • allow_anonymous_with_optional_user(): never block; inserts optional user context
    • require_login(): allow baseline role and all supervisors (hierarchy)
  • Access policies
    • require_role(..), require_role_or_supervisor(..)
    • require_group(..)
    • require_permission("domain:action") — deterministic hashing to PermissionId; use validate_permissions! to catch collisions at test-time
  • Login/logout
    • route_handlers::login: verifies credentials and sets the auth cookie
    • route_handlers::logout: removes the auth cookie
  • Repositories
    • repositories::memory::{MemoryAccountRepository, MemorySecretRepository}
    • Optional SurrealDB / SeaORM backends via feature flags
  • JWT codec
    • codecs::jwt::JsonWebToken with JsonWebTokenOptions (use persistent keys in production)

Cryptographic Backend Selection

This crate supports two cryptographic backends for JWT operations:

Backend Default Description
rust_crypto ✅ Pure Rust implementation, works on all platforms without system dependencies
aws_lc_rs ❌ AWS Libcrypto implementation, potentially faster on some platforms

Using the Default Backend (rust_crypto)

The crate uses rust_crypto by default, which requires no additional setup:

[dependencies]
axum-gate = "1" # Uses rust_crypto by default

Switching to AWS Libcrypto (aws_lc_rs)

To use the AWS Libcrypto backend for potentially better performance:

[dependencies]
axum-gate = { version = "1", default-features = false, features = ["aws_lc_rs"] }

Note: The aws_lc_rs backend may require additional build tools depending on your platform. See the aws-lc-rs build documentation for details.

Security

  • Use a persistent JWT key (do not rely on the default random key in production)
  • Keep the issuer consistent between Gate configuration and RegisteredClaims
  • Use secure cookie settings in production (HttpOnly, Secure, appropriate SameSite)
  • Rate-limit sensitive endpoints (e.g., login)
  • Enable audit-logging and prometheus features for observability; never log secrets, tokens, or cookie values

Examples and docs

Examples and complete usage are available in the crate documentation on docs.rs; the repository also includes curated examples (e.g., examples/oauth2-github for a full GitHub OAuth2 flow): https://docs.rs/axum-gate

For common integration issues and practical debugging tips, see TROUBLESHOOTING.md (covers CookieGate, OAuth2 flows, and Bearer/Static token usage).

MSRV and license

  • MSRV: 1.88
  • License: MIT
  • SurrealDB (BUSL-1.1) notice:
    • Enabling the optional feature storage-surrealdb pulls in SurrealDB, which is licensed under the Business Source License 1.1 (not OSI-approved).
    • BUSL restricts Production Use unless allowed by the licensor or after the project's Change Date. This feature is off by default.
    • If you build or distribute binaries that enable this feature, you must comply with SurrealDB's BUSL terms or obtain a commercial license.
    • When distributing binaries that include SurrealDB, include third-party notices and the SurrealDB license text.
    • For fully open-source distributions, prefer the memory, storage-seaorm, or storage-seaorm-v2 backends. Note: storage-seaorm and storage-seaorm-v2 are mutually exclusive — enable only one of these features per build.
  • subtle license notice:
    • The license for the subtle dependency is provided in the NOTICE file in this repository. When redistributing, retain the NOTICE contents as required by that license.