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.
Replace splitsecure.mycompany.com throughout this guide with a subdomain of your own that does not exist, for example splitsecure.acme.com. It needs no DNS record.
Go to Directory → People.
Click Add Person.
Fill in the fields.
Field Value First name SplitSecure Last name Admin Username [email protected]A domain that does not existPrimary email [email protected]The same as the usernameI will set password Do not checkThe user never has a password Click Save.
- Go to Security → Administrators.
- Click Add Administrator.
- In Grant administrator role to, search for
[email protected]and select the user. - Select Super Administrator, or the admin role you prefer.
- Click Save.
Add SplitSecure as an identity provider in Okta
In the Okta Admin Console
- Go to Security → Identity Providers.
- Click Add Identity Provider.
- Select SAML 2.0 IdP and click Next.
- 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 |
Just-in-time provisioning is off: a user must exist in Okta before they can sign in through SplitSecure, so nobody can create an account by signing in. The filter ^[^@]+@splitsecure\.mycompany\.com$ restricts this identity provider to your SplitSecure domain. Change it to match the domain you chose.
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.
Go to Security → Identity Providers → Routing Rules.
Click Add Routing Rule.
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 providerUse this identity provider SplitSecureThe identity provider you created above Click Create Rule.
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.
- Go to Directory → Groups.
- Click Add Group.
- Enter a name, for example
SplitSecure Admins, and a description. - Click Save.
- Open the new group and click Assign people.
- Search for
[email protected], click +, then click Save.
- Go to Security → Authentication Policies and select App sign-in.
- Open the Okta Admin Console policy.
- Click Add Rule.
- Enter a rule name, for example
SplitSecure MFA. - 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 |
Do not check Phishing resistant. That constraint accepts only Okta’s own phishing-resistant authenticators, so Okta prompts the user to enrol in Okta Verify instead of trusting the AMR claims from SplitSecure.
- Click Save.
- Move
SplitSecure MFAto 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 aboveSplitSecure 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
- Go to Security → Identity Providers.
- Find your identity provider and click Actions → Configure Identity Provider.
- 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.
The NameID is the identifier the service provider receives for the person signing in. NameID format sets its type, and NameID value sets where it comes from:
- Same for every sign-in: the value you enter in NameID. Every sign-in through the connected app is the same user.
- Chosen at each sign-in: the person signing in enters or picks it, within the limits you set under Limit the value.
- Built from each person’s email: the SplitSecure email of the person signing in. Email must end with limits who can sign in.
- Generated once, when the app is created (Persistent format) or New for each sign-in (Transient format): SplitSecure generates the identifier.
The defaults depend on the service provider. The form starts on the format and value this service provider usually takes.
- Click the Okta (SAML2) card.
- Enter a Name, for example
Okta Admin Console. - 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. - Under Metadata File, upload the XML file you downloaded from Okta.
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.
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.
Click Sign in in the same browser window where you clicked Log in. Other browsers, profiles and devices never show the button, and once you leave the page it does not come back. To sign in again, start a new request.
Okta opens the Admin Console signed in as the SplitSecure admin user. Okta asked for no password.
- Open your organization’s Okta sign-in page in the test profile.
- Enter
[email protected]as the username. - The routing rule sends you to the Web App, which opens the Log in page for the connected app.
- In NameID, select
[email protected]and click Log in. - Wait for the Guardian Team’s approval, then click Sign in.
Okta signs you in as the SplitSecure admin user and shows no password prompt at any point.
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
- Add a SAML Identity Provider (opens in a new tab): Okta help on SAML identity providers
- Add an external SAML IdP (opens in a new tab): Okta developer guide for external SAML IdPs