Core authentication

SSO connections

Authalla supports multiple Single Sign-On (SSO) connection types to let your users authenticate with external identity providers.

Overview

SSO connections in Authalla fall into two categories:

  • Social login: OAuth-based providers like Google, GitHub, and Microsoft for consumer accounts. Users click a provider button on the login screen.
  • Enterprise SSO: Identity providers that authenticate users based on their email domain (OIDC or SAML). When a user enters an email with a configured domain, they're automatically redirected to the enterprise IdP.
flowchart TD
  userStarts[User starts login] --> entersEmail[User enters email]
  entersEmail --> domainCheck{Email domain has enterprise SSO?}
  domainCheck -->|Yes| redirectEnterprise[Redirect to enterprise IdP]
  domainCheck -->|No| showDefault[Show default login methods]
  showDefault --> socialButtons[Social login buttons]
  redirectEnterprise --> callback[Return to Authalla callback]
  callback --> oauth2Continue[Continue OAuth2 flow]

Shared concepts

Tenant domains and callback URLs

All SSO connections require callback/redirect URLs that tell the identity provider where to send users after authentication.

Your tenant domain determines these URLs:

  • Default: {tenant-id}.authalla.com
  • Custom domain: Your own domain (e.g., auth.yourcompany.com)

When you add a custom domain, all callback URLs automatically switch to use your custom domain. You must update your IdP configurations when this happens.

Email domain routing

Enterprise SSO connections (OIDC and SAML) use email domain routing. When a user enters an email address during login:

  1. Authalla extracts the domain (e.g., [email protected] → acme.com)
  2. Checks if any active enterprise connection is configured for that domain
  3. If found, redirects the user to that IdP instead of showing the default login screen

Each email domain can only be configured for one connection per tenant.

Connection statuses

Enterprise SSO connections have three statuses:

  • Active: Users with matching email domains are redirected to this IdP
  • Testing: Connection is configured but not yet active for users
  • Inactive: Connection is disabled

User provisioning and linking

