# Set up SSO with Okta

Source: https://docs.qualflare.com/docs/administration/sso/okta · Last updated: 2026-11-02

Connect Okta to a Qualflare Enterprise workspace over SAML 2.0: create the app, exchange metadata, set SHA-256 signing, map groups to roles and test sign-in.

To set up single sign-on with Okta for a Qualflare Enterprise workspace, create a SAML 2.0 app in Okta, upload its metadata on the Qualflare **Single Sign-On** page, copy Qualflare's Entity ID and ACS URL back into Okta, and run a test sign-in.

## Before you begin

Available on: Enterprise.

Requires the Owner role in the workspace.

* Admin access to Okta.
* An email domain you can add a DNS TXT record to. See [Verified Domains](https://docs.qualflare.com/docs/administration/verified-domains).
* Saving any change asks **Confirm it’s you** when you last signed in or confirmed more than 5 minutes ago.

## Connect Okta

### Step 1: Create the SAML app in Okta

Create a SAML 2.0 app integration for Qualflare in Okta, as Okta's guide [Create SAML app integrations](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm) describes. Qualflare shows the values the app needs only after step 3, so come back to this app in step 4.

### Step 2: Set SHA-256 signing

Qualflare accepts RSA-SHA256, RSA-SHA384 or RSA-SHA512 signatures over SHA-256, SHA-384 or SHA-512 digests, and refuses SHA-1.

In the Okta app, open **General** > **SAML Settings** > **Edit** > **Show Advanced Settings**. Set **Signature Algorithm** to RSA-SHA256 and **Digest Algorithm** to SHA256. Both must be the SHA256 option: RSA-SHA256 over a SHA1 digest is refused. These are Okta's defaults.

### Step 3: Upload the Okta metadata to Qualflare

Download the app's SAML metadata as an XML file. In Qualflare, open **Single Sign-On** in the workspace sidebar, under **Administration**, upload the file (`.xml`, up to 1 MB) and click **Save connection**. The connection starts disabled. See [Connect your identity provider](https://docs.qualflare.com/docs/administration/sso#connecting-an-identity-provider).

### Step 4: Copy Qualflare's values into Okta

Under **Service provider details**, copy **Entity ID (Audience URI)** and **ACS URL (Reply URL)** with their copy buttons. Paste them into the Okta app as the audience URI and the reply URL, unchanged: Qualflare refuses a sign-in posted to a changed ACS URL, even one with a trailing slash added.

### Step 5: Send the user's email

Have Okta send a persistent, email address or unspecified Name ID. Qualflare refuses a transient one.

Qualflare looks in the attribute you enter in **Email attribute** on the Single Sign-On page, then in an email-address Name ID, then in the first of these attributes that Okta sends:

```text
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
urn:oid:0.9.2342.19200300.100.1.3
email
mail
emailAddress
```

### Step 6: Map groups to roles (optional)

Have Okta send the user's groups in an attribute, and enter that attribute's name in **Group attribute**. Add **Role rules**: the first matching rule wins, and anyone else gets the **Default role**. Click **Save mapping**. See [Map attributes and roles](https://docs.qualflare.com/docs/administration/sso#attributes-and-role-mapping).

### Step 7: Verify your domain and test

Verify your email domain on [Verified Domains](https://docs.qualflare.com/docs/administration/verified-domains). Turn on **Connection enabled** and click **Turn on connection**. Then run a test sign-in from a private browser window: enter an email address at the verified domain on the sign-in page and select **Continue**. **Require SSO** stays off until a test sign-in succeeds.

## Encrypted assertions (optional)

Qualflare accepts an encrypted assertion only with RSA-OAEP key transport and AES content encryption: AES-128, AES-192 or AES-256 in CBC mode, or AES-128-GCM.

In the Okta app, open **General** > **SAML Settings** > **Edit** > **Show Advanced Settings**. With **Assertion Encryption** set to Encrypted, set **Key Transport Algorithm** to RSA-OAEP and **Encryption Algorithm** to AES256-CBC or AES128-CBC. AES128-GCM also works; AES-256-GCM doesn't. Or set **Assertion Encryption** to Unencrypted.

Turn on [Require encrypted assertions](https://docs.qualflare.com/docs/administration/sso#require-encrypted-assertions) in Qualflare only once Okta encrypts, then click **Update connection**. Otherwise every sign-in fails.

## Provision users with SCIM

Once single sign-on works, Okta can add, update and remove workspace members over SCIM 2.0. Paste Qualflare's **SCIM base URL** as "Base URL" and the token as "API Token". See [SCIM Provisioning](https://docs.qualflare.com/docs/administration/scim).

## Verify

You should see the member signed in to the workspace after the test sign-in, and **Require SSO** can now be turned on.

## Troubleshoot

* `Single sign-on failed. Please try again, or contact your workspace owner if it keeps happening.`: Qualflare refused the sign-in. Check the signing settings in step 2 first, then the encryption settings if Okta encrypts.
* A 403 `origin not allowed` error after Okta signs you in: the reply URL in Okta isn't Qualflare's ACS URL exactly. Copy **ACS URL (Reply URL)** again and paste it unchanged.
* `Your email address's domain isn't verified for single sign-on with this workspace yet. Contact your workspace owner.`: verify that domain on [Verified Domains](https://docs.qualflare.com/docs/administration/verified-domains).
* **Logging out of Qualflare didn't sign me out of Okta**: **Log out** ends only the Qualflare session, so the next single sign-on can go straight through. Sign out of Okta too.

## Next steps

* [Require SSO](https://docs.qualflare.com/docs/administration/sso#enforcing-sso) for the members at your verified domains
* [Set the SSO session lifetime](https://docs.qualflare.com/docs/administration/sso#sso-session-lifetime)
* [SCIM Provisioning](https://docs.qualflare.com/docs/administration/scim)
* [Recover from a lockout](https://docs.qualflare.com/docs/administration/sso#recovering-from-a-lockout)