By default, the Tonic Structural login page provides an option to create a new Structural account.

Any user who has access to the Structural URL can create an account.

On a self-hosted instance, to prevent any new accounts, set the environment setting TONIC_DISABLE_ACCOUNT_CREATION to true.

You can configure this setting from Structural Settings. So you can set it to false whenever a user needs to create an account, and then set it to true to once again prevent account creation.

New user on a self-hosted instance

If your company has a self-hosted Tonic Structural instance that is installed on-premises, then you navigate to the Structural URL for that instance.

Your self-hosted instance might be configured to use single sign-on for Structural access. If so, then from the Structural login page, to create your Structural user account, click the single sign-on option.

Otherwise, to create your Structural user account, click Create Account.

Your administrator can provide the URL for your Structural instance and confirm the instructions for creating your user account.

When you create the account, the Structural application opens to the New Workspace view so that you can create your first workspace.

New user for an existing Structural Cloud organization

If your Structural license is on Structural Cloud, then new users that have a matching email domain are automatically added to your Structural Cloud organization.

For a Structural Cloud license other than a pay-as-you-go license, the license agreement specifies the included email domains. When a user with a matching email domain signs up for a Structural account, they are added to that Structural Cloud organization.

For more information about Structural Cloud organizations, go to Structural organizations.

For a pay-as-you-go Structural Cloud license, when a user with the same corporate email domain as the subscribed user signs up for a Structural account, they are added to that Structural Cloud organization.

To sign up for a Structural Cloud account:

1. Go to https://app.tonic.ai.

2. Click Create Account.

3. In the Email field, provide your email address.

4. In the Password field, enter the password that you want to use for Structural.

5. In the Repeat Password field, enter the password again.

6. Click Create Account.

Structural Cloud opens to the New Workspace view so that you can create your first workspace.

In Tonic Structural, each user belongs to an organization. Organizations are used to determine the company or customer that a Structural user belongs to. The User Settings view displays the organization identifier for the user.

A self-hosted instance of Structural contains a single organization. All users belong to that organization.

Structural Cloud hosts multiple organizations. The organizations are kept completely separate. Users from one Structural Cloud organization do not have any access to the users or workspaces that belong to a different Structural Cloud organization.

When is a Structural organization created?

A Structural organization is created:

• For a standard Structural license, both self-hosted and Structural Cloud, when the first user signs up for a Structural account

• For a pay-as-you-go Structural Cloud license, when the user subscribes to Structural

• When a user signs up for a free trial on Structural Cloud. Each free trial user is in a separate Structural Cloud organization.

When is a new user added to an existing organization?

Self-hosted instance

A self-hosted instance has a single organization. Every user who signs up for an account on that instance is added to the organization.

Annual Structural Cloud license (not pay-as-you-go)

For companies with an annual Structural Cloud license, the license includes the email domains that are included in the license.

When a user with one of the included email domains signs up for a Structural account, they are automatically added to that organization.

Pay-as-you-go license

For a pay-as-you-go license, when a user with the same corporate email domain signs up for a Structural account, they are automatically added to that organization.

Free trial

During a free trial, a user can invite users with the same corporate email domain to have access to their free trial workspace.

When those users sign up for a Structural free trial in response to that invitation, they are automatically added to the Structural Cloud organization for the free trial user.

Tonic Structural instances have the following options to manage access to 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.

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.

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

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.

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.

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

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

• 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>

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

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 .

Tonic Structural uses permissions and permission sets to manage role-based access (RBAC) to Structural features and functions.

A permission grants access to a specific feature or function.

A permission set is a collection of permissions that can be assigned to a user or an SSO group.

Built-in and custom permission sets

Structural provides a set of built-in permission sets that you cannot edit or delete.

The Enterprise license plan also allows you to create custom permission sets.

Global permission sets

Global permission sets control access to features and functions that are outside of the context of a specific workspace. For example, global permission control who can manage users and configure environment settings.

For the lists of built-in global permission sets and available permissions, go to #permission-sets-builtin-global and #permissions-global.

For information on how to assign global permission sets, go to Configuring access to global permission sets and Setting initial access to all global permissions.

You can also select a default global permission set to assign to all new users.

Workspace permission sets

