How to Set Up Single Sign-On (SSO) in Sparkforge

Single Sign-On (SSO) lets agency and sub-account users sign in to Sparkforge with their existing identity provider credentials. SSO uses the OpenID Connect (OIDC) standard. SAML is not supported yet but is on the roadmap.

What SSO does

SSO connects Sparkforge to an external Identity Provider (IdP) that speaks OIDC. Users are redirected to the IdP, authenticate once, and are returned to Sparkforge with a verified token. That eliminates separate Sparkforge passwords and centralizes user lifecycle in your IdP.

Eligibility

• Active agency subscription on the white-label tier.
• A configured white-label domain (SSO only appears on the white-labeled login page).
• One IdP integration per agency. Multiple IdPs are not supported.
• The IdP must support OIDC.
• Users must already exist in Sparkforge or be created via the Users API with their externalUserId.

Where to find SSO

Go to Company Settings (Agency Level) → Single Sign-On (SSO). All agency admins can view and configure. Click Enable SSO to start the setup flow.

Setup flow

Step 1: Client ID and Secret

• Method of Authentication: locked to OIDC.
• Client ID: identifier issued by your IdP.
• Secret: secure key from your IdP that Sparkforge uses to authenticate requests.

Step 2: OIDC configuration

Configure automatically or manually.

• Automatic discovery (recommended): set Use OIDC Config URL to Yes and enter the OIDC config URL (typically https://<idp>/.well-known/openid-configuration).
• Manual: enter the Authorization URL, Token Endpoint, and User Info Endpoint from your IdP.

Scopes: openid is required. profile and email are recommended.

Redirect URL: prefilled by Sparkforge. If not, it follows https://<your-whitelabel-domain>/login/sso. This URL must be allow-listed in your IdP. Don't edit it unless fixing the format.

Step 3: User details mapping

• Remote ID Field (required): unique user ID from the IdP (for example, sub in OIDC, oid in Azure).
• ID Field (optional): the Sparkforge user ID for direct mapping.
• Email Field: the IdP attribute holding the user's email (for example, email, userPrincipalName). Must be unique per user.
• Email Verified Field (required): ensures the email has been validated by the IdP (for example, email_verified).

Step 4: Review and finish

Save the configuration. You will see three collapsible sections: SSO Configuration, Test Status, and Additional Settings. SSO cannot be enabled until a test passes.

Testing and enabling SSO

Testing is mandatory.

1. In the Test Status section, click Start Test. Or open the three-dot menu and click Test Configuration.
2. Sparkforge mimics the SSO login flow and sends you to the IdP to log in.
3. You are redirected back to the Company Settings SSO tab with the updated test status.
4. If the test passes, enable SSO. If it fails, the error message points to the cause.

Editing the SSO config marks all prior tests as expired and resets SSO toggles. You must re-test to re-enable.

Provider-specific setup

Auth0

• Create a Regular Web Application in Auth0.
• Copy Client ID and Secret into Sparkforge.
• Add the Sparkforge Redirect URL to Auth0 Allowed Callback URLs.
• Config endpoint: https://YOUR_DOMAIN/.well-known/openid-configuration.
• Scopes: openid profile email.
• Mapping: Remote ID → sub, Email → email, Verified → email_verified.

Azure Active Directory (Entra ID)

• Azure Portal → App registrations → New registration.
• Add the Sparkforge Redirect URI.
• Copy Application (Client) ID into Sparkforge as Client ID.
• Create a Client Secret and copy into Sparkforge.
• Copy the OpenID metadata document URL from Endpoints into the Sparkforge config field.
• Add permissions: openid, profile, email.
• Mapping: Remote ID → oid, Email → userPrincipalName, Verified → true.

Okta

• Okta Admin → Applications → Create App Integration.
• Select OIDC - OpenID Connect, type Web Application.
• Add the Sparkforge Redirect URL under Login redirect URIs.
• Copy Client ID and Secret into Sparkforge.
• Use the Okta metadata URL: https://<okta-domain>/.well-known/openid-configuration.
• Assign groups or users.
• Mapping: Remote ID → sub, Email → email, Verified → email_verified.

Adding users from your IdP to Sparkforge

SSO supports login only. New users are not created automatically. Add users to Sparkforge before they try to sign in.

1. Create a Private Integration Token with the Create or Edit Users scope.
2. Use the Create Users or Update Users API to add or update users.
3. Set externalUserId to match the user's unique ID from your IdP.

Sparkforge matches users by their externalUserId first, then falls back to email plus company ID. If neither matches, login fails. Always set externalUserId so email changes in the IdP don't break SSO.

Common errors