# Okta

Use these instructions to set up Okta as your SSO provider for Tonic Structural.

## Okta configuration

You complete the following configuration steps within Okta.

### Create an application

1. Create a new application. Choose the **OIDC - OpenId Connect** method with the **Single-Page Application** option.

![Create a new app integration](https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FRZaWu2JTK4i9EInTVbSG%2Fimage.png?alt=media\&token=53ec13a6-71d7-4ce7-bb95-2516fbe21264)

2. Click **Next**, then fill out the fields with the values below:
   1. **App integration name:** Typical names are Tonic, Tonic-Prod, Tonic-Dev
   2. **Logo (optional):** Download and use this image - <img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FJTGYT5aYQEjHXYROjI3B%2Ftonic-logo-square.png?alt=media&#x26;token=5f6f4de3-87b3-4ed8-b5e4-a1283bd0c5e4" alt="" data-size="line">
   3. **Grant type:** `Implicit (hybrid)`
   4. **Sign-in redirect URIs:** For self-hosted customers,  `<base-url>/sso/callback`.<br>

      For Structural Cloud, the value is `https://app.tonic.ai/sso/callback/<your organization identifier>`. You organization identifier is displayed on your [**User Settings** view](https://docs.tonic.ai/app/managing-your-tonic-account#user-view-copy-org-id).
   5. **Sign-out redirect URIs:** `<base-url>/sso/logout`
   6. **Base URIs:** The URL to your Structural instance
   7. **Controlled access:** Configure as needed to limit Structural access to the appropriate users

![App integration settings](https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FwFGKd9xvKibqPujcHWUj%2Fimage.png?alt=media\&token=287b16c0-c737-438d-a278-9f5e250f3570)

### Configure application settings

After you save the above, navigate to the **General Settings** page for the application and make the following changes:

1. **Grant type:** Check **Implicit (Hybrid)** and **Allow ID Token with implicit grant type**.
2. **Login initiated by:** Either **Okta** or **App**
3. **Application visibility:** Check **Display application icon to users**
4. **Initiate login URI:** To allow users to log in to Structural directly from Okta, provide an initiate login URI.\
   \
   For self-hosted, the value is your base URI.\
   \
   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).

![](https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2F6LTygzLPdmpX7fBFPupN%2Fimage.png?alt=media\&token=0fbcfbc1-055c-4e88-8439-d11984072e40)

![Application and login settings](https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FZyVtb5yfPTjc2fL5Hxgq%2Fimage.png?alt=media\&token=64ca1700-34b2-483e-91ef-615a96f1c7fa)

### Configure sign-on settings

Navigate to **Sign On settings**. In the **OpenID Connect ID Token** section, assign a groups claim filter.

![OpenID Connect ID Token settings](https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FW13xPu2kxDKyArYjMvez%2Fimage.png?alt=media\&token=d9bfb4f7-139b-4b8c-a64a-53854f5d17ac)

### Add a scope and claim to your authorization server

On your authorization server, Structural requires a scope and claim to allow Structural to have access to your groups.

You can add these to your default authorization server. If you are not comfortable adding the scope and claim to your default authorization server, you can create a new authorization server just for Structural. If you create a new authorization server, assign a new access policy to Structural.

To display the details for an authorization server:

1. Under **Security**, click **API**.
2. On the API page, click **Authorization Servers**.
3. Click the edit icon for the server to add the scope and claim to. To instead create a new authorization server, click **Add Authorization Server**.

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FyBn0dsgY9xLJM1YaP7tF%2FOkta_AuthorizationServers.png?alt=media&#x26;token=28b6cda2-bd4f-41f7-bf2c-dcd65ece40e9" alt=""><figcaption><p>Authorization Servers list</p></figcaption></figure>

#### Adding the scope

On the authorization server details, click the **Scopes** tab.

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FRAxAlzzmw4oTM3U2Fy3D%2FOkta_Scopes.png?alt=media&#x26;token=f0f6323f-06b4-45f3-8a21-01dc9c44d1a7" alt=""><figcaption><p>Scopes list for the authorization server</p></figcaption></figure>

Add a scope called **groups**.

![Add Scope panel](https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FmdaiqUH7uf38XKOZ6RMO%2Fimage.png?alt=media\&token=1f3aa105-b892-49bd-8304-a5e76dcedf81)

#### Adding the claim

Next, click the **Claims** tab. Add a claim called **groups** that has the following settings:

1. **Include in token type:** `ID Token` and `Always`
2. **Value type:** `Groups`
3. **Filter:** `Matches Regex .*` If this is not your default authorization server, you can use this to filter to only Structural groups. Otherwise, Structural has its own method to filter unwanted groups.
4. **Included in:** The following scopes: **groups**

![Add Claim panel](https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FtX9jWT1zDNGZZxqdQRBR%2Fimage.png?alt=media\&token=b7e002c5-a930-4a2a-a88c-da4bc5303c37)

### Values to provide to Structural

Make a note of the following values that must be provided to Structural:

1. Client ID of the application:

   ![](https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FpduE7Ygsdg4H5XURcS9Y%2FScreen%20Shot%202021-11-12%20at%2011.57.32%20AM.png?alt=media\&token=19149c35-5be0-4aa8-97e1-cc8239c6a3f5)
2. Your Okta domain (for example, `tonic.okta.com`)
3. Custom authorization server ID (if you made one):

   ![](https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FvFOzay1OrxbzBWxl2d7R%2FScreen%20Shot%202021-11-12%20at%2012.00.02%20PM.png?alt=media\&token=43690f76-b4ea-4101-8b5d-0ac3394fcd88)
4. IdP ID (If you use an outside identity provider):

   ![](https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2FJ1dF8AXV95KwjrmfIfe7%2FScreen%20Shot%202021-11-12%20at%2012.02.26%20PM.png?alt=media\&token=3a01f83f-eb2e-4a2e-89cf-45c0bc248ec4)

## Structural configuration - self-hosted instance

On a self-hosted instance, to configure the connection to Okta, you configure environment settings.

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

* `TONIC_SSO_PROVIDER`: `Okta`
* `TONIC_SSO_DOMAIN`: \<Your Okta domain>
* `TONIC_SSO_CLIENT_ID`: \<Okta application client ID>
* `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").
* `TONIC_SSO_AUTHORIZATION_SERVER_ID`: \<auth server id>\
  \
  Omit if not used.
* `TONIC_SSO_IDENTITY_PROVIDER_ID`: \<IdP Id>\
  \
  Omit if not used.

## Structural configuration - Structural Cloud

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

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 Okta:

<figure><img src="https://3378426797-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LSQCLFQ4bslJ-HYc8c3%2Fuploads%2Fs18eGoE2JJB2jFtNlHeX%2FCloudSSOEnabledOkta.png?alt=media&#x26;token=d7f5dbfe-2c8f-4a6f-ad36-8263a5f402ce" alt=""><figcaption><p>Configuration settings for Okta SSO on Structural Cloud</p></figcaption></figure>

1. Click **Okta**.
2. In the **SSO Client ID** field, provide the client identifier of the SSO application.
3. In the **SSO Domain** field, provide your Okta domain.
4. If you use an outside identity provider (IdP), then in the **Identity Provider ID** field, provide the IdP ID.\
   \
   If you do not use an outside IdP, then you can leave this blank.
5. If you use a custom authorization server, then in the **Authorization Server** field, provide the authorization server identifier.\
   \
   If you do not use a custom authorization server, then you can leave this blank.