Workspace permission sets provide access to specific workspace management features and functions.

Workspace permission sets are assigned to users and groups within the context of a specific workspace. For example, a user might have the Editor permission set in one workspace and the Viewer permission set in another workspace.

For the lists of built-in workspace permission sets and available permissions, go to #permission-sets-builtin-workspace and #available-workspace-permissions.

For information on how to assign workspace permission sets, go to Sharing workspace access.

You can also select a default workspace permission set to assign to workspace owners.

Available global permissions

The following tables list the available global permissions, and indicates how the permissions apply to the built-in global permission sets.

User management permissions

Workspace management permissions

Tonic administration permissions

Configuration management permissions

Available workspace permissions

The following table lists the available workspace permissions, and indicates how the permissions apply to the built-in workspace permission sets.

Workspace management and configuration permissions

Workspace access permissions

Table and column configuration permissions

Data generation, tracking, and downloads permissions

Other data generation configuration permissions

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

Tonic Structural comes with a set of built-in global and workspace permission sets. You cannot edit or delete the built-in permission sets.

When a new permission is added to Structural, it is also added to the appropriate built-in permission sets.

Built-in global permission sets

Structural comes with the following built-in global permission sets:

• Admin - For self-hosted only. Provides complete access to all global permissions. The Admin permission set automatically receives any new global permissions.

• Admin (Environment) - For self-hosted only. Identical to the Admin permission set. Only assigned to users and groups listed in the value of the environment variable TONIC_ADMINISTRATORS.

• General User - Allows users to create workspaces. Also allows them to see other users in the organization, which is needed for workspace sharing and transfer, and to configure access to global permission sets. By default, the General User permission set is assigned to all Structural users and SSO groups.

• Account Admin - For Structural Cloud only. An Account Admin is associated with a Structural Cloud organization. An Account Admin can remove and reset user passwords for the users in the organization. They can also manage access to any workspace for the organization, and download the usage report.

For information on the assigned global permissions for the built-in global permission sets, go to #permissions-global.

Built-in workspace permission sets

Structural comes with the following built-in workspace permission sets:

• Manager - Provides complete access to all workspace permissions. The Manager permission set automatically receives all new workspace permissions. For instances with a Basic license, this is the only workspace permission set. By default, the Manager workspace permission set is assigned to workspace owners.

• Editor - Requires a Professional or Enterprise license. An editor can view and update nearly every aspect of a workspace. The Editor permission set automatically receives appropriate new workspace permissions. They cannot rename or delete the workspace, change the connection information, or copy the workspace.

• Auditor - Requires an Enterprise license. An auditor can view the workspace configuration, but cannot make any changes at all to it.

• Viewer - Requires an Enterprise license. Similar to an auditor, a viewer can view but not edit the workspace configuration. However, they are further restricted in that they cannot:

  • View any of the data

  • View the Protection Audit Trail

  • Download the Privacy Report

  • Download job logs

For information on the assigned workspace permissions for the built-in workspace permission sets, go to #available-workspace-permissions.

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

The Access Management tab on Structural Settings view includes a list of the current Tonic Structural users.

From the list, you can remove Structural users. You can also restore removed users. If you do not use SSO to manage users, then you can reset passwords for Structural users.

For information on how users are added to Structural, go to Logging into Structural for the first time.

You do not use the Users list to manage user permissions.

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

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

Viewing the Users list

To display the Users list:

1. In the Structural heading, click Structural Settings.

2. On Structural Settings view, click Access Management.

3. On the Access Management tab, click Users.

For each user, the list includes the following information:

• Name

• Email address

• When the user was most recently active in Structural

To use a column to sort the list, click the column heading. To reverse the sort order, click the column heading again.

Removing a Structural user

You can remove a Structural user from the Users list. When you remove a user, you must select a new owner for that user's workspaces.

To remove a Structural user:

1. In the Users list, click the actions menu, then click Remove User.

2. If the user is the owner of any workspaces, then the Transfer Workspace Ownership panel displays. Select a user to be the new owner of the removed user's workspaces, then click Next.

3. On the Remove User From Tonic panel, click Transfer & Remove.

