> For the complete documentation index, see [llms.txt](https://docs.collibra.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.collibra.com/data-quality-self-hosted/admin-configuration/admin-console/user-management/sso-for-api-usage/configuring-an-externally-managed-jwt.md).

# Configuring an externally managed JWT

This recommended method allows you to manage the generation and retrieval of access tokens. Once you have an access token, you can then call the API by including it as an authorization bearer token in the request header. Data Quality & Observability (self-hosted) processes and validates this token and maps the user roles to grant users access to the application.

{% hint style="warning" %}
In multi-tenant environments, each tenant must have a unique client ID (client\_id) from the Identity Provider (IdP). The DQ Application supports a one-to-one relationship between client IDs used for client tokens and DQ tenants. Therefore, if you need SSO for API usage using client tokens for multiple DQ tenants, you need to set up multiple applications on the IdP side.
{% endhint %}

The SSO for API Usage configuration page is available on the **Admin Console** under **User Management**.

![Image of SSO for API Usage page](https://4121921244-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWCrP7Albs8DfJjIQxUxw%2Fuploads%2Fgit-blob-d8a576245764363c0fd7ff2e70db0b7762fef970%2Fdq-externally-managed-jwt.png?alt=media)

It contains the following settings:

<table><thead><tr><th width="152">Field</th><th>Description</th></tr></thead><tbody><tr><td>Allow External Tokens</td><td>Enables externally managed JWT tokens.</td></tr><tr><td>Enable DQ proxy to IdP</td><td>Instructs DQ Web to request JWT tokens on behalf of the customer.</td></tr><tr><td>IdP Token URL</td><td><p>The token endpoint URL of the identity provider (IdP).</p><div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title="Example" data-icon="glasses-round"><p>https://&#x3C;your_domain>/oidc/2/token</p></div></div></td></tr><tr><td>Grant Type</td><td><p>The grant type used for authentication. Options are:</p><ul><li><strong>Password</strong>. Tokens are associated to a user.</li><li><strong>Client Credentials</strong>. Tokens are associated to a client or service instead of a user.</li></ul></td></tr><tr><td>clientId</td><td>The client ID. Required if <strong>Client Credentials</strong> is selected in the <strong>Grant Type</strong> field. To assign permissions to the client ID, open the <strong>AD Security</strong> page under <strong>User Management</strong>, click the <strong>Mappings</strong> tab, and then map the client ID to a role. The client ID displays in the <strong>Groups</strong> column for the assigned role. The same clientId must also be specified in the <code>aud</code> parameter in the JSON payload of the JWT.</td></tr><tr><td>Parameters</td><td><p>Static query parameters that are appended to the call to the IdP. This is typically found in the URL of the IdP and is specific to the IdP implementation. Optional if <strong>Client Credentials</strong> is selected in the <strong>Grant Type</strong> field.</p><div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title="Example" data-icon="glasses-round"><p>client_id=012345a6-abc1-012a-0ab1-01a23b45cd6789012</p></div></div></td></tr><tr><td>Role Claim Attribute</td><td><p>Attributes in the claims array from the access_token that define where DQ roles and user groups should be mapped. Used only if <strong>Password</strong> is selected in the <strong>Grant Type</strong> field.</p><div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title="Example" data-icon="glasses-round"><p>params,Groups</p></div></div></td></tr><tr><td>Scope</td><td><p>Optional. IdP-specific properties that define the scope of what is returned in the access_token from the OAuth or OIDC request. Typically associated with the token specified in the <strong>clientID</strong> field.</p><div data-gb-custom-block data-tag="tabs"><div data-gb-custom-block data-tag="tab" data-title="Example" data-icon="glasses-round"><p>openid groups params profile</p></div></div></td></tr></tbody></table>

## Steps

{% tabs %}
{% tab title="Standalone" %}
{% stepper %}
{% step %}
Sign in to Data Quality & Observability (self-hosted) and click <img src="https://4121921244-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWCrP7Albs8DfJjIQxUxw%2Fuploads%2Fgit-blob-268a786d787f353b92e094a60945df32bf9cb208%2FCogwheelIcon.svg?alt=media" alt="Cogwheel icon" data-size="line"> in the left navigation pane.
{% endstep %}

{% step %}
Click **Admin Console**.
{% endstep %}

{% step %}
Click **Configuration Settings**, then click **Application Config**.\ <i class="fa-chevrons-right">:chevrons-right:</i> The Application Configuration Settings page opens.
{% endstep %}

{% step %}
Set the **SSO\_API** setting to **TRUE**.
{% endstep %}

{% step %}
From the Admin Console treeview menu, click **User Management**, then **API for SSO Usage**.\ <i class="fa-chevrons-right">:chevrons-right:</i> The SSO for API Usage page opens.
{% endstep %}

{% step %}
Select the **Allow External Tokens** option to enable the acceptance of externally managed JSON Web Tokens (JWT).
{% endstep %}

{% step %}
Set the following properties in the owl-env.sh script:

| Property                                                                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `export SECURITY_JWT_ALLOW_EXTERNAL=true`                                     | Enables this globally in Data Quality & Observability (self-hosted), but still requires each tenant to enable this in the Allow External Tokens option from the SSO for API Usage from the User Management section of the Admin Console menu.                                                                                                                                                                                                                                                                                                                                                                            |
| `export SECURITY_JWT_EXTERNAL_ROLE_CLAIM_ATTRIBUTE=<claim attribute>`         | Maps to a property in the JWT that holds an array of ROLES that Data Quality & Observability (self-hosted) uses to map users to roles. Not used if **Client Credentials** is selected in the **Grant Type** field.                                                                                                                                                                                                                                                                                                                                                                                                       |
| `export SECURITY_JWT_EXTERNAL_USERNAME_PROPERTY=<username>`                   | Maps to a property in the JWT that Data Quality & Observability (self-hosted) displays as the username. Not used if **Client Credentials** is selected in the **Grant Type** field.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `export SECURITY_JWT_TENANT_PROPERTY=<tenant>`                                | Required in multi-tenant environments. This property is included in the JWT claims to identify the Data Quality & Observability (self-hosted) tenant that users are logging into. Not used if **Client Credentials** is selected in the **Grant Type** field.                                                                                                                                                                                                                                                                                                                                                            |
| `export SECURITY_JWT_TOKEN_ISSUER=<iss>`                                      | The issuer of the JWT that is included in the process to validate the token.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `export SECURITY_JWT_TOKEN_JWKPROVIDERURL=<cert endpoint exposed by the IdP>` | <p>An endpoint of the IdP where the certificates can be retrieved. This property is used to validate the token.</p><p>You can retrieve the cert endpoint by accessing the oidc/.well-known/openid-configuration endpoint to return the jwks\_uri in the response. For example, when you access <strong>https\://{{subdomain}}.onelogin.com/oidc/2/.well-known/openid-configuration</strong>, the response shows the jwks\_uri as <code>"jwks\_uri": "https\://{{subdomain}}.onelogin.com/oidc/2/certs"</code>. In this case, the cert endpoint is <strong>https\://{{subdomain}}.onelogin.com/oidc/2/certs</strong>.</p> |
| {% endstep %}                                                                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

{% step %}
Restart the Data Quality & Observability (self-hosted) web application.
{% endstep %}
{% endstepper %}

#### Example of the JSON payload of a JWT

The following is an example of the decoded JSON payload of a JWT:

```
{
  "sub": "123456789",
  "preferred_username": "example.user",
  "name": "Example User",
  "updated_at": 1234567890,
  "given_name": "Example",
  "family_name": "User",
  "groups": [
    "CollibraAdmin"
  ],
   "tenant": "public",
   "post_logout_redirect_uri": "http://localhost:9000/logout",
   "accountName": "example.user"
  },
  "aud": "012345a6-abc1-012a-0ab1-01a23b45cd6789012",
  "exp": 1234567890,
  "iat": 1234567890,
  "iss": "https://<subdomain>.onelogin.com/oidc/2"
}
```

In this example, the values used in the owl-env.sh correspond to the JSON payload properties as follows:

<table><thead><tr><th width="152">owl-env.sh property</th><th>Value</th></tr></thead><tbody><tr><td><code>SECURITY_JWT_EXTERNAL_USERNAME_PROPERTY</code></td><td>example.user</td></tr><tr><td><code>SECURITY_JWT_TENANT_PROPERTY</code></td><td>tenant</td></tr><tr><td><code>SECURITY_JWT_TOKEN_ISSUER</code></td><td>https://&#x3C;subdomain>.onelogin.com/oidc/2</td></tr></tbody></table>

In addition, the value `aud` must use the same client ID specified in the clientid field on the SSO for API Usage configuration page and in the role mappings.
{% endtab %}

{% tab title="Kubernetes" %}
{% stepper %}
{% step %}
Sign in to Data Quality & Observability (self-hosted) and click <img src="https://4121921244-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWCrP7Albs8DfJjIQxUxw%2Fuploads%2Fgit-blob-268a786d787f353b92e094a60945df32bf9cb208%2FCogwheelIcon.svg?alt=media" alt="Cogwheel icon" data-size="line"> in the left navigation pane.
{% endstep %}

{% step %}
Click **Admin Console**.
{% endstep %}

{% step %}
Click **Configuration Settings**, then click **Application Config**.\ <i class="fa-chevrons-right">:chevrons-right:</i> The Application Configuration Settings page opens.
{% endstep %}

{% step %}
Set the **SSO\_API** setting to **TRUE**.
{% endstep %}

{% step %}
From the Admin Console treeview menu, click **User Management**, then **API for SSO Usage**.\ <i class="fa-chevrons-right">:chevrons-right:</i> The SSO for API Usage page opens.
{% endstep %}

{% step %}
Select the **Allow External Tokens** option to enable the acceptance of externally managed JSON Web Tokens (JWT).
{% endstep %}

{% step %}
Set the following properties in the **values.yaml** file:

```
 global:
                    web:
                    security:
                    externalJwt:
                    enabled: false
                    externalRoleClaim: "groups"
                    externalUserNamePropName: "accountName"
                    externalTenantPropName: "tenant"
                    externalTokenIssuer: ""
                externalTokenJwkProviderURL: ""
```

{% endstep %}

{% step %}
Restart the Data Quality & Observability (self-hosted) web pod.
{% endstep %}
{% endstepper %}

#### Example of a JSON payload of a JWT

The following is an example of the JSON payload of a JWT:

```
{
  "sub": "123456789",
  "preferred_username": "example.user",
  "name": "Example User",
  "updated_at": 1234567890,
  "given_name": "Example",
  "family_name": "User",
  "groups": [
    "CollibraAdmin"
  ],
   "tenant": "public",
   "post_logout_redirect_uri": "http://localhost:9000/logout",
   "accountName": "example.user"
  },
  "aud": "012345a6-abc1-012a-0ab1-01a23b45cd6789012",
  "exp": 1234567890,
  "iat": 1234567890,
  "iss": "https://<subdomain>.onelogin.com/oidc/2"
}
```

In this example, the values used in the Web ConfigMap correspond to the JSON payload properties as follows:

<table><thead><tr><th width="152">Web ConfigMap property</th><th>Value</th></tr></thead><tbody><tr><td><code>SECURITY_JWT_EXTERNAL_USERNAME_PROPERTY</code></td><td>example.user</td></tr><tr><td><code>SECURITY_JWT_TENANT_PROPERTY</code></td><td>tenant</td></tr><tr><td><code>SECURITY_JWT_TOKEN_ISSUER</code></td><td>https://&#x3C;subdomain>.onelogin.com/oidc/2</td></tr></tbody></table>

{% hint style="info" %}
If **Client Credentials** is selected in the **Grant Type** field, the client ID specified in the **clientId** field must also be specified in the `aud` parameter in the JSON payload.
{% endhint %}
{% endtab %}
{% endtabs %}