> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/get-started/onboarding-to-ox/connect-to-ox/sign-in-to-ox/logging-into-okta.md).

# SSO with Okta

Okta is an identity and access management platform that supports OpenID Connect (OIDC) for secure single sign-on.

OX supports OIDC SSO with Okta so your users can sign in to OX with their company credentials.

This guide shows how to create an OIDC Web Application in Okta, connect it to OX, and optionally use Okta groups to control OX roles and scopes.

## Prerequisites

* Okta Admin Console permissions to create applications and manage groups.
* OX Owner or Admin permissions.

## Step 1: Create the OIDC application \[Okta]

Create an OpenID Connect (OIDC) Web Application in Okta that represents OX. This app sets the redirect URI and provides the Client ID and Client Secret you need when connecting to OX.

**To create the OIDC application:**

1. Sign in to the **Okta Admin Console**.
2. Select **Applications** > **Applications** > **Create App Integration**, and set the following:

* **Sign-in method:** **OIDC – OpenID Connect**.
* **Application type:** **Web Application**.

3. Select **Next**, and set the following:

* **App integration name:** enter a clear name, for example, **OX Security SSO**.
* **Sign-in redirect URIs:** add your OX callback URL. Take the URL from the [Okta Configuration ](https://app.ox.security/settings?tab=login\&loginOption=Okta)dialog box (<https://app.ox.security/settings?tab=login\\&loginOption=Okta>).

4. Select **Save**.

## Step 2: Get Client ID and Client Secret \[Okta]

* In the **Okta Admin Console**, go to **Applications > Applications > your app >** **General**, and find and copy: **Client ID** and **Client Secret**.

## Step 3: Configure SSO in OX \[OX]

1. In the OX platform, go to **Settings** > **Login Settings** and select **Okta**. The [Okta Configuration](https://app.ox.security/settings?tab=login\&loginOption=Okta) dialog box opens.

<figure><img src="/files/fbACdhetrOhcTEyfGK6Z" alt="" width="511"><figcaption></figcaption></figure>

<table><thead><tr><th width="219">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Okta Domain</strong></td><td>Add your Okta domain (for example, <code>https://your-domain.okta.com</code>).</td></tr><tr><td><strong>Client ID</strong></td><td>Paste the Client ID from the Okta app.</td></tr><tr><td><strong>Client Secret</strong></td><td>Paste the Client Secret from the Okta app.</td></tr><tr><td><strong>Enable auto provisioning</strong></td><td>Enable this option if you want users to sign in without inviting them in the OX Members page and to control roles and scopes using Okta groups.<br><strong>Note:</strong><br>- If you do not configure auto-provisioning with roles, users who are not invited from the OX Members page sign in as <strong>Read Only</strong> by default.<br>- If you configure auto-provisioning with roles, manage role assignments only in Okta. Role changes in the OX Members page are ignored for users who sign in with Okta SSO.</td></tr><tr><td><strong>Sync OX Group Roles</strong></td><td>Roles define the permission level a user has in OX (Admin, Developer, Policy Manager, Read Only). When you map Okta groups to OX roles, Okta becomes the single source of truth for who can do what. This reduces manual changes in OX, enforces least-privilege, and keeps audits simple because access is managed in one place.</td></tr><tr><td><strong>Sync OX Group Scopes</strong></td><td>Scopes control what data and assets a user can see or manage in OX (for example by application owner or by tag). Mapping Okta groups to OX scopes lets you segment access cleanly across teams, business units, or projects. You keep sensitive areas visible only to the right people, and visibility updates follow org changes in Okta automatically.</td></tr></tbody></table>

2. Select **Save**.

## Step 4: Assign users to the app \[Okta]

1. In the **Okta Admin Console**, go to **Applications > your app > Assignments**
2. Select **Assign**, and assign **People** and **Groups** who can sign in to OX.
3. Select **Save**.

## Step 5: Enable app-initiated login and catalog visibility \[Okta]

1. In the **Okta Admin Console**, go to **Applications > your app** > **General** > **App Settings** > **Edit**.
2. **Login initiated by:** select **Either Okta or App**.
3. Select **Display application icon to users**.
4. **Initiate login URI:** Take the URL from the [Okta Configuration ](https://app.ox.security/settings?tab=login\&loginOption=Okta)dialog box (<https://app.ox.security/settings?tab=login\\&loginOption=Okta>).

> **Note:** For On-Prem\
> [`https://app.ox.security/sso-login?organization=`](https://app.ox.security/sso-login?organization=)`<ORG_ID>&organization_name=<ORG_SLUG>&display_name=<DISPLAY_NAME>Example:`\
> <https://app.ox.security/sso-login?organization=org_XXX&organization_name=d7992de2-acme&display_name=acmeorg&connection=okta-acme>

5. Select **Save**.

## Step 6: Map Okta groups to OX roles \[Okta and OX]

This step enables the automatic assignment of [OX Security roles](/admin-settings/roles.md) based on user groups in your IdP. There are the following types of roles:

* Roles predefined by OX,
* Custom roles.

### Create user groups for predefined roles

Each predefined role group requires a prefix. The default is: OXApp-. You can change the default prefix to a custom one.

**To change the default prefix:**

1. Go to **Settings > Login > \[IdP icon]** and enter a different prefix.

<figure><img src="/files/oRhlBQe1HzRypIE0yyAC" alt="" width="464"><figcaption></figcaption></figure>

2. **Create IdP role groups:** In your IdP, go to **Directory > Groups** and create groups using these exact names (case-sensitive) for each OX role you want to sync:

* OXApp-Admin
* OXApp-Developer
* OXApp-Dev Manager/Security Champion
* OXApp-Policy Manager
* OXApp-Read Only

### Create user groups for custom roles

In case you have custom role(s) defined in OX, you need to create groups using the exact labels OX generates for your custom roles. The label is different from the custom role name.

You can view the custom role label only in the instructions provided by OX within the Configuration dialog.

**To locate the custom role label:**

1. Go to **Settings > Login > \[IdP icon]** and in the instruction box, select **+**.
2. Scroll down in the instructions box until you get to **Advanced settings (auto provisioning) - Setting roles**.
3. Read the procedure. The custom role label appears next to the custom role name in brackets. You cannot change it.
4. Use this label as the name of your new group in IdP.

**For example:**

I know that the admin defined a custom role called Executive Viewer. If I am looking for the label that OX generated for the custom role Executive Viewer, first I locate the custom role Executive Viewer in brackets and then I can see that OX generated a label for this custom role "OXApp-CustomRole1".

<figure><img src="/files/E6mKkKR0D7NX0ifoUxIZ" alt="" width="489"><figcaption></figcaption></figure>

### **Complete the process**

1. **Map group attributes**: In your IdP, ensure you have groups attribute mapping enabled.
2. **Enable sync:** In OX, go to **Settings > Login > \[IdP icon]** and enable **Sync OX Group Roles** using the prefix you selected.
3. Select **Save**.
4. In the IdP, assign users who need that specific scope access as members of the corresponding group.

## Step 7: Map Okta groups to OX scopes \[Okta and OX]

1. In the **Okta Admin Console**, go to **Directory** > **Groups**
2. Select **Add group**.
3. Name the scope groups by using the following naming conventions.

<details>

<summary>App owner and other UI-visible scopes</summary>

For scopes that are available in the OX scope selector:

1. In OX, click the **scope selector** in the top navigation bar (for example, **Entire Organization**).
2. Select the scope that you want to map.
3. Click the information icon next to the scope.
4. In the details panel, copy the value from the **SSO Group String** field.
5. Use the copied value as the Okta group name.

The **SSO Group String** is generated automatically by OX.

Example:

```
OXAppOwnerScope-DevOps-id:devops@acme.com
```

</details>

<details>

<summary>Tag scopes</summary>

Tag scopes are not displayed in the scope selector, so OX does not generate an **SSO Group String** for them.

Instead, create the Okta group name by using the following format:

```
OXTagScope-<TAG_NAME>-id:<TAG_ID>
```

Example:

```
OXTagScope-app-id:acme-app
```

Replace:

* `<TAG_NAME>` with the tag name.
* `<TAG_ID>` with the unique ID of the tag.

The tag ID is not available in the OX user interface. To obtain it, use the OX API to retrieve the tag details, and then use the returned tag ID when constructing the group name.

> **Note:** Tag IDs can currently be retrieved only through the OX API by using the **Get Single Tag** endpoint.

</details>

4. Open each new group, select **Assign people**, and add the relevant users or groups.
5. Go to **Applications > your app >** **Sign On** . **OpenID Connect ID Token** . **Edit**
6. **Group claim type:** **Filter**.
7. **Group claim filter:** **groups** **Matches regex** `.*`
8. Select **Save**.
9. In the OX platform, go to **Settings > Login Settings** and enable **Sync OX Group Scopes**.

## Step 8: Test the sign-in \[OX]

1. In the OX platform, go to `https://<ENV>.app.ox.security/`.
2. Select **Sign in with Okta** and sign in with a user you assigned.
3. If you configured the **Initiate login URI**, you can open that link to start the flow directly.

## Troubleshooting

| Symptom                            | Where to fix | What to check                                                                                                                          |
| ---------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| Invalid redirect URI               | Okta         | The **Sign-in redirect URIs** entry must exactly match `https://auth.<ENV>.app.ox.security/login/callback`.                            |
| Invalid client or secret           | OX and Okta  | Paste the exact **Client ID** and **Client Secret** from the Okta app. Ensure the secret is valid.                                     |
| User not authorized to use the app | Okta         | Applications → your app → **Assignments**. Ensure the user or their group is assigned.                                                 |
| Roles do not match after sign-in   | Okta and OX  | Verify the user’s Okta group membership. Ensure **Group claim filter** includes groups and **Sync OX Group Roles/Scopes** is on in OX. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ox.security/get-started/onboarding-to-ox/connect-to-ox/sign-in-to-ox/logging-into-okta.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.