Microsoft Entra ID (previously Azure Active Directory)

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 then 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 are 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 Structural.