Authentication guide - Sure Docs (draft)

Overview

This guide covers all authentication features including OIDC, OAuth2, SAML 2.0, database-backed provider management, JIT provisioning, role mapping, user management, and audit logging.

Configuration methods

Database-backed providers (recommended)

Manage providers through the admin UI without server restarts:

AUTH_PROVIDERS_SOURCE=db

Benefits:

Changes take effect immediately
No server restarts required
Web-based configuration at /admin/sso_providers
Audit trail for all changes

YAML-based providers (legacy)

Configure providers in config/auth.yml. Requires server restart for changes.

We recommend migrating to database-backed providers. See the migration section below.

OIDC configuration

Supported providers

OIDC works with any compliant provider:

Google Workspace
Microsoft Entra ID (Azure AD)
Okta
Auth0
Keycloak
Authentik
GitLab

Basic OIDC setup

Create OAuth client in your IdP

Configure the redirect URI shown for the provider in Sure. For a provider with the ID authentik, use:

https://yourdomain.com/auth/authentik/callback

Add provider in admin UI

Navigate to /admin/sso_providers and click Add Provider:

Strategy: openid_connect
Issuer URL: https://accounts.google.com
Client ID: your-client-id
Client Secret: your-client-secret
Scopes: openid profile email

Configure role mapping

Set default roles and group mappings (optional)

Test the integration

Use the test login flow to verify configuration

Multiple OIDC providers

Configure multiple providers simultaneously (e.g., Keycloak + Authentik):

# config/auth.yml
providers:
  - id: "keycloak"
    strategy: "openid_connect"
    name: "keycloak"
    label: "Sign in with Keycloak"
    issuer: <%= ENV["OIDC_KEYCLOAK_ISSUER"] %>
    client_id: <%= ENV["OIDC_KEYCLOAK_CLIENT_ID"] %>
    client_secret: <%= ENV["OIDC_KEYCLOAK_CLIENT_SECRET"] %>

  - id: "authentik"
    strategy: "openid_connect"
    name: "authentik"
    label: "Sign in with Authentik"
    issuer: <%= ENV["OIDC_AUTHENTIK_ISSUER"] %>
    client_id: <%= ENV["OIDC_AUTHENTIK_CLIENT_ID"] %>
    client_secret: <%= ENV["OIDC_AUTHENTIK_CLIENT_SECRET"] %>

Each provider must have a unique name field, which determines the callback URL path. For example, a provider named authentik uses https://your-domain.com/auth/authentik/callback.

OAuth2 configuration

Use OAuth2 for providers without OIDC support (GitHub, GitLab, Discord, Slack).

GitHub example

Create OAuth App

Go to GitHub Settings → OAuth Apps → New OAuth AppCallback URL:

https://your-domain.com/auth/github/callback

Configure in admin UI

Strategy: oauth2
Authorization URL: https://github.com/login/oauth/authorize
Token URL: https://github.com/login/oauth/access_token
User Info URL: https://api.github.com/user
Client ID: [your-client-id]
Client Secret: [your-client-secret]
Scopes: user:email

Token endpoint authentication

The application supports multiple authentication methods:

client_secret_post (default): Send credentials in request body
client_secret_basic: Send credentials in Authorization header

SAML 2.0 configuration

Service Provider metadata

Your application provides SAML metadata at:

https://your-domain.com/auth/saml/[provider-id]/metadata

Okta SAML setup

Create SAML application

In Okta admin console:

Go to Applications → Create App Integration
Select SAML 2.0

Configure SAML settings

Single sign on URL: https://your-domain.com/auth/saml/okta/callback
Audience URI (SP Entity ID): https://your-domain.com/auth/saml/okta
Name ID format: EmailAddress
Application username: Email

Configure attribute statements

email: user.email
firstName: user.firstName
lastName: user.lastName
groups: appuser.groups

Get IdP metadata

Copy:

Identity Provider Single Sign-On URL
Identity Provider Issuer
X.509 Certificate

Configure in admin UI

Strategy: saml
SSO URL: [from Okta]
Entity ID: [from Okta]
Certificate: [paste X.509 certificate]

Azure AD SAML setup

Create enterprise application

Go to Microsoft Entra ID → Enterprise applications
Click New application → Create your own application
Select Integrate any other application (Non-gallery)

Configure SAML

Identifier (Entity ID): https://your-domain.com/auth/saml/azure
Reply URL (ACS URL): https://your-domain.com/auth/saml/azure/callback
Sign on URL: https://your-domain.com
Logout URL: https://your-domain.com/auth/saml/azure/logout

