Tonic Textual respects the access control policy of your single sign-on (SSO) provider. To access Textual, users must be granted access to the Textual application within your SSO provider.

Self-hosted instances can use any of the available SSO options. Textual Cloud organizations can enable Okta SSO.

To enable SSO, you first complete the required configuration in the SSO provider. You then configure Textual to connect to it. For self-hosted instances, you use Textual environment variables for the configuration. For a Textual Cloud organization, you use the Single Sign-On tab on the Permission Settings page.

After you enable SSO, users can use SSO to create an account in Textual.

For self-hosted instances, to only allow SSO authentication, set the environment variable REQUIRE_SSO_AUTH to true. For Textual Cloud, this is configured in the application. When SSO is required, Textual 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.

You can .

Tonic Textual supports the following SSO providers:

In Tonic Textual, each user belongs to an organization. Organizations are used to determine the company or customer that a Textual user belongs to.

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

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

The displays the organization that the user account belongs to.

When is a Textual organization created?

A Textual organization is created:

New user on a self-hosted instance

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

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

Otherwise, to create your Textual user account, click Sign Up.

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

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

To display the SSO group list:

1. Click the user image at the top right.

2. In the user menu, click Permission Settings.

3. On the Permission Settings page, click Groups.

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

The list only displays the group names and indicates the SSO provider. To manage the group permissions:

• To assign global permission sets, go to the Global Permission Sets list. For more information, go to .

• To assign dataset permission sets, go to the Datasets page. For more information, go to .

Tonic Textual provides the following options to manage access to Textual and its features.

On Textual Cloud, after you complete the configuration in Okta, you configure the Textual connection to Okta from the Single Sign-On tab on the Permission Settings page.

1. To enable Okta SSO, check the Enable Okta SSO checkbox.

2. In the SSO Client ID field, enter the client identifier of the application.

3. In the SSO Domain field, enter the Okta domain.

4. If you use a third-party provider, then in the Identity Provider ID field, provide the provider identifier. If you do not use a third-party provider, then you can skip this field.

5. If you created a custom authorization server, then in the Authorization Server field, provide the server identifier. If you did not create a custom authorization server, then you can skip this field.

6. To require your organization users to use Okta SSO to log in to Textual, check the Require SSO for login checkbox.

Use these instructions to set up Okta as your SSO provider for Tonic Textual. Okta is supported on both self-hosted instances and on Textual Cloud.

Use these instructions to set up Azure Active Directory as your SSO provider for Tonic Textual.

Azure configuration

Register Textual as an application within the Azure Active Directory Portal:

1. In the portal, navigate to Azure Active Directory -> App registrations, then click New registration.

On a self-hosted instance, after you , uncomment and configure the relevant in Textual.

Kubernetes

For Kubernetes, the settings are in the Okta SSO Config section of values.yaml:

• oktaAuthServerId

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

Create an OAuth application

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

To display the list of Textual users:

1. Click the user icon at the top right.

2. In the user menu, click Permission Settings.

In a self-hosted instance of Tonic Textual, the default global permission set for Textual users does not include the ability to manage or assign global permissions.

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

Displaying the permission set lists

The Permission Settings page contains the lists of global and dataset permissions.

To display the Permission Settings page:

1. Click the user icon at the top right.

2. In the user menu, click Permission Settings.

On the Permission Settings page:

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

• Dataset Permission Sets contains the list of dataset 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.

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 can create custom global and dataset permission sets.

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

For example, you might want a dataset permission set that allows a user to manage the files but not share or delete the dataset.

For global permissions, you might want a global permission set that allows a user to manage access to any dataset, but not manage Textual users.

Creating a custom permission set

To create a custom permission set:

1. On the global or dataset 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 for that permission set type (global, dataset).

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

4. To save the new permission set, click

Editing a 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 global or datasets 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 global or dataset permission sets list, click Settings.

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

3. On the confirmation panel, click Confirm.

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

Learn about permission sets and permissions

View and configure permission sets

Assign global permission sets

Tonic Textual uses permissions and permission sets to manage role-based access (RBAC) to Textual 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

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

You can also create custom permission sets.

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

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

Redirect URI

In your SSO provider, configure the following redirect URI:

• Sign-in redirect URI: <textual-base-url>/sso/callback/oidc

Textual configuration

Required environment variables

After you set up the SSO provider, you uncomment and configure the required in Textual.

• The application client identifier

• For HTTP basic authentication (client_secret_basic), the client secret

• The base URL of the provider. This is the location of /.well-known/openid-configuration

For Kubernetes, in values. yaml:

For Docker, in .env:

Optional environment variables

You can optionally uncomment and configure the following optional environment variables:

• A space-delimited list of scopes to request from the OIDC SSO provider. Because group information is not part of the standard OIDC specification, for Textual 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 address or username.

Textual has default values for these settings:

For Kubernetes, in values.yaml:

For Docker, in .env:

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

Create an OAuth 2.0 client ID in Google

1. Go to https://console.developers.google.com/apis/credentials

2. Click Create credentials, located near the top.

3. Select OAuth client ID.

4. Select Web application as the application type.

5. Choose a name.

6. Under Authorized redirect URIs, add the URL of the Textual server with the endpoint /sso/callback/google. For example, a local Textual server at http://localhost:3000 would need http://localhost:3000/sso/callback/google to be set as the redirect URI. Also note that internal URLs might not work.

