Skip to main content

​
Overview

Applad’s authentication system supports multiple providers (email, OAuth, SAML), multi-factor authentication, and three multi-tenancy models — all configured in auth/auth.yaml.

​
Basic Configuration

auth/auth.yaml
session:
  duration: 86400           # 24 hours
  refresh: true
  refresh_duration: 2592000 # 30 days
  rotate_on_refresh: true

password:
  min_length: 10
  require_uppercase: true
  require_number: true
  require_symbol: true
  hashing: "argon2id"
  argon2id:
    memory: 65536
    iterations: 3
    parallelism: 4

brute_force:
  enabled: true
  max_attempts: 5
  lockout_duration: 900     # 15 minutes
  progressive: true

​
Authentication Providers

​
Email Authentication

auth/auth.yaml
providers:
  - type: "email"
    enabled: true
    verification_required: true
    verification_expiry: 86400  # 24 hours

​
OAuth Providers

Supported OAuth providers: Google, GitHub, Microsoft, Apple, Facebook, Twitter.
auth/auth.yaml
providers:
  - type: "oauth"
    name: "google"
    enabled: true
    client_id: ${GOOGLE_CLIENT_ID}
    client_secret: ${GOOGLE_CLIENT_SECRET}
    scopes: ["email", "profile"]
    pkce: true

  - type: "oauth"
    name: "github"
    enabled: true
    client_id: ${GITHUB_CLIENT_ID}
    client_secret: ${GITHUB_CLIENT_SECRET}
    scopes: ["user:email"]
    pkce: true
1

Create OAuth application

Register your application with the OAuth provider:
2

Configure redirect URIs

Set the OAuth callback URL to:
https://your-instance.com/auth/callback/{provider}
3

Set credentials

applad secrets set GOOGLE_CLIENT_ID
applad secrets set GOOGLE_CLIENT_SECRET

​
SAML Authentication

For enterprise SSO with Okta, Auth0, Azure AD, etc.
auth/auth.yaml
providers:
  - type: "saml"
    name: "okta"
    enabled: false
    metadata_url: ${OKTA_METADATA_URL}
    signed_requests: true

​
Phone Authentication

auth/auth.yaml
providers:
  - type: "phone"
    enabled: false
    verification_expiry: 300  # 5 minutes

​
Multi-Factor Authentication

auth/auth.yaml
mfa:
  enabled: true
  required: false  # Set to true to enforce MFA for all users
  methods:
    - type: "totp"
      enabled: true
    - type: "webauthn"
      enabled: true
      relying_party: "myapp.com"
    - type: "backup_codes"
      enabled: true
      count: 10

​
MFA Methods

  • TOTP — Time-based one-time passwords (Google Authenticator, Authy)
  • WebAuthn — Hardware security keys (YubiKey, Touch ID, Face ID)
  • Backup Codes — Single-use recovery codes

​
Multi-Tenancy

Applad supports three multi-tenancy models. Choose one per project:

​
Row-Level Isolation

Shared database, shared schema. A tenant_field column is added to every table, with row-level filters enforcing isolation.
auth/auth.yaml
multi_tenancy:
  enabled: true
  model: "row"
  tenant_field: "org_id"
Best for: Most SaaS products — lowest cost, simplest to operate.

​
Schema-Level Isolation

Shared database, separate schemas. Each tenant gets their own Postgres schema. Tables are identical in structure but physically isolated.
auth/auth.yaml
multi_tenancy:
  enabled: true
  model: "schema"
  schema_pattern: "tenant_{slug}"  # tenant_{id} | tenant_{slug}
Best for: Regulated industries requiring stronger isolation.

​
Database-Level Isolation

Separate database per tenant. Each tenant gets their own connection. Maximum isolation.
auth/auth.yaml
multi_tenancy:
  enabled: true
  model: "database"
  database_url_field: "database_url"  # Field on tenant record
Best for: Enterprise with strict data residency or contractual isolation requirements.

​
Session Management

auth/auth.yaml
session:
  duration: 86400           # Access token lifetime (24 hours)
  refresh: true
  refresh_duration: 2592000 # Refresh token lifetime (30 days)
  rotate_on_refresh: true   # Issue new refresh token on each use