When a user authenticates via SSO, Authalla:

  1. Looks up by external identity: Checks if this user has logged in with this provider before (using the provider's unique user ID)
  2. Looks up by email: If no external identity exists, checks for an existing user with the same email address
  3. Links or creates:
    • If a user exists and email is verified, links the external identity to that user
    • If a user exists but email is not verified, sends a verification email with a linking confirmation
    • If no user exists and registration is enabled, creates a new user account

On subsequent logins, user profile information (name, email) is synced from the IdP if "Sync User Attributes" is enabled.

Social login

Social login lets users sign in with popular OAuth providers: Google, GitHub, Microsoft, Facebook, X (Twitter), and LinkedIn.

Configuration

Navigate to the Admin UI → Tenants → Select your tenant → SSO tab to configure social login providers.

Required fields:

  • Provider type: Select from the supported providers
  • Client ID: OAuth client ID from the provider
  • Client Secret: OAuth client secret (encrypted at rest)

Redirect URI (shown in Admin UI):

https://{tenant-domain}/oauth2/social-login-callback

Copy this redirect URI and add it to your OAuth application settings in the provider's console (e.g., Google Cloud Console, GitHub OAuth Apps, etc.).

What users see

Social login buttons appear on your tenant's login page. Users click a provider button and are redirected to that provider for authentication.

Common issues

Custom domain changes: After activating a custom domain, update your OAuth app's redirect URI in each provider's console to use the new domain.

Missing email (GitHub, X): Some providers don't always return an email address. X (Twitter) requires elevated API access to provide email. GitHub fetches email in a separate API call, which may fail if the user hasn't made their email public. Authentication will fail if the provider doesn't provide an email.

Registration disabled: If your tenant doesn't allow registration (allow_registration = false), new users cannot sign up via social login. Only existing users can link social accounts.

Enterprise SSO (OIDC)

Enterprise OIDC SSO lets organizations authenticate users with their own identity providers (Azure AD / Entra ID, Okta, Google Workspace, or any generic OIDC provider).

Configuration

Navigate to Admin UI → Tenants → Select your tenant → SSO tab → Enterprise SSO (OIDC) to configure connections.

Required fields:

  • Connection name: Friendly identifier (e.g., "Acme Corp SSO")
  • Provider type: microsoft_entra, okta, google_workspace, or generic_oidc
  • Client ID: OAuth2 client ID from your IdP
  • Client Secret: OAuth2 client secret (encrypted at rest)
  • Email domains: Comma-separated list of domains that trigger this connection (e.g., acme.com, acme.co.uk)

Configuration modes:

  • Auto (recommended): Paste your IdP's discovery URL (e.g., https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration) and Authalla automatically fetches endpoints
  • Manual: Enter authorization endpoint, token endpoint, userinfo endpoint, and JWKS URI manually

Redirect URI (configure in your IdP):

https://{tenant-domain}/oauth2/enterprise-sso-callback

Discovery URLs by provider

Microsoft Entra ID:

https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

Okta:

https://{your-domain}.okta.com/.well-known/openid-configuration

Google Workspace:

https://accounts.google.com/.well-known/openid-configuration

What users experience

  1. User visits your app and clicks "Sign in"
  2. User enters their email address (e.g., [email protected])
  3. Authalla detects the email domain matches an enterprise SSO connection
  4. User is redirected to the IdP (e.g., Microsoft login page)
  5. After authenticating at the IdP, user returns to Authalla
  6. Authalla completes the OAuth2 authorization flow and logs the user into your app

Claim mappings

OIDC providers return user information as "claims" in the ID token or userinfo endpoint. Authalla maps these claims to user attributes:

  • sub: Unique user identifier (required)
  • email: User's email address (required)
  • name: Full display name
  • given_name: First name
  • family_name: Last name
  • groups: User's groups or roles

Default mappings by provider:

  • Microsoft Entra ID: Uses long claim names like http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • Okta: Uses short names like email, name, given_name
  • Google Workspace: Standard OIDC claims

If login fails (missing claims)

If authentication fails because email or sub is missing, check your IdP configuration:

  1. Ensure your IdP is configured to release the email and sub (or equivalent) claims.
  2. If your IdP uses different claim names, update the connection's claim mappings to match.
  3. Retry the login after saving changes.

Scopes

Default scopes: openid, email, profile

You can customize scopes in the connection settings if your IdP requires additional scopes.

Enterprise SSO (SAML)

Enterprise SAML SSO lets organizations authenticate users using SAML 2.0 identity providers.

Configuration

Navigate to Admin UI → Tenants → Select your tenant → SSO tab → Enterprise SSO (SAML) to configure connections.

Required fields:

  • Connection name: Friendly identifier (e.g., "Acme Corp SAML")
  • Provider type: azure_ad, okta_saml, or generic_saml
  • Email domains: Domains that trigger this connection (e.g., acme.com)

IdP configuration (from your identity provider):

  • IdP SSO URL: Single Sign-On URL where Authalla sends SAML requests
  • IdP Entity ID: Unique identifier for your IdP
  • IdP Certificate (X.509): Public certificate for verifying SAML assertions (PEM format)

Configuration methods:

  1. Metadata upload (easiest): Upload your IdP's metadata XML file to auto-fill all IdP fields
  2. Metadata URL: Paste your IdP's metadata URL (Authalla will parse it in the UI)
  3. Manual: Enter SSO URL, Entity ID, and certificate manually

Service Provider (SP) configuration

After creating a connection, Authalla generates SP configuration values you must provide to your IdP:

SP Entity ID:

urn:authalla:sp:{connection-id}

(Unique per connection, shown in Admin UI)

Assertion Consumer Service (ACS) URL:

https://{tenant-domain}/saml/acs

Sign-on URL (SP-initiated login):

https://{tenant-domain}/saml/{connection-id}

SP Metadata URL:

https://{tenant-domain}/saml/{connection-id}/metadata

Setting up with your IdP

Option 1: Metadata upload (recommended)

  1. Click "Download Metadata XML" in the Admin UI
  2. Upload the XML file to your IdP (Azure, Okta, etc.)
  3. Your IdP will automatically configure SP Entity ID and ACS URL

Option 2: Manual configuration

  1. Copy SP Entity ID and ACS URL from the Admin UI
  2. Enter them manually in your IdP's SAML configuration
  3. Set NameID format to "EmailAddress"

Provider-specific setup

Microsoft Entra ID:

  1. Go to Azure Portal → Microsoft Entra ID → Enterprise Applications
  2. Create a new application → "Integrate any other application"
  3. Go to Single sign-on → SAML
  4. Upload metadata file or paste SP Entity ID and ACS URL
  5. Download "Federation Metadata XML" and upload to Authalla

Okta:

  1. Go to Okta Admin Console → Applications → Create App Integration
  2. Select "SAML 2.0"
  3. Upload metadata file or enter SP Entity ID as "Audience URI" and ACS URL as "Single sign-on URL"
  4. Set Name ID format to "EmailAddress"
  5. Copy metadata URL from "Sign On" tab and paste in Authalla

What users experience

SP-initiated flow (most common):

  1. User enters email → redirected to IdP
  2. User authenticates at IdP
  3. IdP POSTs SAML response to https://{tenant-domain}/saml/acs
  4. Authalla validates the assertion and continues OAuth2 flow

IdP-initiated flow:

  1. User starts login from IdP portal
  2. IdP POSTs SAML response directly to Authalla
  3. Authalla validates and redirects to the configured default OAuth2 client (if set)

To enable IdP-initiated flow, set a "Default OAuth2 Client" in the connection settings.

Attribute mappings

SAML assertions contain attributes about the user. Authalla maps these to user fields:

Default mappings by provider:

Microsoft Entra ID:

  • email → http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • name → http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
  • given_name → http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
  • family_name → http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

Okta:

  • email → email
  • name → name
  • given_name → firstName
  • family_name → lastName

Generic SAML:

  • Standard attribute names (email, name, given_name, family_name)

You can customize attribute mappings in the connection settings if your IdP uses different attribute names.

Signing and encryption

Request signing: Disabled by default. Enable if your IdP requires signed SAML requests.

Assertion signing: Enabled by default. Authalla expects the IdP to sign assertions using the certificate you provided.

Encryption: Not currently supported (signing only).

Certificate management

Authalla generates an SP signing certificate when you create a connection. This certificate:

  • Is valid for 10 years
  • Is included in the SP metadata XML
  • Can be rotated via the Admin UI

To rotate the certificate:

  1. Click "Rotate Certificate" in the connection details
  2. Download the new metadata XML
  3. Upload it to your IdP immediately
  4. SSO will not work until the IdP has the new certificate

Single Logout (SLO)

Single Logout is not currently supported. Users log out via Authalla's standard logout endpoint (/oauth2/logout).

Troubleshooting

Domain mismatch errors

Error: "Email domain {domain} is not allowed for this SSO connection"

Cause: The user's email domain doesn't match any configured domains for enterprise SSO connections.

Fix: Add the domain to the connection's email domains list, or verify the user is using the correct email address.

Missing email or user identifier

Error: "Email not found" or "User identifier (sub) not found"

Cause: The IdP didn't return the required claim/attribute, or the claim mapping is incorrect.

Fix:

  • For OIDC: Use the Debug dialog to view available claims and adjust mappings
  • For SAML: Check attribute mappings and verify your IdP is sending the required attributes
  • Some providers require additional scopes or configuration to release email addresses

Registration closed

Error: "Registration is closed for this tenant"

Cause: The tenant has allow_registration = false, so new users cannot be created via SSO.

Fix: Either enable registration for the tenant, or manually create user accounts before they attempt to log in.

Account inactive

Error: "Account is inactive. Please contact the administrator."

Cause: The user account exists but has status != 'active'.

Fix: Activate the user account in the Admin UI.

Incorrect redirect URI

Error: "redirect_uri_mismatch" or similar OAuth error

Cause: The redirect URI configured in your OAuth app or IdP doesn't match what Authalla is using.

Fix:

  • Verify the redirect URI in your IdP matches exactly: https://{tenant-domain}/oauth2/social-login-callback (social), https://{tenant-domain}/oauth2/enterprise-sso-callback (OIDC), or https://{tenant-domain}/saml/acs (SAML)
  • If you recently added a custom domain, update the redirect URI in your IdP to use the new domain
  • Check for trailing slashes and HTTPS vs HTTP mismatches

Connection status

Error: "SSO connection is not active"

Cause: The connection status is set to "Testing" or "Inactive".

Fix: Change the connection status to "Active" in the Admin UI.

SAML assertion signature validation failure

Error: Authentication fails silently or returns "Invalid SAML response"

Cause: The SAML assertion signature doesn't match the IdP certificate configured in Authalla.

Fix:

  • Verify you uploaded the correct IdP certificate (X.509 in PEM format)
  • Check if your IdP certificate has expired or been rotated
  • Ensure your IdP is signing assertions (not just responses)
  • Check IdP logs for signing errors

Custom domain not working

Error: SSO fails after adding a custom domain

Cause: Callback URLs changed, but IdP configurations weren't updated.

Fix: Update all callback URLs in your social login providers, OIDC IdPs, and SAML IdPs to use the new custom domain. Each connection in the Admin UI shows the current redirect URI.

Previous
Magic links
Next
OAuth2 & OIDC