Search the documentation
Search the documentation...
SplitSecure documentation

On this page

Procedure · 12 steps

Okta

Sign in to the Okta Admin Console through SplitSecure, with an admin user that has no password.

Updated

Before you start

  • Administrator access to the Okta Admin Console.
  • A SplitSecure identity provider, created in a threshold vault and approved by its Guardian Team. See Create an identity provider.

  • A second browser profile, signed in to the Web App, for the test sign-in. Start and finish the test in that same profile.

This guide makes Okta a connected app of your SplitSecure identity provider, so an Okta administrator signs in only when your Guardian Team, the group of devices that together approve each proposal, approves it. You create a dedicated admin user in a domain that does not exist, point Okta at SplitSecure for that domain, and never set a password. There are many ways to connect Okta; this one has worked well for us.

Values you exchange

Value Where to find it Where to paste it
SAML IdP Entity ID The identity provider’s SAML endpoints card in the Web App Okta, IdP Issuer URI, in Configure the protocol settings
SSO URL (HTTP-Redirect) The same card Okta, IdP Single Sign-On URL, in the same step
Signing certificate (PEM) The same card, Download Certificate → PEM format Okta, IdP Signature Certificate, in the same step
Okta IdP metadata (XML) Okta, Download metadata, in Download the Okta metadata The Web App, Metadata File, in Create the connected app

Create the Okta admin user

In the Okta Admin Console

The admin user lives in a subdomain that does not exist, such as splitsecure.mycompany.com. Okta can never ask it for a password, because every sign-in for that domain goes through SplitSecure.

  1. Go to Directory → People.

  2. Click Add Person.

  3. Fill in the fields.

    Field Value
    First name SplitSecure
    Last name Admin
    Username [email protected] A domain that does not exist
    Primary email [email protected] The same as the username
    I will set password Do not checkThe user never has a password
  4. Click Save.

  1. Go to Security → Administrators.
  2. Click Add Administrator.
  3. In Grant administrator role to, search for [email protected] and select the user.
  4. Select Super Administrator, or the admin role you prefer.
  5. Click Save.

Add SplitSecure as an identity provider in Okta

In the Okta Admin Console

  1. Go to Security → Identity Providers.
  2. Click Add Identity Provider.
  3. Select SAML 2.0 IdP and click Next.
  4. Enter a name, for example SplitSecure.

Authentication settings

Field Value
IdP Usage SSO only
Claims YesOkta then honours the AMR claims SplitSecure sends; see the policy part
Account matching with Persistent Name ID Yes

Account matching

Field Value
IdP username idpuser.subjectNameId
Filter ^[^@]+@splitsecure\.mycompany\.com$ Only users in your SplitSecure domain match
Match against Okta Username or Email
Account link policy YesOkta links the assertion to the matching Okta account
Auto-link filters None
If no match is found Redirect to Okta sign-in pageNo just-in-time provisioning: the user must exist first

Open the Web App in another tab to copy the values.

In the Web App, open Vaults, then your vault, then the identity provider. The SAML endpoints card shows three values:

  • SAML IdP Entity ID
  • SSO URL (HTTP-Redirect)
  • SSO URL (HTTP-Post)

Under them, Download metadata XML saves the metadata file and Download Certificate offers the certificate in PEM format or DER format.

Field Value
IdP Issuer URI The SAML IdP Entity IDFrom the SAML endpoints card
IdP Single Sign-On URL The SSO URL (HTTP-Redirect)From the SAML endpoints card
IdP Signature Certificate Upload the certificate fileDownload Certificate → PEM format on the card
Request Binding HTTP REDIRECT
Application context No
Request Signature Yes
Response Signature Verification Assertion
Response Signature Algorithm SHA-256
Okta Assertion Consumer Service URL Trust-specific
Max Clock Skew 2 Minutes

Click Finish.

The routing rule sends every user in your SplitSecure domain to SplitSecure instead of a password prompt. Other Okta users are not affected.

  1. Go to Security → Identity Providers → Routing Rules.

  2. Click Add Routing Rule.

  3. Configure the rule.

    Field Value
    Rule name SplitSecure Authentication
    User’s IP is AnywhereRestrict it to your IP ranges if you want to
    User is accessing Any application
    User matches Regex on login
    Filter ^[^@]+@splitsecure\.mycompany\.com$ The same expression as the identity provider
    Use this identity provider SplitSecureThe identity provider you created above
  4. Click Create Rule.

  5. Click Activate when Okta asks.

Require two factors for the admin user

In the Okta Admin Console

A rule in the Okta Admin Console authentication policy requires two factor types with hardware-protected credentials. SplitSecure satisfies them through the AMR (Authentication Methods References) claims in its assertion. The rule applies to your SplitSecure admin user or group only.

