SSO connections

A connection is one way for a tenant's users to sign in with an identity provider outside Authalla. Each connection belongs to one tenant. Social connections are listed on the tenant's Connections tab. Enterprise connections belong to an organization, one of your business customers, and are set up on its page under the tenant's Organizations tab.

Overview

A connection has one of three types:

• Social: a consumer account at Google, Microsoft, GitHub, Facebook, LinkedIn, X or Discord. The login page shows a button for it. A tenant has at most one social connection per provider.
• Enterprise OIDC: a company's own OpenID Connect identity provider. Microsoft Entra ID has its own entry; Okta, Google Workspace and others are added as Other OIDC.
• Enterprise SAML: a company's SAML 2.0 identity provider. Microsoft Entra ID has its own entry; Okta and others are added as Other SAML.

Enterprise connections have no button. Users reach them by email domain: an organization owns its email domains, and someone who enters user@acme.com is sent to the connection of the organization that owns acme.com. An organization has at most one enterprise connection.

flowchart TD
  userStarts[User starts login] --> entersEmail[User enters email]
  entersEmail --> domainCheck{Email domain has an enabled enterprise connection?}
  domainCheck -->|Yes| redirectEnterprise[Redirect to enterprise IdP]
  domainCheck -->|No| showDefault[Show the tenant's sign-in methods]
  showDefault --> socialButtons[Buttons for enabled social connections]
  redirectEnterprise --> callback[Return to Authalla callback]
  callback --> oauth2Continue[Continue OAuth2 flow]

Managing connections

Open Admin UI → Tenants → (select tenant) → Connections for social connections. The tab lists them with an Enabled switch each.

Enterprise connections are on Admin UI → Tenants → (select tenant) → Organizations. The tab lists each organization with its email domains and its connection.

Adding a social connection

1. On the Connections tab, click Add connection.
2. Choose the provider. Providers the tenant already has are marked as added.
3. Fill in the client ID and secret and create the connection. You land on its page.

Adding an enterprise connection

1. On the Organizations tab, click Add organization and give it a name, optionally your own external ID for the customer, and its email domains. An email domain can belong to only one organization in a tenant.
2. On the organization's page, click Set up connection and choose the provider under Enterprise OIDC or Enterprise SAML.
3. Fill in the short form and create the connection. You land on its page to finish setting it up.

Deleting an organization deletes its connection, email domains and list of members. Its users stay in the tenant.

Enabling and disabling

The Enabled switch, on the Connections tab for a social connection and on each connection's page, takes effect on the login page immediately. It changes only this connection in this tenant.

A SAML connection can be enabled only once its setup is complete: the switch says why it can't be turned on yet.

Testing an enterprise connection

A new enterprise connection starts as a draft. A draft is never offered at sign-in, even for its organization's email domains.

On the connection's page, click Test sign-in. A window opens on your tenant's sign-in domain and sends you to the identity provider. Sign in with an account there. The test signs no one in to your tenant and creates no user. The connection's page then shows whether it passed, the values it read (email, name, user ID, groups) and everything the identity provider sent. A test fails when the identity provider returns an error, when the email is missing, or when the email isn't at one of the organization's domains, and the page says which.

A passing test turns a draft on. If you can't sign in at your customer's identity provider yourself, you can turn a draft on with its switch and confirm Activate without testing. Each test link works once, for 15 minutes.

Through the Management API and MCP

An organization's connection can also be set up, tested and turned on through the Management API and MCP. See Organizations.

Changing an enterprise connection after its test

When you change the identity provider settings of an enterprise connection that is no longer a draft (its endpoints, client ID or secret, certificate, or claim and attribute mappings), the change waits as a pending change, whether the connection is on or off. Sign-in keeps using the previous settings until a test sign-in of the new ones passes; then they take over. The connection's page shows the settings you are editing and says that they are pending. Discard changes drops them. Its name and the Enabled switch change at once.

Social buttons and email domain routing need no other setting: they work while the tenant has an enabled connection of that kind. The Sign-in methods on the tenant's General tab cover only magic links and passkeys.

Editing and deleting

Click a connection to open its page. It has the connection's settings, a save bar that appears when you change something, and Delete connection at the bottom. A client secret is never shown after you save it: enter a new one to replace it, or leave the field empty to keep the current one.

An organization's members

Who has signed in through an organization's connection, and who still signs in some other way, is on the organization's page. See Organizations.

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., user@acme.com → acme.com)
2. Finds the organization that owns the domain, and its connection if that is enabled
3. If found, redirects the user to that IdP instead of showing the default login screen

Each email domain belongs to at most one organization per tenant.

A connection only signs in emails at its organization's domains. If the identity provider returns an email at any other domain, the sign-in is refused, so one customer's identity provider can't sign in as a user of another.

Sending users to an organization

Your app can send a user straight to an organization's connection with the organization parameter, and tokens from a sign-in through it carry the organization as org_id. See Organizations.

Single sign-on is required once the connection is on