Note that when you remove a user, it does not remove the user from the value of the TONIC_ADMINISTRATORS environment setting. You must update the environment setting manually. If a user or group is later added that has an email address or group name that is in the environment variable value, that user or group is granted the built-in Admin (Environment) permission set.

Restoring a removed user

You can restore a removed Structural user. When you restore a user, Structural restores to the user:

• The global permission sets that they were assigned

• The workspace access that they were granted

To view the list of removed, users, on the Access Management tab of Structural Settings, click Deleted Users.

To restore a removed user:

1. In the Deleted Users list, click the restore icon for the user.

2. On the confirmation panel, click Restore User.

Resetting a user password

From the Users list, if your instance does not use SSO to manage users, you can reset a user's password. You would most likely do this in response to a request from a user who forgot their password.

The reset password option sends an email to the user to allow them to set up a new password.

To reset a password, in the Users list, click the actions menu for the user, then click Reset Password.

From the Global Permission Sets list, you can grant or revoke access to a global permission set. Global permission sets can be assigned to individual users and to SSO groups.

Access to workspace permission sets is managed from Workspaces view. For more information, go to .

You cannot change the assignment of the following global permission sets:

• The global permission set that is assigned to all Structural users. Initially, this is the General User permission set, but .

• The built-in Admin (Environment) global permission set

Before you assign a global permission set to an SSO group, make sure that you are aware of who is in the group. The permissions that are granted to an SSO group automatically are granted to all of the users in the group. For information on how to configure Structural to filter the allowed SSO groups, go to .

To manage the permission set assignment:

1. On the Global Permission Sets list, for the permission set to manage, click Manage Access.

2. To grant access to a user or group:

   1. Begin to type the user or group name.

   2. In the list of matching users or groups, click the user or group name.

3. To remove access from a user or group, click Undo for that user or group.

4. To save the changes to the permission set access, click Save.

In a self-hosted instance of Tonic Structural, the default global permission set for Structural users is limited to creating workspaces.

Until you set the initial access to all global permissions, there is no way to manage or assign global permissions.

To set the initial access to all global permissions, you set the list of users or groups as the value of the environment setting TONIC_ADMINISTRATORS.

The users and groups are assigned the built-in Admin (Environment) permission set.

From the Global Permission Sets list:

• You cannot revoke the built-in Admin (Environment) permission set from those users or groups.

• You cannot assign the Admin (Environment) permission set to other users or groups.

To change the assigned users and groups, you update the value of TONIC_ADMINISTRATORS.

Docker deployments

Update your to include the email addresses or SSO groups the Structural users who should receive administrator access. The value can include both group names and user email addresses.

The should contain the TONIC_ADMINISTRATORS environment setting within the tonic_web_server configuration block. If not, pull the newest version.

Kubernetes deployments

In the file, under tonicai.web_server, edit the administrators property to include the email addresses of the Structural users who should receive administrator access.

To verify that you have the required version of the Helm charts, check that values.yaml contains the administrators line.

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>

Each new Tonic Structural user is assigned a specific global permission set. Each workspace owner is assigned a specific workspace permission set.

Selecting the global permission set to assign to all Structural users

By default, all Structural users are assigned the built-in General User global permission set.

You can also configure a different global permission set to assign to all Structural users.

The permission set cannot be removed.

When you choose a different permission set to assign to all users, unless they were otherwise assigned the previous permission set, they lose access to it.

To set the default global permission set to assign to all Structural users:

1. In the Structural heading, click Structural Settings.

2. On Structural Settings view, click Access Management, then click Global Permission Sets. On the Global Permission Sets list, the current permission set for all users is marked as Assigned to all users.

3. To select a different permission set, hover over the permission set row, then click Assign to all users.

4. The confirmation panel explains the risks of making this change. To confirm the change:

   1. Check I have read and understand the risks.

   2. Click Confirm.

Selecting the workspace permission set for all workspace owners

Every workspace has an owner. When a user creates a workspace, they become the first owner. When the workspace is transferred, the selected user becomes the new owner.

All owners are assigned the same workspace permission set. The permission set cannot be removed from the workspace owner. It can be assigned to and removed from other users and SSO groups.

By default, the workspace permission set for owners is the built-in Manager workspace permission set. You can also select a different workspace permission set to assign to all owners.