Configure attributes

email: user.mail
givenname: user.givenname
surname: user.surname
groups: user.groups

Download metadata

Download Certificate (Base64) and copy Login URL and Azure AD Identifier

Database-backed provider management

Admin UI features

Access at /admin/sso_providers:

Add, edit, delete providers without server restarts
Enable/disable providers with a toggle
Test login flows before enabling
View callback URLs with copy button
Encrypted storage of client secrets
Audit trail of all changes

Security features

Client secrets encrypted at rest using Rails 7.2 ActiveRecord Encryption
Rate limiting: 10 requests/minute per IP on admin endpoints
Discovery endpoint validation for OIDC providers
Issuer validation to prevent impersonation attacks
Super admin role required for provider management

Seeding providers from YAML

Migrate existing YAML configuration to database:

# Dry run (preview changes)
DRY_RUN=true rails sso_providers:seed

# Apply changes
rails sso_providers:seed

# List all providers
rails sso_providers:list

Migration workflow

Backup configuration

cp config/auth.yml config/auth.yml.backup

Run migrations

rails db:migrate

Seed providers

DRY_RUN=true rails sso_providers:seed
rails sso_providers:seed

Enable database source

AUTH_PROVIDERS_SOURCE=db

Restart application

docker-compose restart app

Verify

Check logs for: [ProviderLoader] Loaded N provider(s) from database

AUTH_LOCAL_LOGIN_ENABLED=false

Behavior:

Email/password form hidden
POST /sessions with local credentials blocked
Password reset routes disabled
/password/edit (self-service password change) is blocked — users are redirected away and cannot set a local password while local login is disabled
Users must authenticate via SSO

Emergency admin override

Allow super admins to log in locally during IdP outages:

AUTH_LOCAL_LOGIN_ENABLED=false
AUTH_LOCAL_ADMIN_OVERRIDE_ENABLED=true

Behavior:

Login page shows email/password form with admin-only note
Super admins can log in with local passwords
Super admins can still access /password/edit and set a local password
Regular users are blocked from the password change page and redirected away
Override logins are logged

JIT user provisioning

Provisioning modes

# Create new accounts on first SSO login (default)
AUTH_JIT_MODE=create_and_link

# Only link to existing users, no account creation
AUTH_JIT_MODE=link_only

Domain restrictions

# Allow any verified email domain
ALLOWED_OIDC_DOMAINS=""

# Restrict to specific domains
ALLOWED_OIDC_DOMAINS="example.com,corp.com"

When set, JIT account creation is only allowed for emails from listed domains. Applies to all SSO providers.

Default roles

Configure in admin UI under Role Mapping:

Default Role: Assigned to all JIT-created users (e.g., member)
Group Mappings: Map IdP groups to application roles

When a JIT login creates a new family, the user who creates it is assigned the admin role for that family regardless of the default role setting. Super admin accounts retain their elevated defaults. This ensures the first user of a new family always has the access needed to configure it.

Role mapping

Group-to-role mapping

Map identity provider groups to application roles:

{
  "mappings": [
    {
      "group": "Platform-Admins",
      "role": "super_admin"
    },
    {
      "group": "Team-Leads",
      "role": "admin"
    },
    {
      "group": "Everyone",
      "role": "member"
    }
  ]
}

Mapping is case-sensitive. When a user belongs to multiple groups, the highest role wins (super_admin > admin > member).

OIDC group mapping

Ensure your OIDC provider includes groups:

Scopes: openid profile email groups

Configure your IdP to include groups in the ID token or userinfo response.

SAML attribute mapping

Configure group attribute in SAML provider:

<Attribute Name="groups">
  <AttributeValue>admin-group</AttributeValue>
  <AttributeValue>developer-group</AttributeValue>
</Attribute>

Set the attribute name in provider settings:

Group attribute: groups

Role synchronization

Roles are synchronized on every login:

Fetch current groups from IdP
Apply group-to-role mappings
Update user’s roles
Remove roles no longer mapped

Administrators can manually trigger sync at /admin/users → Sync Roles from SSO.

User management

Admin interface

Access at /admin/users:

View all users with roles, auth methods, last login
Search and filter by role, provider, status
View connected SSO accounts
Manage user roles manually
Suspend/reactivate/delete users
View authentication history

Connected accounts

Users can manage their own connected accounts at /settings/security under Connected Accounts:

View all connected SSO providers with the last-used timestamp
Connect additional providers by signing in with them
Disconnect a provider using the Disconnect button

