# Microsoft Entra ID configuration To use Microsoft Entra ID as your Fabricate single sign-on (SSO) provider, you first complete the following configuration in Microsoft Entra ID. ## Create the app registration In the Azure portal: 1. Go to **Microsoft Entra ID**. 2. Open **App registrations**. 3. Click **New registration**. Configure the app registration as follows: * **Name**: `Fabricate SSO` * **Supported account types**: `Accounts in this organizational directory only (Single tenant)` * **Redirect URI**: * Platform: **Web** * Value: `https://fabricate.tonic.ai/sso/callback` ## Create a client secret 1. Open the app registration that you created. 2. Go to **Certificates & secrets**. 3. Click **New client secret**. 4. Provide a description for the secret. 5. Set the expiration period for the secret. 6. Click **Add**. 7. Copy the secret value. In the Fabricate SSO configuration, you use the secret value as the value of **Client Secret**. ## Confirm the redirect URI Go to **Authentication**. Confirm that the app has a **Web** redirect URI for: ``` https://fabricate.tonic.ai/sso/callback ``` For Fabricate's server-side OIDC flow, you do not need to enable implicit grant settings. ## Copying Microsoft Entra ID values to use in Fabricate In Fabricate, when you configure Microsoft Entra ID as your SSO provider, you provide the following values that you copy from Microsoft Entra ID. ### Issuer URL In the Fabricate SSO configuration, the value of **Issuer URL** is the tenant-specific Microsoft Entra ID issuer URL. The URL is in the following format: ``` https://login.microsoftonline.com//v2.0 ``` For example, if the tenant ID is `11111111-2222-3333-4444-555555555555`, then the issuer URL is: ``` https://login.microsoftonline.com/11111111-2222-3333-4444-555555555555/v2.0 ``` To construct the URL: 1. In the app registration, open **Overview**. 2. Copy the value of **Directory (tenant) ID**. 3. Substitute the copied tenant ID into the URL. ### Client ID In the Fabricate SSO configuration, the value of **Client ID** is the value of **Application (client) ID** in Microsoft Entra ID. To obtain the value: 1. In the app registration, open **Overview**. 2. Copy **Application (client) ID**. ### Client secret In the Fabricate SSO configuration, the value of **Client Secret** is the **Value** of the secret that you created in **Certificates & secrets -> Client secrets**. Do not use the secret ID. Use the secret **Value**. ## Adding the required token claims for fallback The Microsoft Entra ID fallback for Fabricate requires that the following claims are available in the ID token: * `email` * `xms_edov` ### email claim To add the email cliam, in the app registration: 1. Go to **Token configuration**. 2. Click **Add optional claim**. 3. Choose **ID** as the token type. 4. Add the `email` claim. ### xms\_edov claim #### About the xms\_edov claim `xms_edov` is an Microsoft Entra ID-specific boolean claim that indicates whether the email domain owner is verified. When the standard `email_verified` claim is absent, Fabricate uses this claim as the verification signal for Microsoft Entra ID issuers . * For standard OIDC providers, `email_verified == true` still works. * For Microsoft Entra ID issuers, `xms_edov == true` is accepted as an equivalent fallback. #### Adding the xms\_edov claim `xms_edov` is not always exposed in the standard token configuration UI. You can instead add it in the app manifest. In the app registration: 1. Go to **Manifest**. 2. Find the `optionalClaims` section. 3. Ensure `idToken` includes both `email` and `xms_edov`. The manifest section should look similar to the following: ```json "optionalClaims": { "idToken": [ { "name": "email", "essential": false, "additionalProperties": [] }, { "name": "xms_edov", "essential": false, "additionalProperties": [] } ], "accessToken": [], "saml2Token": [] } ``` If `optionalClaims` already exists, do not replace existing claims. Instead, merge the new entries into the existing structure. ## Add group names to synchronize with Fabricate ### About group name synchronization Fabricate can optionally synchronize a user's Fabricate account group memberships with group names that Entra ID sends when the user signs in. The user is then automatically added to the matching Fabricate account group. Fabricate only synchronizes groups that are assigned to the Fabricate application. Fabricate matches the values in the `groups` claim to existing Fabricate group names. The group name match is case insensitive. Fabricate does not create missing groups automatically. ### Add the groups claim to the app registration Tp add the groups claim in the app registration: 1. Go to **Token configuration**. 2. Click **Add groups claim**. 3. For group type, select **Groups assigned to the application**. This is required for cloud-only group display names. It is also recommended generally because it keeps tokens smaller and reduces group overage risk. 4. Expand the **ID** token customization section. 5. Choose the group value format: * If the Fabricate groups should match Active Directory -synced group names, choose **sAMAccountName**. * If the groups are cloud-only Entra groups, leave **Group ID** selected for now. The portal might not expose cloud-only display names here. 6. Click **Add** or **Save**. ### Assign Entra ID groups to the Fabricate enterprise application After you configure the claim, assign the relevant Entra groups to the Fabricate enterprise application. Fabricate only synchronizes the assigned groups. #### Locate the enterprise application Entra ID normally creates the enterprise application automatically for the app registration. To find it: 1. In the app registration, open **Overview**. 2. Click **Managed application in local directory**. This opens the matching enterprise application. 3. If that link is not visible: 1. Go to **Microsoft Entra ID** -> **Enterprise applications.** 2. Clear the filters. 3. Search for the app registration name or **Application (client) ID**. #### Assign the groups to the application To assign the groups: 1. Go to **Microsoft Entra ID**. 2. Open **Enterprise applications**. 3. Open the Fabricate SSO application. 4. Go to **Users and groups**. 5. Click **Add user/group**. 6. Assign the Entra groups for which to send the group names to Fabricate. When **Groups assigned to the application** is selected, Entra ID only emits groups that: * Are assigned to the application. * Are present in the signed-in user's memberships. Microsoft documents this as direct membership behavior. Make sure to assign the group that directly contains the user that you expect to test with. ### Add display names to the app manifest For cloud-only Entra groups, update the app manifest so that Entra ID emits display names instead of group object identifiers. Note that even though the manifest supports this option, the **Token configuration** configuration often does not expose it. In the app registration: 1. Go to **Manifest**. 2. Find `groupMembershipClaims`. 3. Set it to `ApplicationGroup`. 4. Find `optionalClaims.idToken`. 5. Update the `groups` optional claim so its `additionalProperties` includes `cloud_displayname`. ### Manifest examples Here is an example of the basic manifest structure: ```json "groupMembershipClaims": "ApplicationGroup", "optionalClaims": { "idToken": [ { "name": "groups", "source": null, "essential": false, "additionalProperties": [ "cloud_displayname" ] } ], "accessToken": [], "saml2Token": [] } ``` {% hint style="info" %} if `groupMembershipClaims` is `None`, Entra does not emit the `groups` claim, even if `optionalClaims.idToken` includes a `groups` entry. {% endhint %} #### Configuration to match group names to SA If: * The groups are synchronized from on-premises Active Directory (AD). * Fabricate groups must match `sAMAccountName`, then use: ```json { "name": "groups", "source": null, "essential": false, "additionalProperties": [ "sam_account_name" ] } ``` #### Configuration for a mix of both AD-synchronized and cloud-only groups For mixed environments, where the assigned application groups include both AD-synced groups and cloud-only groups, use: ```json { "name": "groups", "source": null, "essential": false, "additionalProperties": [ "sam_account_name", "cloud_displayname" ] } ``` ### Limitations and troubleshooting #### Limitations Note the following limitations: * When too many groups would be included in the token, Entra ID might emit group overage claims instead of `groups` . * Fabricate uses the group names that are present in the token. It does not call Microsoft Graph to resolve overage claims. * For the Fabricate synchronization to assign a user to a Fabricate account group: * The Fabricate group must already exist. * The Fabricate group name must match the emitted Entra group value. * If Entra ID emits group object identifiers, Fabricate treats those IDs as group names. The group identifiers will not match Fabricate group names. * To assign groups to an enterprise application, the tenant might need the appropriate Entra ID licensing. #### Debugging When the group synchronization is configured correctly, the expected response is: ```json { "id_token_groups": ["Fabricate Developers"], "normalized_group_names": ["Fabricate Developers"] } ``` If `id_token_groups` is missing, check that: * `groupMembershipClaims` is `ApplicationGroup` * The group is assigned to the enterprise application. If `id_token_groups` contains GUIDs, check that the `groups` optional claim includes either: * For cloud-only groups, `cloud_displayname`. * For AD-synced groups, the correct AD-synchronized name property . --- # 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/fabricate/fabricate-accounts-and-users/managing-account-users/single-sign-on-sso/microsoft-entra-id-configuration.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.