tokens:
  access_token_expiry: 900        # 15 minutes
  refresh_token_expiry: 2592000   # 30 days
  rotation: true
  revocation_on_password_change: true
  revocation_on_suspicious_activity: true

​
Managing Users

​
List users

applad auth users list

​
View user details

applad auth users get <user-id>
Shows profile, role, MFA status, linked OAuth providers, and recent auth events.

​
Delete a user

applad auth users delete <user-id>
Soft-deletes the user. They can no longer sign in, but their data is preserved. Active sessions are immediately revoked.

​
Ban a user

applad auth users ban <user-id>
Immediately revokes all sessions and prevents future sign-in attempts.

​
Purge user data (GDPR/CCPA)

applad auth users purge <user-id>
Permanently deletes all data associated with a user across all tables, storage, messaging history, analytics, and auth records. Generates a deletion report. Cannot be undone.

​
Export user data (GDPR/CCPA)

applad auth export --user <user-id>
Generates a complete data export containing all personal data across all tables, storage files, messaging, and auth records. Output is a structured zip archive.

​
Session Management

​
List active sessions

applad auth sessions list
Shows who is signed in, from which device/IP, when the session started, and when it expires.

​
Revoke a session

applad auth sessions revoke <session-id>

​
Revoke all sessions for a user

applad auth sessions revoke --user <user-id>
Use this if you suspect an account has been compromised.

​
Security Features

​
Brute Force Protection

auth/auth.yaml
brute_force:
  enabled: true
  max_attempts: 5
  lockout_duration: 900  # 15 minutes
  progressive: true      # Increase lockout duration on repeated failures

​
Password Requirements

auth/auth.yaml
password:
  min_length: 10
  require_uppercase: true
  require_number: true
  require_symbol: true
  hashing: "argon2id"  # Most secure hashing algorithm

​
Environment Variables

Auth configuration requires these environment variables:
.env
# OAuth — Google
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=  # [SECRET] applad secrets set GOOGLE_CLIENT_SECRET

# OAuth — GitHub
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=  # [SECRET] applad secrets set GITHUB_CLIENT_SECRET

# SAML — Okta (optional)
OKTA_METADATA_URL=

​
Testing Auth Providers

Check that auth providers are configured correctly: 
applad auth providers list
Shows all providers, whether they’re enabled, and any configuration issues.

​
Example: Complete Auth Configuration

auth/auth.yaml
session:
  duration: 86400
  refresh: true
  refresh_duration: 2592000
  rotate_on_refresh: true

password:
  min_length: 10
  require_uppercase: true
  require_number: true
  require_symbol: true
  hashing: "argon2id"

brute_force:
  enabled: true
  max_attempts: 5
  lockout_duration: 900
  progressive: true

mfa:
  enabled: true
  required: false
  methods:
    - type: "totp"
      enabled: true
    - type: "webauthn"
      enabled: true
      relying_party: "myapp.com"
    - type: "backup_codes"
      enabled: true
      count: 10

providers:
  - type: "email"
    enabled: true
    verification_required: true
    verification_expiry: 86400

  - type: "oauth"
    name: "google"
    enabled: true
    client_id: ${GOOGLE_CLIENT_ID}
    client_secret: ${GOOGLE_CLIENT_SECRET}
    scopes: ["email", "profile"]
    pkce: true

  - type: "oauth"
    name: "github"
    enabled: true
    client_id: ${GITHUB_CLIENT_ID}
    client_secret: ${GITHUB_CLIENT_SECRET}
    scopes: ["user:email"]
    pkce: true

multi_tenancy:
  enabled: true
  model: "row"
  tenant_field: "org_id"

tokens:
  access_token_expiry: 900
  refresh_token_expiry: 2592000
  rotation: true
  revocation_on_password_change: true
  revocation_on_suspicious_activity: true

​
Next Steps

Storage

Configure file storage with buckets and permissions

Functions

Create serverless functions for backend logic

Build docs developers (and LLMs) love

Get started for freeTalk to us