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

By Sparkforge Support Team ·Last reviewed May 3, 2026

Sparkforge supports OpenID Connect (OIDC) SSO so users can log in with their organizational credentials. Configure the IdP, map user fields, run a test, then enable SSO from Company Settings.

Sparkforge supports Single Sign-On using the OpenID Connect (OIDC) protocol. SAML is on the roadmap but not yet supported. Once configured, your users sign in to Sparkforge with their organizational identity.

Prerequisites

Your agency must be on the $497 plan.
A whitelabel domain must already be configured.

Where to find SSO

Go to Company Settings → Single Sign-On (SSO). All agency admins can view and configure SSO. Click Enable SSO to start the 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, used by Sparkforge to prove its identity.

Step 2: OIDC configuration

Automatic discovery (recommended)

Set Use OIDC Config URL to Yes.
Enter your IdP's config URL — usually https://<idp>/.well-known/openid-configuration.

Manual configuration

Enter these endpoints from your IdP:

Authorization URL
Token Endpoint
User Info Endpoint

Scopes and redirect URL

Scopes: openid is required. profile and email are recommended.
Redirect URL: prefilled by Sparkforge. If missing, use https://<your-whitelabel-domain>/login/sso. Whitelist this in your IdP. Do not edit it unless correcting the format.

Step 3: User details mapping

Map IdP user attributes to Sparkforge so the same person is recognized across both systems.

Field	Required	Purpose
Remote ID Field	Yes	Unique IdP identifier (for example `sub` in OIDC, `oid` in Azure).
ID Field	No	Sparkforge user ID — use to map directly to existing users.
Email Field	Yes	The IdP email attribute (for example `email`, `userPrincipalName`). Must be unique per user.
Email Verified Field	Yes	Confirms the email is validated by your IdP (for example `email_verified`).

Step 4: Review, test, enable

After saving, you will see three sections:

SSO Configuration — your saved entries.
Test Status — run a mandatory test before SSO can be enabled.
Additional Settings — toggles to enable SSO and optionally hide other login methods (Email, Google).

Run the test

In the test section, click Start Test, or open the three-dot menu and pick Test Configuration.
Sparkforge mimics the SSO login flow, sends you to the IdP, and prompts you to sign in.
You're redirected back to the SSO tab with the updated status.

If the test passes, you can enable SSO. If it fails, the error message points at the cause.

Note: updating the SSO config marks all prior tests as EXPIRED and resets the SSO toggles. You must re-test before re-enabling.

Provider setup

Auth0

Create a Regular Web Application in Auth0.
Copy Client ID and Secret to Sparkforge.
Add Sparkforge's Redirect URL to Auth0's 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 Sparkforge's Redirect URI.
Copy Application (Client) ID to Sparkforge Client ID.
Create a Client Secret and copy it to Sparkforge Secret.
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.
Pick OIDC - OpenID Connect, type Web Application.
Add Sparkforge's Redirect URL under Login redirect URIs.
Copy Client ID and Secret to Sparkforge.
Use Okta metadata: https://<okta-domain>/.well-known/openid-configuration.
Assign groups or users.
Mapping: Remote ID → sub, Email → email, Verified → email_verified.

Editing or deleting an existing SSO config

Editing the SSO config invalidates prior test results and disables SSO. Re-test, then re-enable.
The Hide other login options toggle does not work until SSO is enabled.
Deleting the SSO config (three-dot menu) resets additional settings, expires test results, and disables SSO for all users.

Current limitations

SSO supports login only. New users cannot sign up via SSO — they must already exist in Sparkforge.
Add SSO-ready users via the Create Users API or Update Users API. Set externalUserId to the user's unique IdP ID.

Common errors

Message	Cause	Fix
Something went wrong, please try again.	Sparkforge couldn't fetch user details from your IdP. Often wrong endpoints or temporary IdP downtime.	Verify the OIDC Config URL/endpoints, confirm the IdP app is active, retry.
Email is not verified, please contact your admin.	`email_verified` is missing or false.	Configure your IdP to include `email_verified = true` in the ID token.
remoteIdField is not configured properly.	The Remote ID (for example `sub`, `oid`) is missing or unmapped.	Update your config with a valid unique identifier field.
emailField or idField is not configured properly.	Email or ID Field mapping is invalid.	Provide a valid Email Field (for example `email`, `userPrincipalName`) or ID Field.
No user found with this email.	The IdP user does not exist in Sparkforge.	Create the user in Sparkforge and set `externalUserId` to their IdP unique ID.
You are not authorized to access this account.	The user is missing a sub-account association.	Link the user to a sub-account in Sparkforge.
Failed to initiate SSO test.	The backend could not start the test flow.	Retry. If it persists, contact support with your relationship number.

How user matching works

When a user logs in via SSO, Sparkforge:

Looks for a user with a matching SSO Remote ID (externalUserId).
If none, searches by email plus company ID.
If still nothing, login fails.

If a user's email changes in your IdP and externalUserId is set, Sparkforge keeps recognizing them and updates the email on next login. Always set externalUserId via API at provisioning to avoid email-drift issues. You can also pass platformLanguage at user creation to pre-set the UI language.

Scopes reference

Scope	What it returns	How Sparkforge uses it
`openid` (required)	The user's unique identifier (`sub`).	Links the user to their Remote ID.
`profile`	Name, given_name, family_name.	Enriches user data (display name, etc.).
`email`	Email address and `email_verified`.	Maps to Email Field, supports automatic email updates.
`groups` / `roles`	Group/role membership.	Provider-dependent. Future use for role-based access or sub-account mapping.
`offline_access`	Refresh token for long-lived sessions.	Not supported in Sparkforge.

Frequently Asked Questions

Does Sparkforge support SAML SSO?

Not yet. Sparkforge currently supports OpenID Connect (OIDC) only. SAML is on the roadmap.

What plan do I need for SSO?

The $497 agency plan, plus a configured whitelabel domain. Both prerequisites must be in place before enabling SSO.

Why is my test marked EXPIRED?

Any change to the SSO configuration after a passing test invalidates the result. Run a new test before re-enabling SSO.

Can users self-sign-up through SSO?

No. SSO supports login only. Users must already exist in Sparkforge — provision them via the Create Users API with externalUserId set to their IdP unique ID.

What if a user's email changes in the IdP?

As long as externalUserId (Remote ID) is set, Sparkforge keeps recognizing the user and updates the email automatically on the next SSO login.