Once an organization's connection is enabled, users with an email at its domains can sign in only through it. See Organizations.

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, links the external identity to that user
   • If no user exists and registration is enabled, creates a new user account

Before it links or creates, Authalla needs the email to be verified. If the identity provider didn't verify it, Authalla confirms it itself (see Confirming an email).

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

Confirming an email

A first sign-in through a connection either joins an existing user with the same email or creates a new user. Both hand an account to whoever controls the email, so Authalla needs to know the address is theirs.

When the identity provider says it verified the email, Authalla trusts it. Otherwise Authalla emails a 6-digit code to the address, and the user enters it on the page they are already on. Only after the right code does Authalla join or create the user, and the user's email is then marked verified. A user who never enters the code leaves nothing behind.

An email counts as verified when:

• Social: the provider reports it verified. Facebook never does, so every first Facebook sign-in asks for a code. For GitHub, Authalla reads the user's addresses and picks the primary verified one, else any verified one, else the primary one, which then needs a code.
• Enterprise OIDC: the ID token or userinfo has email_verified: true.
• Enterprise SAML: the assertion has an email_verified attribute set to true. Most IdPs don't send one, so a user's first SAML sign-in usually asks for a code.

The code works for 10 minutes. The user can ask for a new code, 30 seconds apart, up to 5 codes in all, and has 5 wrong tries in total across them. Per address, Authalla also allows at most 10 tries and 10 code emails an hour, and 20 of each a day, however many times the sign-in is started again. The code must be entered in the browser that started the sign-in; opening the email on another device doesn't sign the user in there. A user who already signed in through the connection is recognised by the provider's user ID and never asked again.

The email comes from the tenant's sender address when it has one.

Social login

Social login lets users sign in with a consumer account at Google, Microsoft (personal accounts), GitHub, Facebook, LinkedIn, X or Discord.

Configuration

On the Connections tab, click Add connection and choose the provider under Social.

Required fields:

• Client ID: OAuth client ID from the provider
• Client Secret: OAuth client secret (encrypted at rest)

Redirect URI (shown on the connection page):

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.).

Provider-specific setup

The Add connection dialog and the connection page show these steps for their provider under Setup steps.

Google:

1. In the Google Cloud Console, open Google Auth Platform in your project and set up Branding, with Audience set to External.
2. Under Clients, choose Create client with the application type Web application.
3. Add the redirect URI under Authorized redirect URIs and create the client.
4. Copy the Client ID and Client secret into the connection. Google shows the secret only once.
5. While the app is in Testing, only its test users can sign in. Choose Publish app under Audience to open it to everyone. The openid, email and profile scopes need no verification.

Microsoft:

1. In the Microsoft Entra admin center, go to App registrations and choose New registration.
2. Under Supported account types, choose one that includes personal Microsoft accounts. The Microsoft social connection signs in personal accounts only; for work and school accounts, add Microsoft Entra ID as an enterprise connection.
3. Register, then copy the Application (client) ID from Overview.
4. Under Authentication, add a Web platform redirect URI.
5. Under Certificates & secrets, add a new client secret and copy its Value, not its Secret ID. Sign-in stops when the secret expires (at most 24 months), so replace it in the connection before then.

GitHub:

1. In GitHub, go to Settings → Developer settings → OAuth Apps and choose New OAuth App.
2. Enter the redirect URI as the Authorization callback URL and register the application.
3. Copy the Client ID, then choose Generate a new client secret and copy it. GitHub shows it only once.

Use an OAuth App, not a GitHub App. Authalla reads the user's email addresses from GitHub's /user/emails on every sign-in, which a GitHub App can call only with the Email addresses account permission; without it, GitHub sign-in fails.

Facebook:

1. In Meta for Developers, create an app with the Authenticate and request data from users with Facebook Login use case.
2. Under Facebook Login settings, add the redirect URI to Valid OAuth Redirect URIs. Meta matches it exactly and requires HTTPS.
3. Meta asks for a data deletion instructions URL (or callback) before the app goes live.
4. Copy the App ID and App Secret into the connection. The email and public_profile permissions need no App Review.

LinkedIn:

1. In the LinkedIn Developer Portal, create an app and add the Sign In with LinkedIn using OpenID Connect product.
2. On the Auth tab, add the redirect URI under Authorized redirect URLs.
3. Copy the Client ID and Primary Client Secret into the connection.

X:

1. In the X Developer Console, create an app and turn on OAuth 2.0 as a Web App (confidential client).
2. Add the redirect URI as a Callback URI. X matches it exactly.
3. Turn on Request email from users, and set a Privacy Policy URL and a Terms of Service URL. X shares the user's email only with all three.
4. Copy the OAuth 2.0 Client ID and Client Secret into the connection.

X has no free API access: the developer account needs pay-per-use credits, and each sign-in reads the user's profile. Users see a notice on X's consent screen that the app can read their email address.

Discord:

