Skip to main content

Single Sign-On (SSO)

The Single Sign-On (SSO) page (Settings > SSO) connects the Surface Security console to your identity provider so administrators sign in with their corporate identity instead of a local password. It supports both OpenID Connect (OIDC) and SAML 2.0, with built-in templates for Keycloak, Microsoft Entra ID, Okta, Google Workspace, and Auth0 — and works with any standards-compliant provider.

The same SSO configuration does double duty: beyond dashboard login, it powers extension enrollment. When you deploy the browser extension through an MDM or share a magic link, devices enroll by having the employee sign in through this same identity provider — so configuring SSO once unlocks both admin login and token-free device enrollment (see Onboarding, Step 5).

Screenshot

[SCREENSHOT PLACEHOLDER: The Single Sign-On (SSO) page listing one configured provider with its protocol badge, Primary badge, Enabled state, issuer URL, and Edit/Delete actions]

How it works​

  • You register Surface Security as an application in your identity provider and enter the resulting details here.
  • When at least one enabled provider exists, the login page gains a Sign in with SSO (OIDC) and/or Sign in with SAML button below the password form. Clicking it redirects to your IdP; after a successful sign-in the admin lands in the dashboard.
  • Identity attributes from the IdP (email, name, roles/groups) are mapped to a console admin account. With Auto-create users on first SSO login enabled, an account is created automatically the first time someone signs in; its role comes from your Role Mapping, falling back to the Default Role.
  • Admins who sign in via SSO show an SSO badge on the Admin Users page; their second factor is governed by your IdP, not a local authenticator.
  • Local email/password login always remains available as a fallback — SSO adds a sign-in method, it does not remove one.

Adding a provider​

Click Add Provider and choose the Protocol: OpenID Connect (OIDC) or SAML 2.0.

OIDC​

  1. Pick a Provider Template (Keycloak, Entra ID, Okta, Google, Auth0, or Custom). The template pre-fills the role claim path and scopes typical for that provider.
  2. Fill in the common fields:
    • Name — a display label, e.g. "Okta Production"
    • Issuer URL — your provider's issuer, e.g. https://login.microsoftonline.com/{tenant}/v2.0
    • Client ID and Client Secret — from the application you registered in the IdP
  3. In your IdP's application registration, set the redirect URI to the value shown under Advanced Settings > Redirect URL (by default your console origin followed by /api/v1/auth/sso/callback).
  4. Click Test OIDC Discovery to verify the issuer before saving — the result appears inline next to the button.
Screenshot

[SCREENSHOT PLACEHOLDER: The Add SSO Provider form with OIDC selected, the provider template row, Issuer URL / Client ID / Client Secret fields, and a successful "Test OIDC Discovery" result]

SAML 2.0​

  1. Enter a Name and the IdP Entity ID / Issuer from your provider.
  2. Provide either an IdP Metadata URL (automatic configuration) or paste the IdP Certificate (PEM) manually — the certificate verifies SAML assertion signatures.
  3. Optionally set the SP Entity ID (the audience restriction; it defaults to your deployment's SAML metadata URL if left empty).
  4. Review the SAML Attribute Mapping — the Email, Name, and Roles attribute names default to the standard Microsoft claim URIs and can be changed to match your IdP.
  5. Optionally provide an SP Signing Certificate and private key if your IdP requires signed authentication requests.
  6. Leave Allow IdP-initiated SSO off unless you specifically need it — the form flags it as less secure.

Advanced settings​

Expand Advanced Settings to control identity mapping and provisioning:

SettingPurpose
Email Claim / Name ClaimWhich token claims carry the admin's email and display name (OIDC)
Role Claim PathDot-separated path to the roles array in the ID token, e.g. realm_access.roles for Keycloak or groups for Okta
Role MappingMaps IdP role/group names to Surface Security roles (super_admin, admin, analyst, executive, viewer)
Default RoleAssigned when no mapping matches (defaults to viewer)
ScopesOIDC scopes requested (default openid, email, profile)
Redirect URLThe callback your IdP must allow
Auto-create users on first SSO loginProvision admin accounts on first sign-in instead of pre-creating them
EnabledTurns the provider on or off without deleting it
Primary providerMarks the main provider for this tenant

Secrets are write-only: the client secret and SP private key are never displayed again after saving. When editing, leave those fields blank to keep the current values.

Screenshot

[SCREENSHOT PLACEHOLDER: The Advanced Settings section expanded, showing Claim Mapping, a Role Mapping entry ("SOC-Analysts" mapped to analyst), and the Default Role / Scopes / Redirect URL row]

SSO for extension enrollment​

If you deploy the browser extension via Intune, Group Policy, Jamf, or magic links, devices enroll through this same IdP application. One extra one-time step is required: register a second redirect URI in the IdP application for the enrollment callback (your API endpoint followed by /api/v1/enroll/sso/callback). The exact value, with a copy button, is shown in Onboarding Step 5 and under Settings > General > Deployment Identifiers. One URI covers every enrollment on the deployment. Magic-link enrollment is only offered once SSO is configured.

Testing a new provider​

  1. Save the provider with Enabled checked.
  2. Open the console login page in a private/incognito window — you should see the Sign in with SSO (OIDC) (or Sign in with SAML) button below the password form.
  3. Sign in with a test IdP account that belongs to one of your mapped groups.
  4. Confirm on Settings > Admin Users that the account was created (if auto-create is on) with the expected role and shows the SSO badge.
  5. If something misconfigures, sign in with a local admin account and adjust the provider — local login is unaffected by SSO settings.

Worked example: Entra ID with role mapping​

Goal: everyone in the "SecOps-Admins" Entra group becomes an Admin, "SOC" members become Analysts, and anyone else who signs in gets read-only access.

  1. In Entra ID, register an application, add the console redirect URI, create a client secret, and configure group or app-role claims in the token.
  2. In Surface Security, click Add Provider, protocol OpenID Connect (OIDC), template Entra ID (this sets the role claim path to roles).
  3. Enter the Issuer URL (https://login.microsoftonline.com/{tenant}/v2.0), Client ID, and Client Secret, then click Test OIDC Discovery.
  4. Under Advanced Settings, add role mappings: SecOps-Admins mapped to admin, and SOC mapped to analyst. Leave Default Role as viewer.
  5. Enable Auto-create users on first SSO login, keep Enabled and Primary provider checked, and click Create Provider.
  6. Test with one account from each group and verify the roles on the Admin Users page.

Troubleshooting / FAQ​

The SSO button doesn't appear on the login page. Confirm the provider is saved with Enabled checked. The button is only rendered when an enabled provider of that protocol exists.

Sign-in works but the admin gets the wrong role. Check the Role Claim Path against the actual token your IdP issues, and that the IdP group/role name in Role Mapping matches exactly. Unmatched sign-ins fall back to the Default Role.

"Test OIDC Discovery" fails. The issuer URL must be reachable from the Surface Security backend and serve a standard OIDC discovery document. Verify the URL (no trailing path mistakes) and any egress firewall rules.

Can I lock out password login entirely? No — local login remains available as the fallback path. Instead, keep local accounts minimal (one break-glass Super Admin with MFA) and provision everyone else through SSO. See Admin Users & Roles for MFA enforcement.

Does deleting a provider delete the admins it created? No. Accounts remain on the Admin Users page; deactivate any you no longer want there.