# 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
in the [Entra ID Portal](https://aad.portal.azure.com/), to register Structural as an application:
1. In the portal, navigate to **Microsoft Entra ID -> App registrations**, then click **New registration**.
2. Register Structural and create a new web redirect URI that points to your Structural instance's address and the path `/sso/callback.`
3. Take note of the values for client ID and tenant ID. You will need them later.
### Create a client secret
1. Click **New client secret**.
2. Create a new client secret.
Fields for a new client secret
3. Take note of the secret value. You will need this later.
### Add permissions
Navigate to the **API permissions** page, then add the following permissions for the Microsoft Graph API:
* OpenId permissions
* email
* openid
* profile
* GroupMember
* GroupMember.Read.All
* User
* User.Read
After you add the permissions, click **Grant admin consent for Tonic AI**. This allows the application to read the user and group information from your organization.
When permissions are granted, the status should change to **Granted for Tonic AI**.
### Grant user and group access to Structural
Navigate to **Enterprise applications** and then 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](https://aad.portal.azure.com/), 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://\.**
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](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow#get-a-token).
Set the `scope` parameter on the token request to `/.default`. For example, `api://22d90d9d-f5e4-4242-8989-9af9ac80608f/.default`.
### Assign application permissions for client applications
{% hint style="info" %}
You must complete these permission assignment steps for each client application that needs access to Structural.
{% endhint %}
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
```
`EntraID` replaces the typical `Bearer` prefix.
## Structural configuration
In the Structural web server container, set the following [Structural environment settings](https://docs.tonic.ai/app/admin/environment-variables-setting):
* `TONIC_SSO_PROVIDER`: `Azure`
* `TONIC_SSO_CLIENT_ID`: \
* `TONIC_SSO_CLIENT_SECRET`: \
* `TONIC_SSO_TENANT_ID`: \
* `TONIC_SSO_GROUP_FILTER_REGEX`: Identifies the allowed groups for Structural. For details, go to [sso-limit-groups](https://docs.tonic.ai/app/admin/tonic-user-access/single-sign-on/sso-limit-groups "mention").
{% hint style="info" %}
For Kubernetes, `TONIC_SSO_CLIENT_SECRET` can be provided through the `tonic-sso-client-secret` secret
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.tonic.ai/app/admin/tonic-user-access/single-sign-on/azure.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
