SAML SSO Setup

This guide walks through configuring SAML 2.0 SSO for your FrontLine tenant. SAML is supported for providers that don't offer OIDC or where your organisation prefers SAML-based federation.

FrontLine supports both SP-initiated (user starts at FrontLine) and IdP-initiated (user starts at the identity provider) flows.

How it works

SP-initiated flow:

1. A user navigates to FrontLine and enters their email address.
2. FrontLine identifies the SAML IdP for that email domain and sends a SAML AuthnRequest.
3. The user authenticates with the IdP.
4. The IdP posts a signed SAML assertion back to FrontLine's ACS URL.
5. FrontLine validates the assertion and creates a session.

IdP-initiated flow:

1. The user clicks the FrontLine app tile in their IdP dashboard.
2. The IdP posts a signed SAML assertion directly to FrontLine's ACS URL.
3. FrontLine validates the assertion and creates a session.

FrontLine service provider details

When configuring your IdP, you'll need these FrontLine SP values:

Field	Value
ACS URL (Assertion Consumer Service)	https://app.frontlinehq.io/api/auth/callback/saml
Entity ID (SP Entity ID)	https://app.frontlinehq.io/saml/metadata
SLO URL (Single Logout)	https://app.frontlinehq.io/api/auth/logout/saml

Provider setup guides

Microsoft Entra ID

1. In the Azure portal, go to Entra ID → Enterprise applications → New application → Create your own application.
2. Select Integrate any other application you don't find in the gallery (Non-gallery).
3. Go to Single sign-on → SAML.
4. Under Basic SAML Configuration:
   • Identifier (Entity ID): https://app.frontlinehq.io/saml/metadata
   • Reply URL (ACS URL): https://app.frontlinehq.io/api/auth/callback/saml
   • Sign on URL: https://app.frontlinehq.io
   • Logout URL: https://app.frontlinehq.io/api/auth/logout/saml
5. Under Attributes & Claims, configure:
   • emailaddress → user.mail
   • givenname → user.givenname
   • surname → user.surname
6. Download the Federation Metadata XML or copy the App Federation Metadata URL.
7. Assign users or groups to the application.

Okta

1. In the Okta Admin Console, go to Applications → Create App Integration.
2. Select SAML 2.0.
3. Configure:
   • Single sign-on URL: https://app.frontlinehq.io/api/auth/callback/saml
   • Audience URI (SP Entity ID): https://app.frontlinehq.io/saml/metadata
   • Name ID format: EmailAddress
4. Under Attribute Statements:
   • email → user.email
   • firstName → user.firstName
   • lastName → user.lastName
5. Complete setup and download the IdP metadata.
6. Assign users or groups.

Google Workspace

1. In Google Admin → Apps → Web and mobile apps → Add app → Add custom SAML app.
2. Copy the SSO URL, Entity ID, and download the Certificate from Google.
3. Configure the Service Provider Details:
   • ACS URL: https://app.frontlinehq.io/api/auth/callback/saml
   • Entity ID: https://app.frontlinehq.io/saml/metadata
   • Name ID format: EMAIL
4. Under Attribute mapping:
   • email → Primary email
   • firstName → First name
   • lastName → Last name
5. Enable the app for your organisational units.

Custom SAML 2.0 provider

Any SAML 2.0-compliant IdP can be configured:

1. Obtain the IdP metadata XML or metadata URL.
2. If metadata is not available, collect:
   • SSO URL (IdP login endpoint)
   • Entity ID (IdP identifier)
   • Signing certificate (X.509, PEM or DER format)
3. Configure FrontLine's SP details in your IdP (ACS URL, Entity ID, SLO URL from the table above).

Configuring in FrontLine

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

Field	Description
Metadata URL	URL to the IdP's SAML metadata (preferred — auto-refreshes certificates)
Metadata XML	Manual upload if the IdP doesn't expose a metadata URL
Signing certificate	Manual certificate upload (fallback if not using metadata)
Allowed email domains	Email domains that should route to this provider
Default role	Role assigned to JIT-provisioned users
JIT provisioning	Enable to auto-create users on first SSO login

5. Configure attribute mappings:

FrontLine field	Expected SAML attribute
Email	email or emailaddress or NameID (format: email)
First name	firstName or givenname or given_name
Last name	lastName or surname or family_name
Groups (optional)	groups or memberOf

6. Save in Draft status, test with a pilot user, then set to Active.

tip

Use the Metadata URL option when available. FrontLine automatically refreshes certificates from the metadata endpoint, so you won't need to manually update certificates when your IdP rotates them.

Security requirements

FrontLine enforces the following for all SAML assertions:

• All assertions must be signed — unsigned assertions are rejected.
• Replay prevention — assertion IDs are tracked with a short TTL; replayed assertions are rejected.
• Clock skew tolerance — up to 5 minutes of clock difference between FrontLine and the IdP is allowed.

danger

Never disable assertion signing in your IdP configuration. FrontLine will reject all unsigned SAML assertions.

Troubleshooting

Problem	Cause	Solution
"Invalid assertion signature"	Certificate mismatch	Re-download the IdP certificate or metadata and update in FrontLine
"Assertion replay detected"	Same assertion sent twice	Have the user try logging in again; check for network retries or duplicate form submissions
"ACS URL mismatch"	Reply URL misconfigured in IdP	Verify the ACS URL in your IdP matches https://app.frontlinehq.io/api/auth/callback/saml exactly
"Clock skew exceeded"	Server time drift > 5 minutes	Sync the IdP server's clock via NTP
User attributes missing	Attribute mapping mismatch	Compare the attribute names in your IdP config with the expected names in the mapping table above
IdP-initiated login fails	Entity ID mismatch	Verify the SP Entity ID in your IdP matches https://app.frontlinehq.io/saml/metadata
Certificate rotation breaks login	Manual cert used, not metadata URL	Switch to the Metadata URL option for automatic certificate refresh