> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-docs/user-guide/organizations/sso-configurations/okta.md).

# Okta (SAML / OIDC)

Configure SSO with Okta using SAML or OIDC protocols.

This guide explains how to configure SSO integration between Organizations and Okta. After configuring Okta, return to the [Organizations SSO Configuration Guide](/caf-docs/user-guide/organizations/sso-configurations.md) to complete the setup.

{% hint style="info" %}
**Before you begin:** Open **Authentication** → **SSO** in Organizations and copy the **Entity ID** and **ACS URL** (SAML) or **Redirect URI** (OIDC) as described in [Step 2 of the SSO Configuration Guide](/caf-docs/user-guide/organizations/sso-configurations.md#step-2-enable-sso-and-configure-the-provider).
{% endhint %}

***

## Prerequisites

* Administrator access to Okta
* Super Admin access to Organizations

***

## Choose the Protocol

{% tabs %}
{% tab title="SAML" %}

## SAML Configuration

### Create Application in Okta

1. Access the [Okta Admin Console](https://admin.okta.com)
2. Navigate to **Applications** → **Applications**
3. Click **Create App Integration**

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-26c690a7368d8134b306649150c43c0382d6f84d%2Fokta-create-app-integration.jpg?alt=media" alt="Okta - Create App Integration"></div>

4. Select **SAML 2.0** and click **Next**

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-06d677536c05dbc2243b86a196e25cfb07eee1ef%2Fokta-select-saml.jpg?alt=media" alt="Okta - Select SAML 2.0"></div>

5. Configure the **App name** (e.g., "Certta") and click **Next**

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-8d753f018901fee5f0ae9df2a323c3b36afe7c86%2Fokta-saml-app-name.png?alt=media" alt="Okta - App Name"></div>

### Configure SAML Settings

In the **SAML Settings** section, configure:

| Okta Field                      | Value                                             |
| ------------------------------- | ------------------------------------------------- |
| **Single sign-on URL**          | Paste the **ACS URL** copied from Organizations   |
| **Audience URI (SP Entity ID)** | Paste the **Entity ID** copied from Organizations |

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-be2497eaa405362a7e19b9bbe31ca601497f60ad%2Fokta-saml-settings.png?alt=media" alt="Okta - SAML Settings"></div>

### Configure Attribute Statements

Configure the attributes that will be sent to Organizations:

| Name          | Value              |
| ------------- | ------------------ |
| `email`       | `user.email`       |
| `name`        | `user.displayName` |
| `given_name`  | `user.firstName`   |
| `family_name` | `user.lastName`    |

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-54fd6ea6a1749e136db81dfb6a0d4b7bc4fe3c28%2Fokta-saml-attributes.png?alt=media" alt="Okta - Attribute Statements"></div>

### Configure Group Attribute Statements (Optional)

If you use **Group assignment rules** based on IdP groups:

| Name     | Filter                                          |
| -------- | ----------------------------------------------- |
| `groups` | Matches regex: `.*` (or filter specific groups) |

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-9e191024259cb2c9f59fc16274af0d3c3490c9f0%2Fokta-saml-groups.png?alt=media" alt="Okta - Group Attribute Statements"></div>

Click **Next** and then **Finish**.

### Get Metadata URL

1. In the created application, access the **Sign On** tab
2. Copy the **Metadata URL**

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-b8f75484459a2f996167b21beb4373e4b11f9ceb%2Fokta-saml-metadata-url.png?alt=media" alt="Okta - Metadata URL"></div>

The URL will have the format:

```url
https://{your-domain}.okta.com/app/{app-id}/sso/saml/metadata
```

{% endtab %}

{% tab title="OIDC" %}

## OIDC Configuration

### Create Application in Okta

1. Access the [Okta Admin Console](https://admin.okta.com)
2. Navigate to **Applications** → **Applications**
3. Click **Create App Integration**

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-26c690a7368d8134b306649150c43c0382d6f84d%2Fokta-create-app-integration.jpg?alt=media" alt="Okta - Create App Integration"></div>

4. Select **OIDC - OpenID Connect**
5. Select **Web Application** and click **Next**

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-aa9a976a310c10cea577582b8e66762b7057c97a%2Fokta-select-oidc.png?alt=media" alt="Okta - Select OIDC"></div>

### Configure OIDC Settings

| Okta Field                 | Value                                                                        |
| -------------------------- | ---------------------------------------------------------------------------- |
| **App integration name**   | (e.g., "Certta")                                                             |
| **Grant type**             | ✅ Authorization Code                                                         |
| **Sign-in redirect URIs**  | Paste the **Redirect URI** copied from Organizations                         |
| **Sign-out redirect URIs** | Paste your organization URL (for example, `https://{your-alias}.sso.caf.io`) |
| **Controlled access**      | Select who can access the application                                        |

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-adf3974af099c17efef717dc8912497ecd6a0e71%2Fokta-oidc-settings.png?alt=media" alt="Okta - OIDC Settings"></div>

Click **Save**.

### Get Credentials

In the created application, copy the following information:

| Okta Field        | Use in Organizations as |
| ----------------- | ----------------------- |
| **Client ID**     | Client ID               |
| **Client Secret** | Client Secret           |

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-2d2f5ab0284f02ee053842bee24d2cc1635a8e53%2Fokta-oidc-credentials.png?alt=media" alt="Okta - Client Credentials"></div>

### Get Issuer URL

The Okta Issuer URL follows the format:

```
https://{your-domain}.okta.com
```

Or, if you use a custom Authorization Server:

```
https://{your-domain}.okta.com/oauth2/{authorization-server-id}
```

{% hint style="info" %}

1. Navigate to **Security** → **API** → **Authorization Servers**
2. Copy the **Issuer URL** from the Authorization Server you use for this application
   {% endhint %}

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-57ed2690d89908a95893fd015c07c769554b3efb%2Fokta-issuer-url.png?alt=media" alt="Okta - Authorization Server Issuer"></div>

{% hint style="warning" %}
Configure the step below when you use **Group assignment rules** based on IdP groups. Otherwise, skip to [Assign Users or Groups](#assign-users-or-groups).
{% endhint %}

### Configure Group Scopes (Optional)

To include groups in OIDC tokens for **Group assignment rules**:

1. Access **Security** → **API** → **Authorization Servers**
2. Select the Authorization Server being used (for example, `default`)
3. Open the **Claims** tab and add a **groups** claim mapped to user groups
4. Open the **Scopes** tab and add a `groups` scope if your server requires explicit scopes

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-92e1692c57312f88b46cd516704d649c0fb6020e%2Fokta-oidc-add-claim.jpg?alt=media" alt="Okta - Add Groups Claim"></div>

5. Click **Add Scope** if you need a dedicated groups scope

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-d8d742eb3294ca550366a1fb1e02a222fac99e8b%2Fokta-oidc-add-scope.jpg?alt=media" alt="Okta - Add Groups Scope"></div>

6. In Organizations, add `groups` to **Authorization scopes** on the **SSO** tab (for example, `openid email profile groups`) and map **Groups** on the **Attribute mapping** tab to `groups`

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-e1fded8e2a55853eecae4e6f527143641adf64db%2Fokta-oidc-add-scope2.jpg?alt=media" alt="Okta - Groups Scope Details"></div>
{% endtab %}
{% endtabs %}

***

## Assign Users or Groups

1. In the created application, access the **Assignments** tab
2. Click **Assign**
3. Select **Assign to People** or **Assign to Groups**

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-195056875c9127027b64b24d1fb2ebd12d40625c%2Fokta-assignments.jpg?alt=media" alt="Okta - Assignments"></div>

4. Select the users or groups that will have access and click **Assign**

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-406ddf2389a63517ba9fbd778a5ef873f13e65e2%2Fokta-assignments2.jpg?alt=media" alt="Okta - Assignments"></div>

5. Click **Save and Go Back**

<div data-with-frame="true"><img src="https://737907756-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FI4kncOam5KtDqeGMEiQu%2Fuploads%2Fgit-blob-c8f05f229a8c3f01e1010cd2534d2443d1e42e7d%2Fokta-assignments3.jpg?alt=media" alt="Okta - Assignments"></div>

***

## Next Steps

After configuring the identity provider, return to the [Organizations SSO Configuration Guide](/caf-docs/user-guide/organizations/sso-configurations.md) to:

1. [Configure attribute mapping](/caf-docs/user-guide/organizations/sso-configurations.md#step-3-configure-attribute-mapping)
2. [Configure group assignment rules](/caf-docs/user-guide/organizations/sso-configurations.md#step-4-configure-group-assignment-rules)
3. [Save and test](/caf-docs/user-guide/organizations/sso-configurations.md#step-5-save-and-test)

***

## Troubleshooting

| Problem             | Probable Cause              | Solution                                                            |
| ------------------- | --------------------------- | ------------------------------------------------------------------- |
| Redirect URI error  | URI does not match          | Verify that the reply URL is identical in both systems              |
| Invalid token       | Incorrect Client Secret     | Regenerate the Client Secret in Okta and update it in Organizations |
| Groups not received | Groups claim not configured | Configure the groups claim in the Authorization Server              |
| User not found      | User not assigned           | Add the user in the application's **Assignments**                   |

***

## References

* [Okta Documentation - SAML](https://developer.okta.com/docs/concepts/saml/)
* [Okta Documentation - OIDC](https://developer.okta.com/docs/concepts/oauth-openid/)
* [Configure group claims](https://developer.okta.com/docs/guides/customize-tokens-groups-claim/)


---

# 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.caf.io/caf-docs/user-guide/organizations/sso-configurations/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.