Search the documentation
Search the documentation...
SplitSecure documentation

On this page

Procedure · 10 steps

Set up single sign-on

Verify your domains, group them in an identity pool, and connect the identity provider your members sign in with.

Updated

Before you start

  • An Owner or Admin role in the organization.
  • A plan (opens in a new tab) that includes single sign-on (SSO).
  • Access to your domain’s DNS records.
  • An administrator account at your identity provider (IdP), such as Okta or Microsoft Entra ID.

With single sign-on, your members sign in to SplitSecure with their work account. The Web App sends each email address to the identity provider that serves its domain.

Single sign-on takes three things. Set them up in this order:

  1. Verify a domain. This proves your organization controls it.
  2. Create an identity pool. It groups the domains one set of identity providers serves.
  3. Connect the identity provider in the pool.

Verify a domain

In the Web App

  1. In the sidebar, click Organization → Advanced → Domains.
  2. Click Add domain.
  3. Enter the Domain, for example example.com.
  4. Click Generate DNS record.

The page shows a DNS TXT record: a host that starts with _splitsecure_ and a 64-character value.

In your DNS provider

  1. Add a TXT record with the host and value the Web App shows. At most DNS providers, enter the host without your domain: they add it themselves.

In the Web App

  1. Click Check DNS now.

The Web App does not check on its own. If the record is not visible yet, wait a few minutes and check again.

Create an identity pool

In the Web App

  1. In the sidebar, click Organization → Advanced → SSO / Identity pools.

  2. Click Create pool.

  3. Fill in the fields.

    Field Value
    Name A name for the poolFor example Engineering. Unique in the organization
    Description OptionalShown to administrators only
    JIT provisioning On or offJust-in-time (JIT) provisioning creates a member at their first SSO sign-in. When it is off, only invited members and members provisioned through SCIM sign in
    Default seat A seatThe seat a new member gets through this pool when their invitation names none
  4. Click Create pool.

  1. On the pool’s page, under Domains, check the verified domains this pool serves.
  2. Click Save changes.

A domain belongs to one pool at a time.

Connect the identity provider

In the Web App

  1. On the pool’s page, under Identity providers, click Create IdP config.
  2. Enter a Display name, for example Okta.
  3. Under Protocol, choose OpenID Connect or SAML 2.0.
  4. Under Domains, leave every box unchecked to serve all the pool’s domains, or check some of them.

Skip this step for SAML 2.0. Create an OpenID Connect (OIDC) application at your identity provider first, then copy its values here.

Field Value
Issuer URL Your provider’s issuerIt must start with https://
Client ID The application’s client ID
Client secret The application’s client secret
Scopes openid profile email When blank, these three are sent

Click Create identity provider. The configuration’s page then shows the OIDC redirect URI. Register it in the application at your identity provider.

Skip this step for OpenID Connect.

If your identity provider gives you a metadata file instead of a metadata URL, click Upload metadata file and choose the file. It fills Identity provider entity ID, Single sign-on URL and Signing certificates. Check the values before you save.

Field Value
Identity provider entity ID Your provider’s entity ID
Metadata URL Your provider’s metadata addressOr leave it blank and fill in the next two fields
Single sign-on URL Your provider’s sign-in addressNeeded only without a metadata URL
Signing certificates Your provider’s certificate, in PEMNeeded only without a metadata URL. Paste both during a key rollover
Email attribute OptionalWhen blank, the email comes from the usual attributes

Click Create identity provider. The configuration’s page then shows the Service provider entity ID and the Assertion consumer service URL. Enter both in the application at your identity provider. Each configuration has its own consumer URL.

If your identity provider imports service provider metadata, click Download metadata and upload the file there instead. An identity provider that reads metadata from an address takes the Service provider metadata URL.

There is no test button. Sign in with a test account to check the connection.

Require single sign-on

In the Web App

  1. In the sidebar, click Organization → Advanced → Domains, then click the domain.

  2. Under Capture mode, choose one.

    Capture mode Effect
    None Members sign in any way they like
    Soft: warn on social A member who signs in with a social account sees a reminder to use SSO
    Hard: require SSO Social and email-link sign-in are refused for this domain

Hard: require SSO needs an active identity provider for the domain.

Release a domain

In the Web App

  1. On the domain’s page, click Release, then Release in the confirmation.

You cannot release a domain while an active identity provider serves it. Deactivate or delete that configuration first.

Troubleshooting

Issue Solution
The TXT record isn’t visible yet DNS has not published the recordWait a few minutes, then click Check DNS now again
domain already exists; release it before re-adding The domain is already on Domains, in any stateOpen it there
No verified domains yet. on the pool’s page No domain is verifiedFollow Verify a domain above
a domain is already assigned to another identity pool Another pool claims the domainUncheck it in that pool first
Release is disabled: An identity provider uses this domain An active configuration serves the domainDeactivate or delete the configuration, then release
A member sees Access Not Provisioned JIT provisioning is off and they are not a memberInvite them, provision them through SCIM, or turn JIT on
A member sees Single Sign-On Unavailable Your plan no longer includes single sign-onMove to a plan (opens in a new tab) that includes it
The domain shows Superseded Another organization verified itCheck your DNS records, then remove the domain and verify it again

External resources