Safety guard for disconnecting: Sure prevents a user from disconnecting their last SSO provider when they have no local password set. The disconnect button is hidden in that case, and a warning is shown prompting the user to set a password first. If the user has either a second SSO provider connected or a local password, disconnecting proceeds and the event is recorded in the SSO audit log as an unlink event. Deactivate user: Immediately cut off all access without removing data. All web sessions are destroyed, all OAuth tokens and API keys are revoked, and every subsequent login attempt is rejected with HTTP 401.

/admin/users → Actions popover → Deactivate User

Reactivate user: Restore access. The user must log in again; existing sessions and tokens are not restored.

/admin/users → Actions popover → Reactivate User

Delete user: Permanently remove (cannot be undone)

/admin/users → Actions popover → Delete User → Type email to confirm

Sync roles: Force role synchronization from IdP

/admin/users → Actions popover → Sync Roles from SSO

Audit logging

Event types

Access logs at /admin/sso_audit_logs: Authentication events:

login: Successful SSO login
login_failed: Failed login attempt
logout: User logout
logout_idp: RP-initiated federated logout
link: SSO account linked to user
unlink: SSO account unlinked
jit_account_created: New account created via JIT provisioning

Query via console:

SsoAuditLog.by_event("login").recent.limit(50)
SsoAuditLog.by_event("login_failed").where("created_at > ?", 24.hours.ago)

Log retention

Standard: 90 days in database
Extended: 1 year (database + archive)
Compliance: 7 years (archive storage)

Monitoring

Set up alerts for:

Multiple failed login attempts (brute force detection)
Provider configuration changes
Unusual login locations
Role escalations

Troubleshooting

YAML mode:

Check required environment variables are set (OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET)

DB mode:

Verify provider is enabled in /admin/sso_providers
Check AUTH_PROVIDERS_SOURCE=db is set
Review application logs for provider loading messages

Discovery endpoint validation fails

When adding an OIDC provider:

Ensure issuer URL is correct and accessible
Check firewall rules allow outbound HTTPS
Verify issuer returns valid JSON with issuer field
For self-signed certificates, configure SSL verification

Callback URL mismatch

Each provider requires exact callback URL match: Format: https://yourdomain.com/auth/<provider_name>/callback Examples:

Keycloak: https://yourdomain.com/auth/keycloak/callback
Authentik: https://yourdomain.com/auth/authentik/callback
Google Workspace: https://yourdomain.com/auth/google/callback

The callback URL is shown in admin UI when editing a provider (with copy button). Use that exact value in your identity provider. Older examples that use /auth/openid_connect/callback only apply to a legacy provider whose name is literally openid_connect.

Groups not syncing

Add groups scope to OIDC configuration
Verify IdP includes groups in token/assertion
Check group attribute name matches IdP configuration
Review audit logs to see what groups are received
Some IdPs require additional configuration to include groups

`POST /api/v1/auth/sso_create_account` returns “account already exists”

When a mobile SSO account creation attempt conflicts with an existing record (for example, the same email address or identity is already registered), the API returns HTTP 422 with:

{ "errors": ["An account or sign-in identity with these details already exists"] }

This is a generic message that does not expose internal database index names or field values. To resolve, have the user sign in with the existing account and link the SSO identity from Settings → Security → Connected Accounts instead.

Security considerations

Encryption

Client secrets encrypted at rest using Rails 7.2 ActiveRecord Encryption
In self-hosted mode, encryption keys are derived from SECRET_KEY_BASE unless you set dedicated ACTIVE_RECORD_ENCRYPTION_* keys
Keep the same SECRET_KEY_BASE for the lifetime of an existing instance. Changing it changes the derived encryption keys and can make existing encrypted fields, including user email lookups, unreadable.
For additional security, set custom encryption keys via ACTIVE_RECORD_ENCRYPTION_* variables
If you enable custom keys on an existing self-hosted instance, run bin/rails security:backfill_encryption once to rewrite older plaintext values
If users suddenly see “invalid username or password” after encryption changes, restore the previous SECRET_KEY_BASE or previous ACTIVE_RECORD_ENCRYPTION_* values first, then rerun the backfill task if you intentionally moved to dedicated keys.

TOTP one-time use

Each TOTP code is accepted only once. When a user signs in with a code, Sure records the time step of that code and rejects any subsequent use of the same step—including concurrent requests that arrive at the same time. A code seen over the shoulder, captured by a proxy, or relayed by a phishing page cannot be replayed within its validity window. The time step is claimed atomically with a conditional database update, so two simultaneous requests using the same code can never both succeed. Setting up or disabling two-factor authentication clears the recorded time step.

