Tonic Structural supports integrations with several external single sign-on (SSO) providers to allow users to use SSO to create accounts and log in to Structural.

To only allow SSO authentication, set the environment setting REQUIRE_SSO_AUTH to true. This disables standard email/password authentication. All account creation and login is handled through your SSO provider. If multi-factor authentication (MFA) is set up with your SSO, then all authentication must go through your provider's MFA.

How SSO works in Structural

Required configuration for each SSO provider

To use SSO in Structural, you must have a valid license for the SSO functionality. You must also configure Structural environment variables. The required variables differ by provider.

Identifying the allowed groups

To identify the SSO groups that are allowed in Tonic Structural, in the Structural web server container, set the value of the TONIC_SSO_GROUP_FILTER_REGEX environment setting to a regular expression that identifies the allowed groups.

If you do not configure this setting, then Structural does not synchronize or load any groups from your SSO provider.

For example, to allow all groups that contain the word "Structural", set TONIC_SSO_GROUP_FILTER_REGEX to .*Structural.*.

To allow all SSO groups, set TONIC_SSO_GROUP_FILTER_REGEX to .*.

Cleaning up non-matching groups

When the value of TONIC_SSO_GROUP_FILTER_REGEX changes, Structural does not automatically remove groups that were previously imported into Structural. Groups that no longer match the filter might continue to display in Structural.

For example, you might initially configure TONIC_SSO_GROUP_FILTER_REGEX with a permissive value and then edit it to use a more restrictive filter.

To remove the groups that no longer match the filter:

1. Display the list of SSO groups. If there are non-matching groups, then the Clean Up Groups button is enabled.

2. To remove the non-matching groups:

   1. Click Clean Up Groups.

   2. On the Clean Up Groups dialog, review the list of groups to remove.

   3. To confirm the removal, click Remove Groups.

When a group is removed, it is also removed from any workspaces that it was granted access to.

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

Duo configuration

To indicate to use Duo as an SSO provider for Structural:

1. On the Applications page, click Protect an Application.

2. On the Protect an Application page, for the Web SDK application, click Protect.

Structural configuration

To configure Duo SSO, use the following environment settings.

Most of these values are available from the application details page for Web SDK. To view the application details, on the Applications page, click Web SDK.

• TONIC_SSO_PROVIDER - Duo

• TONIC_SSO_CLIENT_ID - The client ID for Web SDK. Available on the application details page for Web SDK as the value of Client ID.

• TONIC_SSO_CLIENT_SECRET - The client secret for Web SDK. Available on the application details page for Web SDK as the value of Client secret.

• TONIC_SSO_DOMAIN - The Duo domain. This is essentially the URL to your Duo instance: admin-<identifier>.duosecurity.com. Available on the application details page for Web SDK as the value of API hostname.

• TONIC_SSO_GROUP_FILTER_REGEX - Identifies the allowed groups for Structural. For details, go to Synchronizing SSO groups with Tonic Structural.

Tonic Structural respects the access control policy of your SSO provider. To access Structural, users must be granted access to the Structural application within your SSO provider.

After SSO is enabled, users can use SSO to create an account in Structural.

On future logins, users are prompted to use SSO to authenticate.

If you use SSO to manage Tonic Structural groups, then Structural displays the list of groups for which at least one user has logged in to Structural.

To display the SSO group list:

1. In the Structural heading, click Structural Settings.

2. On Structural Settings view, click Access Management.

3. On the Access Management tab, click Groups.

If no users from a group have logged in to Structural, then the group does not display in the list.

The list only displays the group names. To manage the group permissions:

• To assign global permission sets, go to the Global Permission Sets tab.

• To assign workspace permission sets, go to Workspaces view.

Use these instructions to set up Microsoft Entra ID as your SSO provider for Tonic Structural.

Entra ID configuration

Register Structural as an application within the Entra ID Portal:

1. In the portal, navigate to Microsoft Entra ID -> App registrations, then click New registration.

1. Register Structural and create a new web redirect URI that points to your Structural instance's address and the path /sso/callback.

2. Take note of the values for client ID and tenant ID. You will need them later.

1. Click New client secret and create a new client secret

1. Take note of the secret value. You will need this later.

1. Navigate to the API permissions page. Add the following permissions for the Microsoft Graph API:

   • OpenId permissions

     • email

     • openid

     • profile

   • GroupMember

     • GroupMember.Read.All

   • User

     • User.Read

1. Click Grant admin consent for Tonic AI. This allows the application to read the user and group information from your organization.

