> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Okta SAML SSO (Okta Integration Network)

Opal Security is available in the [Okta Integration Network (OIN)](https://www.okta.com/integrations/), so you can set up SAML single sign-on without building a custom SAML app. Sign-on settings and attribute mappings come pre-configured — you only provide your Opal organization ID and exchange two values between Okta and Opal.

This guide is for **Opal SaaS** customers. If you run a self-hosted or airgapped Opal deployment, follow the [custom SAML app setup guide](https://docs.opal.dev/docs/okta-saml-setup.md) instead.

## Prerequisites

Before you configure the integration, make sure you have:

* **An Opal SaaS organization.** The OIN app only supports Opal SaaS. Self-hosted and airgapped deployments must use the [custom SAML app setup guide](https://docs.opal.dev/docs/okta-saml-setup.md).
* **Opal**: an account with admin access to your organization's settings, so you can open the **SAML SSO** setup modal.
* **Okta**: an account with permission to add app integrations and assign users (for example, super admin, or app and org admin).
* **Matching user emails.** Each user's email address in Okta must exactly match the email on their Opal account. Opal accounts are typically provisioned through an [identity provider integration](https://docs.opal.dev/integrations/okta-idphris-integration.md) before enabling SAML SSO.

## Supported features

* **SP-initiated SSO**: users start from Opal's sign-in page and are redirected to Okta to authenticate. See [SP-initiated SSO](#sp-initiated-sso).
* **IdP-initiated SSO**: users launch Opal from the Opal Security tile on their Okta End-User Dashboard.

The following features are **not** supported by this integration:

* **Just-In-Time (JIT) provisioning**: signing in via SAML does not create an Opal account. Users must already exist in Opal with a matching email address.
* **SP-initiated Single Logout (SLO)**: signing out of Opal does not end the Okta session.

For definitions of these features, see the [Okta Glossary](https://help.okta.com/okta_help.htm?type=oie\&id=csh-glossary).

## Configuration steps

### Step 1: Find your Opal organization ID

1. In Opal, go to **Settings** and open the **SAML SSO** setting.

2. In the setup modal, locate the **ACS URL**. It looks like:

   ```
   https://auth.opal.dev/login/callback?connection=saml-a1b2c3d4-...
   ```

3. Your organization ID is the value after `connection=saml-`. Copy it — you'll enter it in Okta in the next step.

Keep this modal open; you'll return to it in Step 3.

### Step 2: Add the Opal Security app in Okta

1. In the Okta Admin Console, go to **Applications > Applications** and select **Browse App Catalog**.
2. Search for **Opal Security** and select **Add integration**.
3. When prompted for the **Opal organization ID**, paste the value from Step 1.
4. Save the integration.

The SAML sign-on settings and attribute mappings (`given_name`, `family_name`, and `email`) are already configured — you don't need to change anything on the **Sign On** tab.

### Step 3: Connect Okta to Opal

1. In Okta, open the Opal Security app and go to the **Sign On** tab.
2. Under the SAML setup instructions, copy the **Identity Provider Single Sign-On URL** and download the **X.509 Certificate**.
3. Back in Opal's **SAML SSO** setup modal:
   * Paste the URL into **Identity Provider SAML 2.0 SSO URL**.
   * Upload the downloaded certificate under **Identity Provider Public Certificate**.
4. Save the configuration.

### Step 4: Assign users

In Okta, open the Opal Security app's **Assignments** tab and assign the users or groups who should be able to sign in to Opal.

A user's email address in Okta must exactly match the email on their Opal account. Users whose emails don't match will not be able to sign in via SAML.

### Step 5: Test the connection

1. In an incognito or private browser window, go to your Opal sign-in page.
2. Sign in with SAML using an assigned Okta account, following the [SP-initiated SSO](#sp-initiated-sso) flow below.
3. Confirm you land in Opal signed in as that user.

## SP-initiated SSO

To sign in to Opal starting from Opal's sign-in page:

1. Go to [https://app.opal.dev](https://app.opal.dev).
2. Enter your email address and continue.
3. Under your organization, select **Continue with SAML**.
4. You are redirected to Okta to authenticate. Enter your Okta credentials.
5. After Okta verifies your credentials, you are redirected back to Opal and signed in.

Users can also sign in with IdP-initiated SSO by selecting the **Opal Security** tile on their Okta End-User Dashboard.

## Optional: Require SAML for all logins

Once you've verified SAML sign-in works, you can require it for your whole organization by enabling **Restrict login to SAML** in Opal's **SAML SSO** settings. We recommend designating break-glass users first so admins retain access if your identity provider is unavailable.

## Troubleshooting

| Issue | Resolution |
| - | - |
| User sees an error after Okta sign-in | Confirm the user's Okta email matches their Opal account email exactly. |
| User doesn't see Opal in their Okta dashboard | Confirm the user or one of their groups is assigned to the app in Okta. |
| Sign-in redirects fail after certificate rotation | Download the new X.509 certificate from the app's **Sign On** tab and re-upload it in Opal's SAML SSO settings. |
| You use self-hosted Opal | This app only supports Opal SaaS. Follow the [custom SAML app setup guide](https://docs.opal.dev/docs/okta-saml-setup.md). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.