Using Okta for SSO

Prev Next

This guide will teach you how to configure SAML-based Single Sign-On with Okta for Clarity. Once configured, your users sign in to Clarity with their Okta credentials, and Okta policies such as MFA apply to Clarity.

Estimated time to complete: 30 minutes

If you run into any problems, please contact your support team or support@claritysecurity.io.


Before You Begin

To successfully configure Single Sign-On with Okta, you'll need the following pre-requisites before you begin:

  • Admin access within your Okta instance

    • Note: If you do not have admin access, reach out to your Okta admins for provisioning.

  • Admin access within your Clarity Security tenant. The SSO settings live under Settings > SSO.

  • Your Clarity tenant URL. The examples below use https://YOURDOMAIN.claritysecurity.io. Replace YOURDOMAIN with your tenant name.

Two things to know before you turn SSO on:

  • Who can sign in. Clarity matches the email address Okta sends against an existing Clarity user, or against an active identity in Clarity with the same email. Anyone else is refused with "Unknown identity". A person whose identity is inactive in Clarity is also refused, even if they are assigned the app in Okta. Make sure the people who need Clarity exist as active identities before you enable SSO. Someone who has never signed in to Clarity before gets a Clarity login with standard end-user access on their first Okta sign-in. Administrator and other roles are granted in Clarity separately, not by the Okta assignment.

  • Local passwords are disabled while SSO is on. When Enable SSO is on, the Clarity login page redirects straight to Okta and the password reset pages return Not Found. Test the configuration before you enable it (Step 13). If you need to go back to local passwords, turn Enable SSO off.


Part 1: Create the Clarity App in Okta

Step 1: Login to Okta

Login to your Okta Admin Console by heading to the URL below.

https://www.okta.com/login/

Step 2: Navigate to your Org, then choose Applications from the left menu and click Create App Integration

Step 3: Choose SAML 2.0

Select SAML 2.0 as the sign-in method and click Next.

Step 4: Name your App

"Clarity SSO Login" or "Clarity SSO App" will work. Pick something that will make it obvious, as you will be assigning this application to everyone that you want to be able to login to Clarity. Add a logo if you like, then click Next.

Step 5: Configure the SAML Settings

Fill in the General settings as follows:

Single sign-on URL = https://YOURDOMAIN.claritysecurity.io/saml2/okta/acs

Leave Use this for Recipient URL and Destination URL checked.

Audience URI (SP Entity ID) = https://YOURDOMAIN.claritysecurity.io/saml2/okta/metadata

Select Persistent for Name ID format and Email for Application username.

Step 5b: Enable Single Logout

Single Logout signs the user out of Okta when they sign out of Clarity. Complete this step. Once Enable SSO is on, the Sign out button hands off to Okta, and if Clarity has no Logout URL the sign-out fails with an error and the user stays signed in to Clarity. Clarity signs its logout requests, so Okta needs Clarity's public key.

Under Settings > SSO in Clarity, click the button labeled Download PEM Key and save the file.

Back in the Okta application configuration, click Show Advanced Settings. Upload the PEM file under Signature Certificate by clicking Browse Files. Then check the box for Allow application to initiate Single Logout and use:

Single Logout URL = https://YOURDOMAIN.claritysecurity.io/saml2/okta/sls

SP Issuer = https://YOURDOMAIN.claritysecurity.io/saml2/okta/metadata

Clarity ends its own session only after Okta confirms the logout, so the Single Logout URL and Signature Certificate in Okta need to be right or sign-out will not complete.

Step 6: Scroll down to Attribute Statements

Clarity reads one attribute from the SAML response. Complete this attribute exactly as shown:

Name = email    Name format = URI Reference    Value = user.email

The attribute name must be email in lower case. Clarity reads the attribute by name, so the Name format does not matter. Clarity uses this value to find the user, so it has to match the email address on the person's Clarity identity.

Step 7: Scroll down and click Next, then choose "I'm an Okta customer adding an internal app" and click Finish

Step 8: Click View SAML setup instructions

This will be on the right side of the screen on the Sign On tab. On newer Okta consoles, the same values are under View IdP metadata or the SAML Signing Certificates section.

Step 9: Save or Record the values in the new tab

Record these four values from the new tab. You will enter them in Clarity in Step 12.

  • Identity Provider Issuer

  • Identity Provider Single Sign-On URL

  • Identity Provider Single Logout URL

  • X.509 Certificate

Step 10: Assign the new App to people in your organization