1. When permissions have been granted, the status should change to Granted for Tonic AI.

2. Navigate to Enterprise applications and select Tonic Structural. From here, you can assign the users or groups that should have access to Structural.

(Optional) Using service principals for Structural authentication

You can optionally configure Entra ID to use service principals for Structural authentication:

Update the Structural app registration

1. From the EntraID portal, to navigate to the Tonic Structural app registration page, click

   Microsoft EntraID → App Registrations → [Your Tonic Structural App].

2. If your application registration doesn't already have an application ID URI, then under Essentials:

   1. Click Add an Application ID URI.

   2. At the top of the Expose an API page, click Add.

   You can use the default suggestion of api://<application-client-id>.

3. To navigate to the App roles configuration page, click Manage → App roles

4. Click Create app role, then configure the role:

   • Display Name: Can be any value, but we recommend Service Principal

   • Allowed Member types: Application

   • Value: Structural.ServicePrincipal

   • Description: Can be any value, but it should describe the service principal role.

5. To navigate to the Manifest configuration page, click Manage → Manifest

6. Set the value for accessTokenAcceptedVersion to 2, then click Save.

   This ensures that the EntraID access tokens that are created using the Structural application scope are version 2.0.

7. To navigate to the API permissions configuration page, click Manage → API permissions

8. Click Add a permission.

   For the Microsoft Graph API, add the following application permissions:

   • Application.Read.All - Required to fetch information about Service Principals

   • GroupMember.Read.All Required to sync the Service Principal group membership Note that your Tonic Structural registration should already contain a delegated permission for GroupMember.Read.All. This application permission is an additional, separate permission.

   Before they can take effect, application permissions require Admin consent.

Structural is now set up to authenticate application service principals using access tokens that are acquired from the EntraID OAuth 2.0 client credentials flow.

To use the client credentials flow to retrieve an access token, follow these instructions.

Set the scope parameter on the token request to <your-application-id-uri>/.default. For example, api://22d90d9d-f5e4-4242-8989-9af9ac80608f/.default.

Assign application permissions for client applications

For the Structural API to successfully authorize an application service principal, you must grant the Structural.ServicePrincipal role to the application service principal.

1. For an application that requires access to Structural, to navigate to the App Registration page, click Microsoft EntraID → App Registration → [Your Application].

2. To navigate to the API permissions configuration page, click Manage → API permissions.

3. Click Add a permission.

   1. On the APIs my organization uses tab, search for your Structural app registration.

   2. Add the Structural.ServicePrincipal application permission.

Before they can take effect, application permissions require Admin consent.

The required role should be present in the access tokens that are acquired using the client credentials flow.

To use your application service principal to make Structural API calls, in the HTTP Authorization header, use the following format:

EntraID <token>

EntraID replaces the typical Bearer prefix.

Structural configuration

In the Structural web server container, set the following Structural environment settings:

• TONIC_SSO_PROVIDER: Azure

• TONIC_SSO_CLIENT_ID: <Microsoft Entra ID Client ID>

• TONIC_SSO_CLIENT_SECRET: <Microsoft Entra ID Client Secret>

• TONIC_SSO_TENANT_ID: <Microsoft Entra ID Tenant ID>

• TONIC_SSO_GROUP_FILTER_REGEX: Identifies the allowed groups for Structural. For details, go to Synchronizing SSO groups with Tonic Structural.

Use these instructions to set up AWS IAM Identity Center as your SSO provider for Tonic Structural.

This integration uses a combination of SAML 2.0 and the AWS Identity Store API to resolve group names. If you do not require groups, you can also use the .

AWS configuration

You complete the following configuration steps within IAM Identity Center.

Create the SAML application

On the Applications page, click Add application.

On the Add application page, under Select application type:

1. Click I have an application I want to set up.

2. Click SAML 2.0.

3. Click Next.

On the Configuration application page, in the Display name field, enter a name for the application.

Under IAM Identity Center metadata, copy the IAM Identity Center SAML metadata file URL.

You set this as the value of a Structural environment setting.

Alternatively, you can download the file to provide in your Structural configuration. However, the URL is preferred.

Under Application properties, set Application start URL to your Structural URL.

Under Application metadata:

1. Click Manually type your metadata values.

2. Set Application ACS URL to your Structural URL followed by /api/sso/samllogin.

3. Set Application SAML audience to Tonic.

To create the application, click Submit.

Configure attribute mappings for Structural

Next, you configure the attribute mappings that Structural requires.