Issuer validation

OIDC identities store the issuer claim from ID token
On subsequent logins, issuer is verified against configured provider
Prevents issuer impersonation attacks

Admin access

SSO provider management requires super_admin role
Regular admin users (family admins) cannot access /admin/sso_providers
All provider changes logged with user ID

Log filtering

Sure filters sensitive values from request logs so they never appear in log output, even when verbose parameter logging is on. The following parameters are always redacted:

Passwords, tokens, keys, and secrets (standard Rails defaults)
One-time codes: MFA TOTP codes, backup codes, OAuth and bank authorization codes, and the desktop SSO exchange code (the code parameter, anchored — currency_code, country_code, and postal_code remain readable)
Mobile SSO linking code (linking_code) and invitation code (invite_code)
SimpleFIN access URL (access_url)
Device authorization flow fields (device_code, user_code, verification_uri_complete)
FinanceKit publisher credential and event fields

These are configured in config/initializers/filter_parameter_logging.rb.

Rate limiting

Sure uses Rack::Attack to throttle credential-checking endpoints in production and staging. Rate limiting is disabled in development and test environments to avoid flakiness. Every endpoint that checks a password, TOTP code, or backup code is throttled by both IP address and a credential-identifying discriminator (email address, or the session-bound user ID for MFA step-up). Both throttles must pass — an attacker cannot bypass one by rotating IPs against a single target or by spraying many addresses from one IP.

Endpoint	Throttle keys	Limit
`POST /sessions` — web login	IP + email	10 req/min each
`POST /mfa/verify` — TOTP and backup codes	IP + session user ID	10 req/min each
`POST /password_reset` — password reset	IP + email	10 req/min each
`POST /oidc_account/create_link` — SSO identity linking	IP + email	10 req/min each
`POST /api/v1/auth/login` — mobile/API login	IP + email	10 req/min each
`POST /api/v1/auth/sso_link` — mobile SSO identity linking	IP + email	10 req/min each
`PATCH /password` — self-service password change	IP + user ID	10 req/min each
`POST /oauth/token` — OAuth token endpoint	IP	10 req/min
`POST /register` — OAuth registration	IP	10 req/min
`POST /mfa/webauthn_options`, `/mfa/verify_webauthn`, `/sessions/passkey` — WebAuthn MFA	IP	10 req/min
`POST /sessions/passkey_options` — passkey challenge (conditional mediation)	IP	30 req/min
`POST /settings/webauthn_credentials/options` — passkey registration code check	User ID	10 req/min
`POST /settings/webauthn_credentials` — passkey registration code spend	User ID	10 req/min
Admin endpoints (`/admin/*`)	IP	10 req/min

Requests that exceed a limit receive HTTP 429. The throttle also matches format-suffixed paths (e.g. /sessions.json) so scripted clients cannot bypass it by appending a file extension. For JSON API requests (Content-Type: application/json), the email discriminator is extracted from the request body before Rails parses parameters. The body is rewound after reading so the controller still receives it intact. Non-rewindable input streams (Rack 3 servers that do not support rewind) skip the email throttle and fall back to IP-only throttling for those requests. The password-change throttle uses the signed-in user’s ID (resolved from the session cookie) rather than an email address, since the endpoint requires an active session. Requests without a valid session are redirected to sign in and do not spend either budget. During an admin impersonation, the throttle is keyed on the impersonated user’s ID — the same user whose password is being checked — so the impersonating admin’s sessions do not gain extra guesses.

Example configurations

Default hybrid (local + SSO)

AUTH_LOCAL_LOGIN_ENABLED=true
AUTH_LOCAL_ADMIN_OVERRIDE_ENABLED=false
AUTH_JIT_MODE=create_and_link
ALLOWED_OIDC_DOMAINS=""

Users can sign in with email/password or SSO. JIT account creation allowed for all verified emails.

Pure SSO-only

AUTH_LOCAL_LOGIN_ENABLED=false
AUTH_LOCAL_ADMIN_OVERRIDE_ENABLED=false

Email/password form hidden. Password reset disabled. SSO required for all users.

SSO-only with emergency admin override

AUTH_LOCAL_LOGIN_ENABLED=false
AUTH_LOCAL_ADMIN_OVERRIDE_ENABLED=true

Super admins can log in locally during IdP outages. Regular users must use SSO.

Link-only JIT + restricted domains

AUTH_JIT_MODE=link_only
ALLOWED_OIDC_DOMAINS="example.com,yourcorp.com"