Skip this step if you have one SplitSecure admin user: the policy rule can name the user directly.

  1. Go to Directory → Groups.
  2. Click Add Group.
  3. Enter a name, for example SplitSecure Admins, and a description.
  4. Click Save.
  5. Open the new group and click Assign people.
  6. Search for [email protected], click +, then click Save.
  1. Go to Security → Authentication Policies and select App sign-in.
  2. Open the Okta Admin Console policy.
  3. Click Add Rule.
  4. Enter a rule name, for example SplitSecure MFA.
  5. Configure the rule.

IF conditions

Field Value
User’s type is Any user type
User’s group membership includes SplitSecure AdminsIf you created the group
User is The SplitSecure admin userIf you did not create a group

THEN access and authentication

Field Value
User must authenticate with Any 2 factor types
Phishing resistant UncheckedSee the warning below
Hardware protected CheckedSatisfied by SplitSecure’s hwk claim
Require user interaction Checked → Any interactionSatisfied by SplitSecure’s user claim
Authentication methods Allow any method that can be used to meet the requirement
  1. Click Save.
  2. Move SplitSecure MFA to the top of the policy’s rules, above existing rules such as Admin App Policy. Okta applies the first rule that matches, so a rule above yours decides the admin user’s sign-in. Alternatively, deactivate the rules above SplitSecure MFA. A deactivated rule no longer applies to any admin.

SplitSecure sends these AMR claims in every assertion, and Okta honours them because Claims is Yes in the identity provider’s general settings.

Claim Meaning
mfa Multi-factor authentication
user A user interacted
hwk A hardware key was used
mca Multi-channel authentication

Connect Okta to SplitSecure

In the Okta Admin Console

  1. Go to Security → Identity Providers.
  2. Find your identity provider and click Actions → Configure Identity Provider.
  3. In the Summary card, click Download metadata and save the XML file.

In the Web App

In the Web App, open Vaults, then your vault, then the identity provider. Click New Connected App and pick the service provider’s card. Name is required, and the Threshold Identity Provider field is fixed to this provider.

  1. Click the Okta (SAML2) card.
  2. Enter a Name, for example Okta Admin Console.
  3. Keep NameID format on Email Address, NameID value on Chosen at each sign-in and Limit the value on To a list of allowed values. In Allowed values, one per line, add [email protected]. Only the addresses in this list can sign in through this connected app.
  4. Under Metadata File, upload the XML file you downloaded from Okta.
  5. Optionally, under Advanced Options, turn on Selective notifications so members can choose who gets notified for the Guardian Team’s proposals, set the Account Sensitivity banner shown on this connected app’s proposals (None, Low, Medium, High or Critical), and enter a Description or a Reason for creation.

  6. Click Propose connected app. The Web App opens the proposal under Requests. The members of the Guardian Team approve it on their devices, in the mobile app. When the vote passes, the connected app appears under Connected Apps.

Test the sign-in

In the Web App

In the Web App, open Connected Apps, find the new connected app and click Log in. The Web App shows the details of the connected app. In NameID, select [email protected]. To leave a note for the approvers, open Advanced Options and fill in Reason for access. Click Log in again. The members of the Guardian Team approve the sign-in on their devices, in the mobile app. When the vote passes, click Sign in on the proposal page to finish the sign-in at Okta.

  1. Open your organization’s Okta sign-in page in the test profile.
  2. Enter [email protected] as the username.
  3. The routing rule sends you to the Web App, which opens the Log in page for the connected app.
  4. In NameID, select [email protected] and click Log in.
  5. Wait for the Guardian Team’s approval, then click Sign in.

Troubleshooting

Issue Solution
The sign-in fails at once The IdP Issuer URI does not matchCompare it with the SAML IdP Entity ID on the SAML endpoints card; they must be identical
Okta reports a certificate error The certificate is wrong or expiredDownload the certificate again from the SAML endpoints card and upload it to Okta
Okta reports that the user was not found The user does not exist in OktaCreate the user first; just-in-time provisioning is off
The user is not linked after the sign-in Account link policy is not YesSet it to Yes in the identity provider’s account matching settings
Okta asks the admin user for a password The routing rule is inactive or does not matchActivate the rule and check that its filter matches the user’s login
Okta ignores the AMR claims Claims is NoSet Claims to Yes in the identity provider’s authentication settings
Okta prompts to enrol in Okta Verify Phishing resistant is checkedUncheck it in the authentication policy rule
Okta shows 403 Access Forbidden after the sign-in Another rule of the Okta Admin Console policy matches firstMove SplitSecure MFA to the top of the policy’s rules, or deactivate the rules above it
Okta reports a clock skew error The clocks differIncrease Max Clock Skew or synchronize the clocks

External resources