For your new Structural application, click Actions, then select Edit attribute mappings.

On the Attribute mappings tab, set up the following mappings:

• Map Subject to ${user:subject}

• Map GivenName to ${user:givenName}

• Map Email to ${user:email}

• Map FamilyName to ${user:familyName}

• Map Groups to ${user:groups}

Structural configuration

• TONIC_SSO_PROVIDER - Set to AWS

• TONIC_SSO_IDENTITY_PROVIDER_ID - Set to the value of Identity store ID from the Settings page in IAM Identity Center.

• TONIC_SSO_SAML_IDP_METADATA_XML_URL- Set to the IAM Identity Center SAML metadata file URL that you saved earlier. You can alternatively provide the file directly. To do this:

  1. base64 encode the contents of the downloaded metadata XML file.

  2. Set TONIC_SSO_SAML_IDP_METADATA_XML_BASE64 to the base64 encoded string.

• TONIC_SSO_SAML_ENTITY_ID - The entity ID to use to send SAML requests from Structural. If this is not set, the entity ID is determined from the identify provider metadata. You also use this as the value of Audience in the SAML provider configuration.

IAM role configuration

Structural uses the Identity Store API to enrich the group attribute that SAML provides with the group name.

Structural must have permission to use the identity store API to retrieve the group information.

On a self-hosted instance, Structural gets the AWS credentials from the environment. Structural uses either:

• • TONIC_AWS_ACCESS_KEY_ID - An AWS access key that is associated with an IAM user or role.

  • TONIC_AWS_SECRET_ACCESS_KEY - The secret key that is associated with the access key.

  • TONIC_AWS_REGION - The AWS Region to send the authentication request to.

• The credentials for the IAM role on the host machine.

The policy that is associated with your IAM role or IAM user must allow the identitystore:DescribeGroup action. Your policy should be similar to:

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

GitHub configuration

Create an OAuth application

In GitHub, navigate to Settings -> Developer Settings -> OAuth Apps, then create a new application.

1. For Application Name, enter Tonic.

2. For Homepage URL, enter https://tonic.ai.

3. For Authorization callback URL, enter https://your-tonic-url/sso/callback. Replace your-tonic-url with the URL of your Structural instance.

Create a client secret

After you create the application, to create a new secret, click Generate a new client secret.

You use the Client ID and the Client secret in the Structural configuration.

Structural configuration

• TONIC_SSO_PROVIDER: GitHub

• TONIC_SSO_CLIENT_ID: <GitHub Client ID>

• TONIC_SSO_CLIENT_SECRET: <GitHub Client Secret>

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

Keycloak configuration

Within Keycloak, select the realm to use for your Structural client. Under Clients, click Create client.

On the Create client page, under General Settings:

1. From the Client type dropdown list, select OpenID Connect.

2. Enter a Client ID and Name.

3. Click Next.

On the Capability Config tab, click Save. The details page for the new client displays.

On the Settings tab, under Access settings, enter your Tonic URL information.

Click Client scopes. Each client has a dedicated scope named <client-id>-dedicated. To configure the scope, click the scope name.

On the Mappers tab, to add a property mapper to the scope, click Configure a new mapper.

In the list of mapper types, click Group Membership.

Under Add mapper, set both Name and Token Claim Name to groups.

The Full group path toggle affects how child groups appear in Tonic:

• When on, child groups display as parent group/child group.

• When off, child groups display as child group.

To save the new group membership mapper, click Save.

Tonic configuration

• TONIC_SSO_PROVIDER: Keycloak

• TONIC_SSO_DOMAIN: https://my-keycloak-instance

• TONIC_SSO_CLIENT_ID: <Keycloak client ID>

• TONIC_SSO_REALM_ID: <Keycloak realm ID>

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

To configure Google SSO:

1. - Requires GCP project permissions to create credentials.

2. - In addition to the above, requires the Google workspace administrator.

The OAuth client ID is sufficient to enable logging in with your Google account, but no groups are parsed. If the service account is misconfigured, the login succeeds without the groups being parsed and a warning is logged to the server with more details. For the provided links, it is assumed that the user is logged into their administrative account and using the same project.

Creating an OAuth 2.0 client id

1. Go to

2. Click Create credentials, located near the top.

1. Select OAuth client ID.

1. Select Web application as the application type.

2. Choose a name.

3. Under Authorized redirect URIs, add the URL of the Structural server with the endpoint /sso/callback.

   • Also note that internal URLs might not work:

1. Note the client ID and client secret. You will need to provide them to Structural.

Providing the client information to Structural

