OIDC SSO Setup

This guide walks through configuring OpenID Connect (OIDC) SSO for your FrontLine tenant. OIDC is the recommended protocol for most identity providers.

FrontLine uses Authorization Code + PKCE exclusively — implicit and password credential flows are not supported.

How it works

1. A user navigates to FrontLine and enters their email address.
2. FrontLine identifies the configured IdP for that email domain and redirects to the provider's authorization endpoint.
3. The user authenticates with the IdP.
4. The IdP redirects back to FrontLine's callback URL with an authorization code.
5. FrontLine exchanges the code for tokens, validates claims, and creates a session.

If JIT provisioning is enabled and the user does not yet exist in FrontLine, an account is created automatically with the configured default role.

Provider setup guides

Microsoft Entra ID

1. In the Azure portal, go to Entra ID → App registrations → New registration.
2. Set the Redirect URI to:

   https://app.frontlinehq.io/api/auth/callback/oidc
3. Under Authentication, confirm Web platform is selected and PKCE is supported.
4. Under Certificates & secrets, create a new client secret. Copy the value immediately.
5. Note the following from the Overview page:
   • Application (client) ID
   • Directory (tenant) ID
6. The discovery URL is:

   https://login.microsoftonline.com/{directory-tenant-id}/v2.0/.well-known/openid-configuration
7. Under Token configuration, add optional claims: email, given_name, family_name.

Okta

1. In the Okta Admin Console, go to Applications → Create App Integration.
2. Select OIDC — OpenID Connect and Web Application.
3. Set the Sign-in redirect URI to:

   https://app.frontlinehq.io/api/auth/callback/oidc
4. Note the Client ID and Client secret.
5. The discovery URL is:

   https://{your-okta-domain}/.well-known/openid-configuration
6. Assign users or groups to the application.

Google Workspace

1. In the Google Cloud Console, go to APIs & Services → Credentials → Create Credentials → OAuth client ID.
2. Select Web application.
3. Add the Authorized redirect URI:

   https://app.frontlinehq.io/api/auth/callback/oidc
4. Note the Client ID and Client secret.
5. The discovery URL is:

   https://accounts.google.com/.well-known/openid-configuration
6. In Google Admin → Security → API controls, ensure the app is trusted for your organisation.

Custom OIDC provider

Any provider that supports OpenID Connect Discovery can be configured:

1. Obtain the Discovery URL (must serve a .well-known/openid-configuration document).
2. Register FrontLine as a client in your provider with the redirect URI:

   https://app.frontlinehq.io/api/auth/callback/oidc
3. Note the Client ID and Client secret.

Configuring in FrontLine

1. Navigate to Settings → Security & SSO → Add Provider.
2. Select OIDC as the protocol.
3. Choose the provider type (Entra ID, Okta, Google Workspace, or Custom OIDC).
4. Fill in the configuration fields:

Field	Description
Discovery URL	The OIDC discovery endpoint from your provider
Client ID	The application/client ID from your provider
Client secret	The client secret (stored securely — never in the database)
Allowed email domains	Email domains that should route to this provider (e.g., yourcompany.com)
Default role	Role assigned to JIT-provisioned users
JIT provisioning	Enable to auto-create users on first SSO login

5. Configure claim mappings:

FrontLine field	Expected claim
Email	email
First name	given_name
Last name	family_name
Groups (optional)	groups

6. Save the configuration in Draft status.
7. Test by logging in with a pilot user.
8. Once verified, set the configuration to Active.

caution

Only one IdP configuration can be Active per email domain. If you have an existing active configuration for the same domain, deactivate it before activating the new one.

Group-to-role mapping

If your IdP sends a groups claim, you can map IdP groups to FrontLine roles:

1. In the SSO configuration, enable Group-to-role mapping.
2. Add mappings: IdP group name → FrontLine role.
3. Users are assigned the mapped role on login. If no group matches, the default role is used.

Group-to-role mapping changes are audited.

Troubleshooting

Problem	Cause	Solution
Redirect fails after IdP login	Callback URL mismatch	Verify the redirect URI in your IdP matches https://app.frontlinehq.io/api/auth/callback/oidc exactly
"Invalid issuer" error	Discovery URL misconfigured	Confirm the discovery URL returns a valid OIDC configuration document
User created without name	Missing claim mapping	Add given_name and family_name to the token claims in your IdP
"State validation failed"	Browser session expired or CSRF	Have the user clear cookies and try again; ensure no proxies are stripping cookies
JIT user gets wrong role	Default role misconfigured	Check the Default role setting in the SSO configuration
Login blocked for SSO user	enforce_sso is off and user is trying SSO	SSO works regardless of enforcement. Check that the email domain is in Allowed email domains