7. On the confirmation page, note the client ID and client secret. You will need to provide them to Textual.

Textual configuration

After you complete the configuration in Google, you uncomment and configure the required in Textual.

• The client ID

• The client secret

For Kubernetes, in values.yaml:

For Docker, in .env:

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 dataset permission sets is managed from the Datasets page. 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 Textual users. Initially, this is the General User permission set, but it can be changed to a different permission set.

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

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.

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

Keycloak configuration

Within Keycloak, select the realm to use for your Textual 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 Textual 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.

Textual configuration

After you complete the configuration in Keycloak, you uncomment and configure the required in Textual.

• The realm URL

• The client identifier

• The client secret, if client authentication is enabled

For Kubernetes, in values.yaml:

For Docker, in .env:

Disabling pushed authorization requests

The environment variable SOLAR_SSO_KEYCLOAK_DISABLE_PUSHED_AUTHORIZATION determines whether to disable Keycloak pushed authorization requests.

By default, this is false.

You would set this to true to troubleshoot Keycloak authentication issues.

You can configure:

• The global permission set that is assigned to all Tonic Textual users.

• The dataset permission set to assign to a user who creates a dataset.

Selecting the global permission set to assign to all Textual users

By default, all Textual users are assigned the built-in General User global permission set. You can configure a different global permission set to assign to all Textual 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 Textual users:

1. Click the user icon at the top right.

2. In the user menu, click Permission Settings.

3. On the Permission Settings page, click Global Permission Sets. The current permission set for all users is marked as Assigned to all users.

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

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

2. Check I have read and understand the risks.

3. Click Confirm.

Selecting the permission set to assign to a dataset creator

By default, when a user creates a dataset, they are assigned the built-in Editor dataset permission set. You can configure a different dataset permission set to assign when a database is created.

Changing the selected permission set does not affect existing datasets. It only applies to datasets that are created after the change.

To select a different permission set for dataset creation:

1. Click the user icon at the top right.

2. In the user menu, click Permission Settings.

3. On the Permission Settings page, click Dataset Permission Sets. The current permission set for database creators is marked Assigned on dataset creation.

4. To select a different permission set, hover over the permission set row, then click

Selecting default permission sets

Default permission set for users who create projects.

Selecting the permission set to assign to a guided redaction project creator

By default, when a user creates a guided redaction project, they are assigned the built-in Editor guided redaction permission set. You can configure a different guided redaction permission set to assign to the user who creates a project.

Changing the selected permission set does not affect existing projects. It only applies to projects that are created after the change.

To select a different permission set for guided redaction project creation:

1. Click the user icon at the top right.

2. In the user menu, click Permission Settings.

3. On the Permission Settings page, click Guided Redaction Permission Sets. The current permission set for project creators is marked Assigned on project creation.

4. To select a different permission set, hover over the permission set row, then click

Tonic Textual comes with a set of built-in global, dataset, and guided redaction permission sets. You cannot edit or delete the built-in permission sets.

Each permission is assigned Textual permissions. When a new permission is added to Textual, it is also added to the appropriate built-in permission sets.

Built-in global permission sets

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

• Admin - 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 TEXTUAL_ADMINISTRATORS.

• General User - Allows users to create datasets and custom entity types. Users can also use the Home page and the Request Explorer. By default, the General User permission set is assigned to all Textual users and SSO groups.

Available global permissions

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

Textual API and requests

Configuration management

Datasets

Guided redaction

Users and permissions

Built-in dataset permission sets

Textual comes with the following built-in permission sets:

• Editor - A dataset Editor has full access to view, edit, and share access to a dataset. When you create a dataset, you are automatically granted the Editor permission set for that dataset.

• Viewer - A dataset Viewer only has access to view the configuration and to preview and download the results.

Available dataset permissions

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

General dataset management

Dataset file management

Built-in guided redaction permission sets

Textual comes with the following built-in guided redaction permission sets:

• Editor - An Editor has almost full access to a guided redaction project. The one permission an Editor does not have is the permission to review redactions. When you create a project, you are assigned the Editor permission set.

• Viewer - A Viewer can view project settings, change statuses, and review redactions.

Available guided redaction permissions

The following tables list the available guided redaction permissions, and indicate how the permissions apply to the built-in guided redaction permission sets.

General project management

Project file management

Review and collaboration

To enable Okta as your SSO provider for Tonic Textual, you first 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:

   • App integration name: The name to use for the Textual application. For example, Textual, Textual-Prod, Textual-Dev.

   • Grant type: Implicit (hybrid)

   • Sign-in redirect URIs: For self-hosted instances, <base-url>/sso/callback/okta. For Textual Cloud, on the Permission Settings page, the sign-in redirect URL is displayed on the Single Sign-On tab. Copy the value from there and paste it into the field.

   • Base URIs: The URL to your Textual instance

   • Controlled access: Configure as needed to limit Textual access to the appropriate users

1. After saving the above, navigate to the General Settings page for the application and make the following changes:

   • Grant type: Check Implicit (Hybrid) and Allow ID Token with implicit grant type.

   • Login initiated by: Either Okta or App

1. Make a note of the following values that must be provided to Textual:

   • Client ID of the application:

   • Your Okta domain (for example, tonic.okta.com)