SSO sign-ins can only link to existing users. New account creation disabled. Only specified domains allowed.

Advanced features

Request signing (SAML)

Generate key pair:

openssl req -x509 -newkey rsa:2048 -keyout private.key -out certificate.crt -days 365 -nodes

Enable in admin UI:

Toggle “Sign requests” to enabled
Paste private key content
Certificate automatically included in SP metadata

Custom attribute mapping

Map custom IdP attributes to application fields:

{
  "custom_mappings": {
    "employee_id": "externalId",
    "cost_center": "metadata.costCenter",
    "manager_email": "metadata.manager"
  }
}

Conditional role assignment

Assign roles based on multiple conditions:

{
  "conditions": [
    {
      "attribute": "department",
      "value": "Engineering",
      "groups": ["senior-engineers"],
      "role": "senior-developer"
    }
  ]
}

Role hierarchy

Define role hierarchies for automatic dependent roles:

{
  "hierarchy": {
    "admin": ["developer", "viewer"],
    "developer": ["viewer"]
  }
}

Best practices

Use OIDC when available

OIDC provides standardized user information and better security than OAuth2.

Enable database-backed providers

Manage providers through admin UI for easier updates and no downtime.

Implement role mapping

Use group-to-role mapping to centralize access control in your IdP.

Monitor audit logs

Regularly review authentication events and failed login attempts.

Rotate secrets regularly

Periodically rotate client secrets and update in admin UI.

Test before enabling

Always test provider configuration before enabling for all users.

Next steps

Quickstart

Get started with SSO in 5 minutes

User management

Manage users and connected accounts

​Overview

​Configuration methods

​Database-backed providers (recommended)

​YAML-based providers (legacy)

​OIDC configuration

​Supported providers

​Basic OIDC setup

​Multiple OIDC providers

​OAuth2 configuration

​GitHub example

​Token endpoint authentication

​SAML 2.0 configuration

​Service Provider metadata

​Okta SAML setup

​Azure AD SAML setup

​Database-backed provider management

​Admin UI features

​Security features

​Seeding providers from YAML

​Migration workflow

​Local login control

​Disable local login (SSO-only)

​Emergency admin override

​JIT user provisioning

​Provisioning modes

​Domain restrictions

​Default roles

​Role mapping

​Group-to-role mapping

​OIDC group mapping

​SAML attribute mapping

​Role synchronization

​User management

​Admin interface

​Connected accounts

​User actions

​Audit logging

​Event types

​Log retention

​Monitoring

​Troubleshooting

​Provider not appearing on login page

​Discovery endpoint validation fails

​Callback URL mismatch

​Groups not syncing

​POST /api/v1/auth/sso_create_account returns “account already exists”

​Security considerations

​Encryption

​TOTP one-time use

​Issuer validation

​Admin access

​Log filtering

​Rate limiting

​Example configurations

​Default hybrid (local + SSO)

​Pure SSO-only

​SSO-only with emergency admin override

​Link-only JIT + restricted domains

​Advanced features

​Request signing (SAML)

​Custom attribute mapping

​Conditional role assignment

​Role hierarchy

​Best practices

​Next steps

Quickstart

User management

Overview

Configuration methods

Database-backed providers (recommended)

YAML-based providers (legacy)

OIDC configuration

Supported providers

Basic OIDC setup

Multiple OIDC providers

OAuth2 configuration

GitHub example

Token endpoint authentication

SAML 2.0 configuration

Service Provider metadata

Okta SAML setup

Azure AD SAML setup

Database-backed provider management

Admin UI features

Security features

Seeding providers from YAML

Migration workflow

Local login control

Disable local login (SSO-only)

Emergency admin override

JIT user provisioning

Provisioning modes

Domain restrictions

Default roles

Role mapping

Group-to-role mapping

OIDC group mapping

SAML attribute mapping

Role synchronization

User management

Admin interface

Connected accounts

User actions

Audit logging

Event types

Log retention

Monitoring

Troubleshooting

Provider not appearing on login page

Discovery endpoint validation fails

Callback URL mismatch

Groups not syncing

`POST /api/v1/auth/sso_create_account` returns “account already exists”

Security considerations

Encryption

TOTP one-time use

Issuer validation

Admin access

Log filtering

Rate limiting

Example configurations

Default hybrid (local + SSO)

Pure SSO-only

SSO-only with emergency admin override

Link-only JIT + restricted domains

Advanced features

Request signing (SAML)

Custom attribute mapping

Conditional role assignment

Role hierarchy

Best practices

Next steps