Authentication Modes

Understand the difference between Standalone and Federated authentication.

Updated Jan 21, 2026 Edit this page

Authentication Modes

9: ACT supports two primary authentication modes: Standalone and Federated. This allows you to choose between a fully self-contained installation or integration with an external Identity Provider (IdP). 10: 11: 12: User Request 13: │ 14: ▼ 15: [ Has Token? ] 16: / \ 17: No Yes 18: │ │ 19: ▼ ▼ 20: [Auth Mode?] [Validate Token] 21: / \ / \ 22: Standalone Federated Crypto Check Remote JWKS 23: │ │ │ │ 24: ▼ ▼ ▼ ▼ 25: [Login UI] [Redirect] [Access App] [Access App] 26: 27: 28: ## Standalone Mode (Local Database)

This is the default mode when no external authentication URL is provided. It is ideal for small teams or single-node installations where simplicity is preferred.

  • How it works: ACT maintains its own user database (local_user table).
  • Session Security: Sessions are managed via JWTs (JSON Web Tokens) signed with your ACT_MASTER_KEY.
  • First-to-Claim: On new installations, a Setup Token is required to create the first administrator account.
  • Activation: Standalone mode is active if the AUTHOS_URL environment variable is not set.

Configuration

# Standalone mode (Default)
DATABASE_URL=sqlite:///var/lib/act/act.db
ACT_MASTER_KEY=... # 64-character hex key

Federated Mode (AuthOS Integration)

Federated mode allows you to delegate authentication to an AuthOS instance. This is recommended for enterprise environments or when you want to use Single Sign-On (SSO) across multiple ACT instances.

  • How it works: ACT does not store passwords locally. It validates tokens provided by your AuthOS instance using JWKS (JSON Web Key Sets).
  • User Sync: Users are automatically mapped to ACT roles based on their AuthOS groups/roles.
  • Activation: Federated mode is automatically activated when AUTHOS_URL is configured.

Configuration

# Federated mode
DATABASE_URL=sqlite:///var/lib/act/act.db
ACT_MASTER_KEY=...
AUTHOS_URL=https://sso.yourdomain.com
AUTHOS_AUDIENCE=act

Switching Modes

[!WARNING] Switching from Standalone to Federated mode (or vice versa) will invalidate all current sessions. In Standalone mode, you must have local users created. In Federated mode, users must exist in your AuthOS instance.

Master Key & Security

In both modes, the ACT_MASTER_KEY is critical. It is used to:

  1. Encrypt/Decrypt sensitive service data (environment variables, private keys).
  2. (Standalone only) Sign session JWTs.

Always keep your Master Key safe. If you lose it, your data remains encrypted and unrecoverable in the database.