1. In the Discord Developer Portal, create an application.
2. On the OAuth2 page, add the redirect URI under Redirects.
3. Copy the Client ID and Client Secret into the connection.

Authalla asks for the identify and email scopes. A Discord user who has not verified their email with Discord gets a code by email on their first sign-in.

Steam is not offered: Steam sign-in returns no email, and every Authalla user has one.

What users see

A button for each enabled social connection appears 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: Authentication fails if the provider doesn't return an email. Facebook leaves it out for accounts registered with a phone number, or when the user declines the email permission. LinkedIn, X and Discord can also leave it out.

The confirmation code doesn't arrive: The user can ask for a new one on the same page. If none arrive, check the tenant's sender address, or choose Use a different sign-in method and sign in another way.

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 OpenID Connect identity provider.

Configuration

On the organization's page, click Set up connection and choose the provider under Enterprise OIDC: Microsoft Entra ID, or Other OIDC for any other identity provider, such as Okta or Google Workspace.

Required fields:

• Connection name: Friendly identifier (e.g., "Acme Corp SSO")
• Client ID: OAuth2 client ID from your IdP
• Client Secret: OAuth2 client secret (encrypted at rest)

Endpoints:

• From the discovery URL (recommended): Paste your IdP's discovery URL (e.g., https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration) and Authalla reads the endpoints from it. On the connection page, Read endpoints reads them again, for example after the IdP changes them.
• By hand: Enter the authorization endpoint, token endpoint, userinfo endpoint and JWKS URI yourself. You can edit them on the connection page at any time.

Redirect URI (configure in your IdP):

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

Discovery URL for Microsoft Entra ID

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

For another identity provider, its documentation gives the discovery URL. It usually ends in /.well-known/openid-configuration.

What users experience

1. User visits your app and clicks "Sign in"
2. User enters their email address (e.g., user@acme.com)
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
• Other OIDC: Standard OIDC claims (email, name, given_name, family_name)

If login fails (missing claims)

The connection page has a Last sign-in attempt section with the last error and the claims the IdP sent. If authentication fails because email or sub is missing:

1. Ensure your IdP is configured to release the email and sub (or equivalent) claims.
2. If your IdP uses different claim names, click Use suggested mappings or edit the claim mappings to match, then save.
3. Retry the login.

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

On the organization's page, click Set up connection and choose the provider under Enterprise SAML: Microsoft Entra ID, or Other SAML for any other identity provider, such as Okta.

Required fields:

• Connection name: Friendly identifier (e.g., "Acme Corp SAML")

The connection starts disabled. Enable it once you have entered the IdP details below.

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 on the connection page to fill in all IdP fields
2. Manual: Enter the SSO URL, entity ID and certificate yourself

Service Provider (SP) configuration

After creating a connection, Authalla generates SP configuration values you must provide to your IdP. The connection page shows them next to the setup steps for your provider:

SP Entity ID:

urn:authalla:sp:{connection-id}

(Unique per connection, shown on the connection page)

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. Download the metadata XML from the connection page
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 the SP entity ID and ACS URL from the connection page
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

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 the assertion and signs the user in
4. Authalla sends the browser to the tenant's default app's initiate login URI, with iss, client_id and login_hint
5. The app starts a normal authorization request, which completes without asking the user to sign in again

The default app

Sign-ins that don't start in one of your apps go to the tenant's default app: those started from an identity provider's portal, such as a tile in Microsoft My Apps, and the Sign in button in the email to a member you add. When the tenant has a single app users sign in to, that app is the default. With more than one, choose it under Admin UI → Tenants → (select tenant) → General → Default app.

The default app takes these sign-ins through its Initiate login URI, set on the app's URIs tab. It's a page on your app that starts an OAuth2 sign-in when visited (OpenID Connect third-party initiated login). Without one, a sign-in started from an identity provider ends on an error page that asks the user to start from the app, and the email to a new member says how to sign in instead of having a button. The dashboard warns about this on the tenant's settings and on each organization with a connection. If your app has no such page yet, build it first: it only needs to start a sign-in the way your login button does, passing on login_hint if it gets one.

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

Other 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 on the connection page

To rotate the certificate:

1. Rotate the certificate on the connection page
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

The sign-in error page tells the user what went wrong in plain words and never shows the technical detail. Look for that in the tenant's Activity log, where each failed sign-in has a reason.

Domain mismatch errors

The user sees: "This email can't sign in here". The Activity log shows Email domain not allowed.

Cause: The email the identity provider returned isn't at one of the connection's organization's domains.

Fix: Add the domain to the organization's email domains, or check the user is signing in with the right 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: Check Last sign-in attempt on the connection page for the claims the IdP sent, and adjust the 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

The user sees: "Can't create an account"

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

The user sees: "Your account is inactive"

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 disabled

The user sees: "This sign-in method isn't available" when the connection was turned off while they were signing in.

Cause: The connection is disabled.

Fix: Turn on its Enabled switch on the tenant's Connections tab.

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 page shows the current redirect URI.