• TONIC_SSO_CLIENT_ID: <client id of oauth credentials>

• TONIC_SSO_CLIENT_SECRET: <client secret of oauth credentials>

• TONIC_SSO_PROVIDER: google

Create and configure a service account to read user groups

To set up the service account:

Create a service account with a json key

2. Click Create service account, located near the top

1. Skip all the subsequent optional steps.

2. After you create the service account, select it and go into the Keys tab.

1. Select Add Key -> Create new key and select JSON as the key type. The browser automatically downloads a json file.

2. The json file must be base64 encoded to set it as a variable in your Docker Compose file. An example command to do this is: cat /path/to/json/file | base64 -w 0 The long output of this command is set as the value of TONIC_SSO_SERVICE_ACCOUNT_JSON_BASE64 in the Docker Compose file

3. Take note of the service account email. You will need this later.

Enable the Admin SDK API

2. Click Enable if it is not yet enabled.

Add the Groups Reader admin role to the service account

2. Select Groups Reader from the list of predefined roles.

3. Click Assign Roles -> Assign service accounts.

4. Copy the service account email into the box, then click Add.

5. To save these changes, click Assign Role.

Providing the service account and group information to Structural

• TONIC_SSO_SERVICE_ACCOUNT_JSON_BASE64: <base64 encoded json key>

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

SSO setup

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

In your SSO provider, configure the following redirect URIs:

• Sign-in redirect URIs: <tonic-base-url>/sso/callback

• Sign-out redirect URIs: <tonic-base-url>/sso/logout

Structural configuration

Required environment settings

In the Structural web server container, set the following Structural environment settings:

• 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 Synchronizing SSO groups with Tonic Structural.

Optional environment settings

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

Okta configuration

You complete the following configuration steps within Okta:

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

1. Click Next, then fill out the fields with the values below:

   1. App integration name: Tonic, Tonic-Prod, Tonic-Dev, etc.

   3. Grant type: Implicit (hybrid)

   4. Sign-in redirect URIs: <base-url>/sso/callback

   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

1. After saving 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: <base-url>

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

1. Next, add a new scope/claim to allow Structural to access groups. You might already have added this to your default authorization server. If not, and you are not comfortable adding this scope/claim to your default authorization server, you can create a new authorization server just for Structural.

2. On your authorization server, navigate to the Scopes. Add a scope called groups.

1. Next, navigate to Claims and 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 .* This can be used to filter to only Structural groups if this is not your default authorization server. Otherwise, Structural has its own method to filter unwanted groups.

   4. Included in: The following scopes: groups

1. If this is a new authorization server just for Structural, make sure to assign a new access policy to Structural.

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

   1. Client ID of the application:
   2. Your Okta domain (for example, tonic.okta.com)

   3. Custom authorization server ID (if you made one):
   4. IdP ID (If you use an outside identity provider):

Structural configuration

In the Structural web server container, set the following environment settings:

• 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 Synchronizing SSO groups with Tonic Structural.

• TONIC_SSO_AUTHORIZATION_SERVER_ID: <auth server id> Omit if not used.

• TONIC_SSO_IDENTITY_PROVIDER_ID: <IdP Id> Omit if not used.

For information on how to configure Structural environment settings, go to Configuring environment settings.

Use these instructions to set up a SAML SSO provider for Tonic Structural.

SAML provider configuration

You must configure the following assertions to be sent to Structural from your SAML provider:

• Email

• GivenName

• FamilyName

• Groups

The Assertion Consumer Service (ACS) URL is https://your-tonic-url/api/sso/samllogin.

Set Audience to the value of the Structural environment setting TONIC_SSO_SAML_ENTITY_ID.

Structural configuration

In the Structural web server container, set the following :

• TONIC_SSO_PROVIDER: SAML

• TONIC_SSO_SAML_IDP_METADATA_XML_URL- Set to the URL of your IDP Metadata XML file. If your SSO solution does not offer a URL, you can set TONIC_SSO_SAML_IDP_METADATA_XML_BASE64 to the Base 64 encoded contents of the IDP Metadata XML file. To encode the contents, run the following command: cat /path/to/xml/file | base64 -w 0

• TONIC_SSO_SAML_ENTITY_ID: The entity ID to use to send SAML requests from Structural. If this is not set, the entity ID is determined from the IDP metadata. You also use this as the value of Audience in the SAML provider configuration.

• TONIC_SSO_GROUP_FILTER_REGEX: Identifies the allowed SSO groups for Structural. For details, go to .