When you change the permission set to assign to users, all owners are assigned the selected permission set. Unless an owner was otherwise assigned the previously selected permission set, they lose access to that permission set.

To set the workspace permission set to assign to workspace owners:

1. In the Structural heading, click Structural Settings.

2. On Structural Settings view, click Access Management, then click Workspace Permission Sets. On the Workspace Permission Sets list, the current permission set for workspace owners is marked by Always assigned to owner.

3. To select a different permission set, hover over the permission set row, then click Assign to all owners.

4. The confirmation panel explains the risks of making this change. To confirm the change:

   1. Check I have read and understand the risks.

   2. Click Confirm.

The built-in Account Admin global permission set is specific to Tonic Structural Cloud. It allows a user to manage workspaces, remove users, and reset user passwords within their Structural Cloud organization. They can also download the usage report for their Structural Cloud organization.

For information about the global permissions that are granted to the Account Admin permission set, go to #permissions-global.

The first user in a Structural Cloud organization is automatically granted the Account Admin permission set. They can then grant the Account Admin permission set to other users in the organization.

Your organization should have at least one user with the Account Admin permission set.

The Access Management tab of Structural Settings view includes the lists of global and workspace permission sets.

Displaying the lists

1. In the Tonic Structural heading, click Structural Settings.

2. On Structural Settings view, click Access Management.

On the Access Management tab:

• Global Permission Sets contains the list of global permission sets.

• Workspace Permission Sets contains the list of workspace permission sets.

The lists include:

• The permission set name

• Whether the permission set is built-in or custom

• For custom permission sets, when it was most recently modified, and the user who modified it

On the Global Permission Sets list, the permission set that is assigned to all users is marked with Assigned to all users.

On the Workspace Permission Sets list, the permission set that is assigned to all workspace owners is marked with Always assigned to owner.

Viewing the details for a permission set

To view the details for a permission set, in the permission sets list, click Settings.

The details panel for a permission set includes:

• The name of the permission set.

• The permission configuration.

You use permissions and permission sets to manage access to Tonic Structural features and functions.

About permission sets and permissions

Configure permission sets

Assign permission sets

You can create custom global and workspace permission sets.

A custom permission set allows you to have more precise control over global and workspace permissions.

For example, you might want a workspace permission set that allows a user to configure the workspace but not run data generation. Or you might want to limit the types of workspace configuration that a user can change.

For global permissions, you might want a global permission set that allows a user to configure Tonic Structural data encryption and generator presets, but not manage Structural users.

Creating a custom permission set

To create a custom permission set:

1. On the workspace or global permission sets list, click the create permission set button.

2. On the permission set details panel, in the Permission Set Name field, type the name for the new permission set. Permission set names must be unique.

3. To base the permission set on an existing permission set, from Create from existing permission set, select the existing permission set to use. When you base the permission set on an existing permission set, Structural copies the permissions from the existing permission set to the new permission set. You can then update the selected permissions as needed. For example, you might want to create a workspace permission set that is nearly identical to the built-in Editor permission set, but that removes the option to generate data. You can base the new permission set on the Editor permission set, then remove the data generation permission. After you save the new permission set, it is not connected to the permission set that you used to obtain the initial set of permissions.

4. Select the permissions to grant to the permission set. If a permission checkbox is checked, then the permission is granted to the permission set. If a permission checkbox is not checked, then the permission is not granted to the permission set.

5. To save the new permission set, click Save.

6. For a global permission set, Structural prompts you to configure access to the new permission set. To display the access management panel for the permission set, click Manage User Access. To not manage access at that time, click Skip.

Editing an existing custom permission set

You cannot make any changes to a built-in permission set.

For a custom permission set, you can change the permission set name and adjust the assigned permissions.

To edit an existing custom permission set:

1. On the workspace or global permission sets list, click Settings.

2. On the permission set details panel, update the permission set configuration.

3. Click Save.

Deleting a custom permission set

You can delete a custom permission set. You cannot delete a built-in permission set.

You cannot delete a permission set that is assigned to any users or groups. Before you can delete the permission set, you must remove the assignment.

To delete a custom permission set:

1. On the workspace or global permission sets list, click Settings.

2. On the permission set details panel, click Delete Permission Set.

3. On the confirmation panel, click Confirm.