Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Required license: Professional or Enterprise
Required global permission: Manage user access to Tonic and to any workspace
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:
In the Structural heading, click Tonic Settings.
On Tonic Settings view, click Access Management.
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.
Required license: Professional or Enterprise
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.
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 AWS as your SSO provider for Tonic Structural.
You complete the following configuration steps within AWS SSO.
In the Applications section, click Add a new application.
Next, on the Add New Application page, click Add a custom SAML 2.0 application.
From IAM Identity Center metadata, download your AWS SSO SAML metadata file URL. You will set this as the value of a Structural environment setting.
Under Application properties, set Application start URL to your Structural URL.
Under Application metadata:
Click Manually type your metadata values.
Set Application ACS URL to your Tonic URL followed by /api/sso/samllogin
.
Set Application SAML audience to Tonic
.
To create the application, click Submit.
Next, you need to 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}
TONIC_SSO_PROVIDER
- Set to AWS
TONIC_SSO_IDENTITY_PROVIDER_ID
- Set to the value of Identity store ID from the Settings page in AWS SSO.
TONIC_SSO_SAML_IDP_METADATA_XML_URL
- Set to the IAM Identity Center SAML metadata file URL that you saved earlier.
In the Structural web server container, set the following :
TONIC_SSO_GROUP_FILTER_REGEX
- Identifies the allowed groups for Structural. For details, go to .
User authentication
How SSO users create Structural accounts and log in to Structural.
Limit groups for Structural
Identify SSO groups that are displayed in Structural.
View the list of groups
View the list of SSO groups for which users have logged in to Structural.
AWS SSO
Integrate with AWS SSO to manage Structural users.
Azure Active Directory
Integrate with Azure Active Directory to manage Structural users.
Duo
Integrate with Duo to manage Structural users.
GitHub
Integrate with GitHub to manage Structural users.
Google Account SSO
Integration with Google Account SSO to manage Structural users.
Keycloak
Integrate with Keycloak to manage Structural users.
Okta
Integrate with Okta to manage Structural users.
OpenID Connect (OIDC)
Integrate with OpenID Connect to manage Structural users.
SAML
Integrate with a SAML-based provider to manage Structural users.
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 .*
.
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:
Display the list of SSO groups. If there are non-matching groups, then the Clean Up Groups button is enabled.
To remove the non-matching groups:
Click Clean Up Groups.
On the Clean Up Groups dialog, review the list of groups to remove.
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.
To indicate to use Duo as an SSO provider for Structural:
On the Applications page, click Protect an Application.
On the Protect an Application page, for the Web SDK application, click Protect.
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 GitHub as your SSO provider for Tonic Structural.
The Structural GitHub SSO integration does not support GitHub group membership.
In GitHub, navigate to Settings -> Developer Settings -> OAuth Apps, then create a new application.
For Application Name, enter Tonic
.
For Homepage URL, enter https://tonic.ai
.
For Authorization callback URL, enter https://your-tonic-url/sso/callback
.
Replace your-tonic-url
with the URL of your Structural instance.
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.
In the Structural web server container, set the following Structural environment settings :
TONIC_SSO_PROVIDER
: GitHub
TONIC_SSO_CLIENT_ID
: <GitHub Client ID>
TONIC_SSO_CLIENT_SECRET
: <GitHub Client Secret>
Azure Active Directory is renamed to Microsoft Entra ID.
The name change does not affect the portal URL.
Use these instructions to set up Azure Active Directory as your SSO provider for Tonic Structural.
Register Structural as an application within the Azure Active Directory Portal:
In the portal, navigate to Azure Active Directory -> App registrations, then click New registration.
Register Structural and create a new web redirect URI that points to your Structural instance's address and the path /sso/callback.
Take note of the values for client ID and tenant ID. You will need them later.
Click Add a certificate or secret and create a new client secret
Take note of the secret value. You will need this later.
Navigate to the API permissions page. Add the following permissions for the Microsoft Graph API:
OpenId permissions
openid
profile
GroupMember
GroupMember.Read.All
User
User.Read
Click Grant admin consent for Tonic AI. This allows the application to read the user and group information from your organization.
When permissions have been granted, the status should change to Granted for Tonic AI.
Navigate to Enterprise applications and select Tonic. From here, you can assign the users or groups that should have access to Structural.
In the Structural web server container, set the following Structural environment settings:
TONIC_SSO_PROVIDER
: Azure
TONIC_SSO_CLIENT_ID
: <Azure Client ID>
TONIC_SSO_CLIENT_SECRET
: <Azure Client Secret>
TONIC_SSO_TENANT_ID
: <Azure Tenant ID>
TONIC_SSO_GROUP_FILTER_REGEX
: Identifies the allowed groups for Structural. For details, go to Synchronizing SSO groups with Tonic Structural.
For Kubernetes, TONIC_SSO_CLIENT_SECRET
can be provided through the tonic-sso-client-secret
secret
Use these instructions to set up Okta as your SSO provider for Tonic Structural.
You complete the following configuration steps within Okta:
Create a new application. Choose the OIDC - OpenId Connect method with the Single-Page Application option.
Click Next, then fill out the fields with the values below:
App integration name: Tonic, Tonic-Prod, Tonic-Dev, etc.
Grant type: Implicit (hybrid)
Sign-in redirect URIs: <base-url>/sso/callback
Sign-out redirect URIs: <base-url>/sso/logout
Base URIs: The URL to your Structural instance
Controlled access: Configure as needed to limit Structural access to the appropriate users
After saving the above, navigate to the General Settings page for the application and make the following changes:
Grant type: Uncheck Allow Access Token with implicit grant type.
Login initiated by: Either Okta or App
Application visibility: Check Display application icon to users
Initiate login URI: <base-url>
Navigate to Sign On settings. In the OpenID Connect ID Token section, assign a groups claim filter.
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.
On your authorization server, navigate to the Scopes. Add a scope called groups.
Next, navigate to Claims and add a claim called groups that has the following settings:
Include in token type: ID Token and Always
Value type: Groups
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.
Included in: The following scopes: groups
If this is a new authorization server just for Structural, make sure to assign a new access policy to Structural.
Make a note of the following values that must be provided to Structural:
Client ID of the application:
Your Okta domain (for example, tonic.okta.com
)
Custom authorization server ID (if you made one):
IdP ID (If you use an outside identity provider):
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_AUTHORIZATION_SERVER_ID
: <auth server id>
Omit if not used.
TONIC_SSO_IDENTITY_PROVIDER_ID
: <IdP Id>
Omit if not used.
Logo (optional): Download and use the this image.
TONIC_SSO_GROUP_FILTER_REGEX:
Identifies the allowed SSO groups for Structural. For details, go to .
For information on how to configure Structural environment settings, go to .
Use these instructions to set up Google as your SSO provider for Tonic Structural.
To configure Google SSO:
Create an OAuth 2.0 Client ID - Requires GCP project permissions to create credentials.
Create and configure a service account to read user groups - 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.
Click Create credentials, located near the top.
Select OAuth client ID.
Select Web application as the application type.
Choose a name.
Under Authorized redirect URIs, add the URL of the Structural server with the endpoint /sso/callback.
For example, a local Structural server at http://localhost:3000 would need http://localhost:3000/sso/callback to be set as the redirect URI
Also note that internal URLs might not work:
Note the client ID and client secret. You will need to provide them to Structural.
Configure the following environment settings in the Structural web server container:
TONIC_SSO_CLIENT_ID
: <client id of oauth credentials>
TONIC_SSO_CLIENT_SECRET
: <client secret of oauth credentials>
TONIC_SSO_PROVIDER
: google
To set up the service account:
For official documentation, see https://cloud.google.com/iam/docs/creating-managing-service-accounts and https://cloud.google.com/iam/docs/creating-managing-service-account-keys.
Click Create service account, located near the top
Skip all the subsequent optional steps.
After you create the service account, select it and go into the Keys tab.
Select Add Key -> Create new key and select JSON as the key type. The browser automatically downloads a json file.
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
Take note of the service account email. You will need this later.
Click Enable if it is not yet enabled.
Go to https://admin.google.com and select Admin Roles.
Select Groups Reader from the list of predefined roles.
Click Assign Roles -> Assign service accounts.
Copy the service account email into the box, then click Add.
To save these changes, click Assign Role.
In the Structural web server container, set the following Structural environment settings:
TONIC_SSO_SERVICE_ACCOUNT_JSON_BASE64
: <base64 encoded json key>
TONIC_SSO_DOMAIN
: <domain name> - The domain name is the workspace domain. For example, for support@tonic.ai, the domain is tonic.ai
.
TONIC_SSO_GROUP_FILTER_REGEX
: Identifies the allowed SSO groups for Structural. For details, go to Synchronizing SSO groups with Tonic Structural.
For Kubernetes, TONIC_SSO_SERVICE_ACCOUNT_JSON_BASE64
can be provided through the tonic-sso-google-account-service-json-secret
secret
Use these instructions to set up a SAML SSO provider for Tonic Structural.
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
.
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.
Use these instructions to set up an OpenID Connect SSO provider for Tonic Structural.
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.
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
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
In the Structural web server container, set the following :
TONIC_SSO_GROUP_FILTER_REGEX
: Identifies the allowed SSO groups for Structural. For details, go to .
In the Structural web server container, set the following :
TONIC_SSO_GROUP_FILTER_REGEX
: Identifies the allowed SSO groups for Structural. For details, go to .
Setting | Default value | Description |
---|
|
| The space-delimited list of scopes to request from the OIDC SSO provider. Because group information is not part of the standard OIDC specification, for Structural to capture group information, a custom scope must be configured. |
|
| The name of the claim that contains the user's first name. |
|
| The name of the claim that contains the user's last name. |
|
| The name of the claim that contains the user's email/username. |
|
| The name of the claim that contains the user's group membership. |
Use these instructions to set up Keycloak as your SSO provider for Tonic Structural.
Within Keycloak, select the realm to use for your Structural client. Under Clients, click Create client.
On the Create client page, under General Settings:
From the Client type dropdown list, select OpenID Connect.
Enter a Client ID and Name.
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.
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.
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.