On the Assignments tab, assign to individuals or Groups. Everyone that will need to log in to Clarity, including administrators, must be assigned this application. If Okta is already connected in your Clarity instance, you may also run a sync and then assign the entitlement for this application utilizing Clarity's provisioning capabilities.


Part 2: Configure Clarity

Step 11 (optional): Connect Okta in Clarity

This step is not required for SSO. Clarity's SAML login works without the Okta connector. Connect Okta only if you want Clarity to govern Okta users, groups and app assignments. Okta Connection instructions: Okta

If you do connect Okta, choosing Yes for the SSO Provider tells Clarity which application grants access to your other SSO-federated applications. It does not affect SAML login to Clarity itself.

If Okta is already connected, edit the application to set it as your SSO provider.

Step 12: Configure SSO Settings in Clarity

Head to Settings > SSO in Clarity and make the following changes. Leave the Off - On toggle (top right) set to Off for now. You will turn it on in Step 14 after testing.

  • Choose Okta from the dropdown for SSO IDP

  • Entity ID - This is the Identity Provider Issuer from Step 9 above.

  • Login URL - This is the Identity Provider Single Sign-On URL from Step 9 above.

  • Logout URL - This is the Identity Provider Single Logout URL from Step 9 above. Do not leave this blank. With Enable SSO on, sign-out fails without it.

  • x509 Certificate - This is the X.509 Certificate from Step 9 above, including the BEGIN and END lines.

Click Save Edits.

Step 13: Test before you enable

The SSO endpoints work even while the toggle is Off, so you can test safely. They use the values you saved in Step 12, so save first. Until SSO IDP is saved as Okta, every test sign-in ends in "Unknown identity". Because SSO is still off, signing out after the test ends the Clarity session only, without going through Okta.

  1. In a private browser window, open https://YOURDOMAIN.claritysecurity.io/saml2/okta/login

  2. Sign in with an Okta account that is assigned the app and has an active Clarity identity.

  3. You should land on the Clarity home page signed in as that person.

If you see "SAML 2 Error - Ask Admin to check settings", the Entity ID or x509 Certificate in Step 12 does not match Okta. If you see "Unknown identity", the email Okta sent does not match an active Clarity identity or existing Clarity user.

Step 14: Enable SSO

Once the test works, return to Settings > SSO, toggle Off - On to On (top right) and click Save Edits. You're all set.

From now on, anyone who opens https://YOURDOMAIN.claritysecurity.io is sent to Okta to sign in. Local password login and password reset are turned off while SSO is enabled, including the /login page.


Signing Out

When Enable SSO is on and a user who signed in through Okta clicks Sign out, Clarity sends a signed logout request to the Logout URL. Okta ends the Okta session and sends its logout response back to Clarity, and only then does Clarity end the Clarity session. If the Logout URL is blank, or Okta cannot validate the request (for example because the PEM key from Step 5b was not uploaded), the sign-out fails and the user stays signed in to Clarity.

Users who signed in with a local password before SSO was enabled are signed out of Clarity only.

Troubleshooting

Symptom

Likely cause

Fix

"SAML 2 Error - Ask Admin to check settings"

Entity ID or x509 Certificate in Clarity does not match Okta

Re-copy the values from the Okta Sign On tab

"Unknown identity"

The email in the SAML response matches no active Clarity identity or user

Check the person's identity in Clarity and the email attribute in Step 6

"Your Clarity account is not active. Contact your Clarity administrator."

The person's Clarity identity is inactive

Reactivate the identity or remove their Okta assignment

Okta error "The SAML Response is not valid" or Audience mismatch

Single sign-on URL or Audience URI in Okta is wrong

Compare against the values in Step 5

Sign out shows an error, or the user is still signed in to Clarity afterwards

Logout URL is blank, or the Single Logout settings or PEM key in Okta do not match

Complete Step 5b and enter the Logout URL in Step 12

Admins locked out after enabling SSO

SSO enabled with a bad configuration

Contact Clarity Support to disable SSO on your tenant, then repeat Step 13 before enabling again

Certificate Renewal

Okta signing certificates expire. When Okta issues a new certificate for the app, copy the new X.509 Certificate into the x509 Certificate field in Settings > SSO and click Save Edits. Do this before the old certificate expires or users will be unable to sign in. Once it has expired, nobody can sign in through Okta to update it, administrators included; see the locked-out row in Troubleshooting.


Need Help?

If you have any problems, contact your customer success team. You can also get in touch with our general support via email, open a support ticket. Our general support team is available Monday - Friday from 8:00 AM - 6:30 PM CST.