DOCSEARCHbyAlgolia
Submit Docs

Rauthy Documentation

repository·main·Indexed 23 days ago

https://github.com/sebadob/rauthy

Rauthy is a high-performance Single Sign-On (SSO) Identity & Access Management (IAM) system written in Rust. It supports OpenID Connect (OIDC), OAuth 2, and PAM logins, featuring MFA, passwordless authentication via FIDO2/Webauthn, and high-availability deployments. The ecosystem includes rauthy-client, a modular library for integrating authentication into web frameworks like actix-web and axum, with support for SCIM v2, backchannel logout, and the Device Authorization Grant flow.

Tokens
68.2K
Snippets
151
Records
322
Agent score
75%

What's inside Rauthy

  1. Overview of Rauthy

    main

    Rauthy is a Single Sign-On (SSO) Identity & Access Management (IAM) solution. It provides authentication and authorization capabilities using the following protocols and methods:

    • OpenID Connect (OIDC)
    • OAuth 2
    • PAM (Pluggable Authentication Modules) Logins

    It is designed to be secure by default, supporting MFA, passwordless login, and various protection mechanisms like brute-force and credential stuffing mitigation.

  2. Overview of rauthy-client

    main

    The rauthy-client is a minimal and safe-by-default client library designed specifically for the Rauthy project. While any generic OIDC client can be used with Rauthy, this library provides a production-ready setup with minimal overhead and secure default values optimized for Rauthy users.

    Examples for integration with actix-web, axum, or generic frameworks can be found in the repository's examples directory. For advanced features like backchannel logout or SCIM, refer to the axum example.

  3. Overview of Rauthy Identity Provider

    main

    Rauthy is a lightweight, high-performance Identity Provider (IdP) written in Rust. It supports OpenID Connect (OIDC), OAuth 2, and PAM (Pluggable Authentication Modules).

    Key characteristics include:

    • Security-First: Secure defaults (e.g., ed25519 for token signing and S256 PKCE flow), MFA support, and protection against brute-force, credential stuffing, and DoS attacks.
    • Efficiency: Low resource footprint suitable for hardware like Raspberry Pi, utilizing extensive caching.
    • Scalability: Supports high-availability (HA) deployments and can scale to millions of users.
    • Database Options: Uses Hiqlite (embedded) by default for zero-setup operation, but supports Postgres for externalized database needs.
    • Versatility: Supports IoT/headless devices via the OAuth 2 Device Authorization Grant flow and provides PAM/NSS modules for Linux host/SSH management.

  4. What is Rauthy?

    main

    Rauthy is a lightweight Identity Provider (IdP) written in Rust that supports OpenID Connect (OIDC), OAuth 2, and PAM. It is designed to be resource-efficient, capable of running on low-power hardware like a Raspberry Pi, while scaling to millions of users.

    Key characteristics include:

    • Secure by Default: Uses modern defaults like ed25519 for token signing and S256 PKCE flow for new OIDC clients.
    • Database Options: Uses Hiqlite by default (embedded, no external dependency required) or supports Postgres for existing infrastructure.
    • High Availability: Supports HA deployments using either Hiqlite's embedded HA cache/persistence or Postgres.
    • Authentication Flows: Supports traditional passwords, FIDO2/Webauthn Passkeys, and Passkey-only accounts (requiring User Verification/UV).
    • IoT & Headless Support: Includes support for the OAuth 2 Device Authorization Grant (device_code) flow.

  6. Understand IP Blacklist Persistence and Expiry

    main

    Persistence

    The blacklist is currently in-memory only. If Rauthy restarts, all blacklisted IPs are lost unless you have configured cluster.cache_storage_disk = true.

    Note: The blacklisting middleware is positioned at the very beginning of the API stack (before access logging) to minimize resource usage during an attack.

    Expiry

    All blacklisting entries have an expiry. Once the set time has passed, the entry is fully removed from Rauthy and the IP is no longer blocked.

  7. Understand PAM User lifecycle and constraints

    main

    A PAM User is a specialized identity linked to a "real" user. Once created, a PAM User is immutable and automatically bound to the lifetime of the underlying real user.

    Key constraints and characteristics:

    • Immutability: You cannot change the username or easily delete and recreate it after creation. This prevents accidental leakage of leftover files.
    • Unique Identifiers: A uid is globally unique across all hosts (similar to gids for groups), making it reliable for managing NFS shares.
    • Modifiable Fields: The only field that can be changed after creation is the shell (which defaults to /bin/bash).
    • Username Requirements: The additional username must follow Linux username regexes. While email addresses might technically work in some scenarios, they are discouraged as they can cause errors in commands (e.g., ssh my.user@example.com@host).
    • Admin Control: Users cannot choose their own Linux usernames. This must be performed by a Rauthy admin to prevent users from claiming reserved system names like root, postgres, or systemd.

  8. Use Forward Authentication to secure legacy applications

    main

    Forward Authentication allows you to secure applications running behind a reverse proxy (like Traefik or Nginx) that do not natively support OIDC.

    When a request is intercepted and forwarded to Rauthy's /auth/v1/oidc/forward_auth endpoint, Rauthy checks for a valid Bearer token in the Authorization header. If valid, Rauthy returns an HTTP 200 Ok and can append user information to the request via custom headers. This allows downstream applications to read user identity information directly from headers.

    Warning: A direct token validation inside your downstream application via a native OIDC client should ALWAYS be preferred. Use Forward Auth only as a last resort due to security pitfalls in reverse proxy configurations.

  9. Configure Events and Alerting

    main

    Rauthy features an integrated Event and Alerting system.

    • Event Generation: Events are triggered during various system scenarios.
    • Notification Channels: Depending on the configured severity level, events can be sent via E-Mail, Matrix, or Slack.
    • Monitoring: Events are visible in real-time within the Admin UI. Developers can also subscribe to the event stream to handle events externally based on custom business logic.

  10. Note on User List visibility for Group Admins

    main

    In Rauthy, Group Admins see the same (minified) user list as a full administrator. The user list is not filtered by group.

    This is a design choice for performance: the users table inlines roles and groups for fast logins, making database-side group filtering expensive. Security is enforced at the write level (the backend prevents any unauthorized modifications) rather than the read level. This allows a Group Admin to find any user and add them to a group they manage, even if that user was created by a different administrator.

  12. Enable High Availability (HA) mode in Rauthy

    main

    Rauthy supports High Availability (HA) using Hiqlite, which implements the Raft algorithm for consistency. In HA mode, all instances share a single HA cache layer for data like authentication codes.

    Key Considerations:

    • Scaling: The optimal number of replicas is 3, or 5 for higher resilience. Scaling beyond this may degrade write throughput.
    • Persistence: Even if using Postgres for your main database, you must provide a persistent volume for Rauthy instances. The Hiqlite cache is disk-backed (storing WAL logs and snapshots). Without a persistent volume, nodes must re-join the Raft cluster from scratch on every restart, increasing downtime.
    • Graceful Shutdown: HA clusters may take 15 to 30 seconds to shut down gracefully (e.g., during leader elections). Ensure your container runtime/orchestrator (like Kubernetes) is configured with a sufficiently long termination grace period.
    • Security: Do not expose Hiqlite ports to the public internet. Use cluster.nodes to configure them for internal communication.