> 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/trust-platform/sso-configurations/okta.md).

# Okta (SAML / OIDC)

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

{% hint style="info" %}
**Before you begin:** Access Trust and copy the **Identifier** and **Reply URL** fields as described in [Step 2 of the SSO Configuration Guide](/caf-docs/user-guide/trust-platform/sso-configurations.md#passo-2-selecionar-protocolo-e-obter-dados).
{% endhint %}

***

## Prerequisites

* Administrator access to Okta
* Administrator access to Trust
* Verified corporate email domain

***

## 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="/files/q7XEihLWyNz6D1cZjUl8" alt="Okta - Create App Integration"></div>

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

<div data-with-frame="true"><img src="/files/Jq7hFy5JVYntpK5r2rS7" alt="Okta - Select SAML 2.0"></div>

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

<div data-with-frame="true"><img src="/files/0wM8tkTDa0FI9bXiXDQE" alt="Okta - App Name"></div>

#### Configure SAML Settings

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

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

<div data-with-frame="true"><img src="/files/oXzFHJfoSMFQ99Hsf8If" alt="Okta - SAML Settings"></div>

#### Configure Attribute Statements

Configure the attributes that will be sent to Trust:

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

<div data-with-frame="true"><img src="/files/Ndb6MVKJ18KTOywEq1Qu" alt="Okta - Attribute Statements"></div>

#### Configure Group Attribute Statements (Optional)

If you want to use custom group mapping:

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

<div data-with-frame="true"><img src="/files/NBN7CkIPJycTrPgtMuog" 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="/files/MRABJJpsduH5u2UfwOIe" 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="/files/q7XEihLWyNz6D1cZjUl8" 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="/files/Pv3VNecYvyAFVXeKKCCS" alt="Okta - Select OIDC"></div>

#### Configure OIDC Settings

| Okta Field                 | Value                                           |
| -------------------------- | ----------------------------------------------- |
| **App integration name**   | (e.g., "Trust - Caf")                           |
| **Grant type**             | ✅ Authorization Code                            |
| **Sign-in redirect URIs**  | Paste the **Reply URL** copied from Trust       |
| **Sign-out redirect URIs** | Paste the **Trust URL** <https://trust.caf.io/> |
| **Controlled access**      | Select who can access the application           |

<div data-with-frame="true"><img src="/files/dFVnCH26HujhQPO4iVYL" alt="Okta - OIDC Settings"></div>

Click **Save**.

#### Get Credentials

In the created application, copy the following information:

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

<div data-with-frame="true"><img src="/files/9Smcpn0YkBtFU34C5cpp" 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**
2. Access **API** -> **Authorization Servers**
3. Copy the Issuer URL
   {% endhint %}

<div data-with-frame="true"><img src="/files/enK5SsTlFkQqhZ52mmqS" alt="Okta - Authorization Server Issuer"></div>

{% hint style="warning" %}
If you plan to use **Custom** mode for permission group mapping, configure the step below. Otherwise, skip to the [Assign Users or Groups](#atribuir-usuarios-ou-grupos) step.
{% endhint %}

#### Configure Group Scopes (Optional)

To include groups in tokens:

1. Access **Security** → **API** → **Authorization Servers**
2. Select the Authorization Server being used (e.g., "default")
3. Click the edit option

<div data-with-frame="true"><img src="/files/AnoTsBn7mz5LWIzMKKzS" alt="Okta - Add Groups Claim"></div>

4. Access the **Scopes** tab
5. Click **Add Scope**

<div data-with-frame="true"><img src="/files/1thEpfGVMtYYqsNaZfvT" alt="Okta - Add Groups Claim"></div>

Fill in the scope following the information below. If you already have a groups scope created, use the same scope in Trust as well. [Configure Properties and Scopes](/caf-docs/user-guide/trust-platform/sso-configurations.md#passo-2-selecionar-protocolo-e-obter-dados)

<div data-with-frame="true"><img src="/files/K2R1nzFqzgTbfE4gUHEn" alt="Okta - Add Groups Claim"></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="/files/OetYPpAPv5MiGMI0Fk3R" alt="Okta - Assignments"></div>

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

<div data-with-frame="true"><img src="/files/uRovUuptFR6MocGZfGTi" alt="Okta - Assignments"></div>

5. Click **Save and Go Back**

<div data-with-frame="true"><img src="/files/XJjJWESqJJYe4I7GMdxL" alt="Okta - Assignments"></div>

***

## Next Steps

After configuring Okta, return to the [Trust SSO Configuration Guide](/caf-docs/user-guide/trust-platform/sso-configurations.md) to:

1. [Configure Properties and Scopes](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-2-select-protocol-and-obtain-data)
2. [Configure Permission Groups](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-3-configure-permission-groups)
3. [Configure Attribute Statements](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-4-configure-attribute-statements)
4. [Configure Domains](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-5-configure-domains)
5. [Save and Test](/caf-docs/user-guide/trust-platform/sso-configurations.md#step-6-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 Trust |
| 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/trust-platform/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.