# OpenID Connect (OIDC)

Use these instructions to set up an OpenID Connect (OIDC) SSO provider for Tonic Structural.

## SSO setup <a href="#sso-oidc-sso-setup" id="sso-oidc-sso-setup"></a>

### Configuration requirements

When you configure the application/client in your SSO system, you must configure it to use Authorization Code Flow.

You must also make note of the `client_id`. You must provide the client ID when you complete the configuration for Structural.

### Redirect URIs <a href="#sso-oidc-tonic-redirect-uris" id="sso-oidc-tonic-redirect-uris"></a>

In your SSO provider, configure the following redirect URIs:

* **Sign-in redirect URIs:** For self-hosted instances, the value is  `<tonic-base-url>/sso/callback` .

  \
  For Structural Cloud, the value is `https://app.tonic.ai/sso/callback/<your organization identifier>`. Your organization identifier is displayed on your [**User Settings** view](https://docs.tonic.ai/app/managing-your-tonic-account#user-view-copy-org-id).
* **Sign-out redirect URIs:** `<tonic-base-url>/sso/logout`

### Initiate login URI

To allow users to log in to Structural directly from the OIDC provider, provide an initiate login URI.

For self-hosted instances, the initiate login URI is their base URL for Structural.

For Structural Cloud, the value is `https://app.tonic.ai/sso/login/<your organization identifier>`. Your organization identifier is displayed on your [**User Settings** view](https://docs.tonic.ai/app/managing-your-tonic-account#user-view-copy-org-id).

## Structural configuration - self-hosted <a href="#sso-oidc-structural-self-hosted" id="sso-oidc-structural-self-hosted"></a>

On a self-hosted instance, you use environment settings to configure the connection to OIDC

### Required environment settings <a href="#sso-oidc-tonic-required-env-variables" id="sso-oidc-tonic-required-env-variables"></a>

In the Structural web server container, set the following [Structural environment settings](https://docs.tonic.ai/app/admin/environment-variables-setting):

* `TONIC_SSO_PROVIDER`: `OIDC`
* `TONIC_SSO_CLIENT_ID`: \<application client ID>
* `TONIC_SSO_CLIENT_SECRET`: Only required for HTTP basic authentication (`client_secret_basic`). The client secret.
* `TONIC_SSO_OIDC_AUTHORITY`: The base URL of the provider. This is the location of `/.well-known/openid-configuration`
* `TONIC_SSO_GROUP_FILTER_REGEX`: Identifies the allowed SSO groups for Structural. For details, go to [sso-limit-groups](https://docs.tonic.ai/app/admin/tonic-user-access/single-sign-on/sso-limit-groups "mention").

### **Optional environment settings** <a href="#sso-oidc-tonic-config-optional-env-variables" id="sso-oidc-tonic-config-optional-env-variables"></a>

<table><thead><tr><th width="303.9114583333333" valign="top">Setting</th><th width="209.8046875" valign="top">Default value</th><th valign="top">Description</th></tr></thead><tbody><tr><td valign="top"><code>TONIC_SSO_OIDC_SCOPES</code></td><td valign="top"><code>openid profile email</code></td><td valign="top">The space-delimited list of scopes to request from the OIDC SSO provider.<br><br>Because group information is not part of the standard OIDC specification, for Structural to capture group information, a custom scope must be configured.</td></tr><tr><td valign="top"><code>TONIC_SSO_OIDC_FIRST_NAME_CLAIM_NAME</code></td><td valign="top"><code>given_name</code></td><td valign="top">The name of the claim that contains the user's first name.</td></tr><tr><td valign="top"><code>TONIC_SSO_OIDC_LAST_NAME_CLAIM_NAME</code></td><td valign="top"><code>family_name</code></td><td valign="top">The name of the claim that contains the user's last name.</td></tr><tr><td valign="top"><code>TONIC_SSO_OIDC_EMAIL_CLAIM_NAME</code></td><td valign="top"><code>email</code></td><td valign="top">The name of the claim that contains the user's email/username.</td></tr><tr><td valign="top"><code>TONIC_SSO_OIDC_GROUPS_CLAIM_NAME</code></td><td valign="top"><code>groups</code></td><td valign="top">The name of the claim that contains the user's group membership.</td></tr><tr><td valign="top"><code>TONIC_SSO_OIDC_ADDITIONAL_ENDPOINT_BASE_ADDRESSES</code></td><td valign="top"></td><td valign="top">The space-delimited list of approved secondary domains where your identity provider is allowed to host its login and token services.</td></tr></tbody></table>

## Structural configuration - Structural Cloud <a href="#sso-oidc-structural-cloud" id="sso-oidc-structural-cloud"></a>

{% hint style="info" %}
**Required global permission:** Manage user access to Tonic Structural and to any workspace
{% endhint %}

### Configuring the general connection information <a href="#required-connection-info" id="required-connection-info"></a>

On Structural Cloud, after you [enable SSO](https://docs.tonic.ai/app/admin/tonic-user-access/sso-cloud#enabling-sso), to configure the connection to OIDC:

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FsFYPiIxD64BxJ8cMOGsW%2FCloudSSOEnabledOIDC.png?alt=media&#x26;token=a285b236-1b96-4be7-87be-6fd5f7dedde5" alt=""><figcaption><p>Configuration settings for OIDC SSO on Structural Cloud</p></figcaption></figure>

1. Click **OIDC**.
2. In the **Authority URL** field, provide the base URL of the provider. This is the location of `/.well-known/openid-configuration`.
3. In the **Client ID** field, provide the identifier of the client application.
4. In the **Client Secret** field, for HTTP basic authentication (`client_secret_basic`), provide the client secret.
5. Optionally, in the **Scopes** field, provide a space-delimited list of scopes to request from the OIDC SSO provider.\
   \
   Note that because group information is not part of the standard OIDC specification, for Structural to capture group information, a custom scope must be configured.

### Configuring claims <a href="#connection-claims" id="connection-claims"></a>

If you use claims to store user information, then to identify the claims:

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2Fx9Jmo85qQy3zlx9br9YO%2FCloudSSOEnabledOIDCClaims.png?alt=media&#x26;token=15e6a254-dd12-422a-a26f-ee158e3dc46b" alt=""><figcaption><p>Advanced Claim Configuration for OIDC SSO on Structural Cloud</p></figcaption></figure>

1. Expand the **Advanced Claim Configuration** section.
2. In the **Email Claim Name** field, provide the name of the claim that contains the user's email/username.
3. In the **First Name Claim Name** field, provide the name of the claim that contains the user's first name.
4. In the **Last Name Claim Name** field, provide the name of the claim that contains the user's last name.
5. In the **Groups Claim Name** field, provide the name of the claim that contains the user's group membership.