# 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.


---

# Agent Instructions: 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:

```
GET https://docs.tonic.ai/app/admin/tonic-user-access/single-sign-on/oidc.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.