> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fiddler.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Microsoft Entra ID OIDC
> Learn how to configure Fiddler with Microsoft Entra ID (formerly Azure AD) for Single Sign-On (SSO) using the OpenID Connect (OIDC) protocol.
## Overview
This integration allows your users to sign in to Fiddler using their existing Microsoft Entra ID account, without needing a separate Fiddler password. Users are automatically provisioned on their first successful login — no manual invitations required. Entra ID group memberships can be synchronized to Fiddler teams.
## Prerequisites
Before starting, ensure you have:
* **Microsoft Entra ID Administrator Access**: Permissions to register applications and grant admin consent in your Entra ID tenant.
* **Fiddler AuthN Administrator Access**: Org Owner role in Fiddler's AuthN management console.
* **Deployment Information**: The hostname of your Fiddler deployment, e.g. `idpexample.dev.fiddler.ai`.
* **Entra ID P2 License** (cloud-native group sync only): required to emit group display names for cloud-native groups. Not needed for basic SSO or for groups synced from on-premises AD.
## Configuring Microsoft Entra ID
Fiddler requires two redirect URIs on the Entra ID application — one added during registration, the second under *Authentication*:
* `https://authn-{base_url}/ui/login/login/externalidp/callback`
* `https://authn-{base_url}/idps/callback`
Replace `{base_url}` with your Fiddler deployment host (e.g. `idpexample.dev.fiddler.ai`).
1. In the [Microsoft Entra admin center](https://entra.microsoft.com/), go to *Entra ID → App registrations* and select *New registration*.
2. Enter a *Name*, e.g. `Fiddler IdP Example`.
3. Under *Supported account types*, select *Accounts in this organizational directory only (Default Directory only - Single tenant)*.
4. Under *Redirect URI*, select the *Web* platform and enter the first redirect URI (replace the host with your deployment): `https://authn-idpexample.dev.fiddler.ai/ui/login/login/externalidp/callback`.
5. Select *Register*.
1. In the registered application, go to *Manage → Authentication*.
2. Under *Redirect URI configuration*, select *Add Redirect URI*.
3. Select *Web* and add the second redirect URI (replace the host with your deployment): `https://authn-idpexample.dev.fiddler.ai/idps/callback`.
4. Select *Configure*.
1. In the registered application, go to *Certificates & secrets*. Under *Client secrets*, select *New client secret*.
2. Add a description, choose an expiry, and select *Add*.
3. Copy the secret *Value* immediately — it is shown only once.
1. In the registered application, go to *API permissions* and select *Add a permission → Microsoft Graph → Delegated permissions*.
2. Select `openid`, `email`, `profile`, `offline_access`, and `User.Read`, then select *Add permissions*.
3. Select *Grant admin consent for Default Directory*.
Add the claims Fiddler needs to the ID token.
1. In the registered application, go to *Token configuration*.
2. Select *Add optional claim*, choose the *ID* token type, and add `email`, `given_name`, and `family_name`. When prompted, enable the option to turn on the Microsoft Graph `email` and `profile` permissions (required for these claims to appear in the token), then select *Add*.
3. Select *Add groups claim*, choose *Groups assigned to the application*, select the *ID* token, then select *Add*. Only the ID token is required for Fiddler. By default Entra emits group IDs (GUIDs); to emit the group **names** that Fiddler maps to teams, complete [Enable Group Sync](#enable-group-sync) below.
From the registered application's *Overview* page, copy the *Application (client) ID* and the *Directory (tenant) ID*. You will need these, along with the client secret, when configuring Fiddler.
## Configuring Fiddler
The URL to the Fiddler AuthN management console is your Fiddler instance base URL prepended with `authn-`. For example, if your Fiddler base URL is `https://idpexample.dev.fiddler.ai` then you will access the AuthN management console at `https://authn-idpexample.dev.fiddler.ai`.
Sign in using the AuthN console Org Owner user account credentials provided by your Fiddler representative.
Ensure your organization is selected in the dropdown. You may see the *fiddler* organization, but this is reserved for system use and should not be edited. Here we are using the *idpexample* organization.
Select *Settings* tab from the top menu and then select *Identity Providers* from the left navigation menu.
1. Select the *Microsoft* option in the *Add provider* section, which brings up the Microsoft Provider form.
2. Note the callback URL shown in the form — it corresponds to the redirect URIs you registered in Entra ID earlier, so no further changes are needed in Entra ID.
1. In the Microsoft Provider form, enter the following values:
1. Enter a name in the *Name* text box. This name is displayed on the SSO login button on the Fiddler sign-in page, so choose one your users will recognize.
2. In the *Client ID* and *Client Secret* text boxes, paste those values copied from Entra ID.
1. Expand the *optional* section.
2. Ensure the *Scopes List* includes `openid`, `profile`, and `email`.
3. Under *Tenant Type*, select *Tenant ID* and paste your *Directory (tenant) ID*.
4. Ensure the *Automatic create* and *Automatic update* checkboxes are selected.
5. Set the *Determines whether an identity will be prompted to be linked to an existing account* dropdown to *Check for existing Username*.
Select the *Create* button and then select the *Save* button. You will be returned to the Organization Settings page.
1. Select your IdP from the list and select the *Activate* button on the identity provider page.
2. Close the settings and then select *Login Behavior and Security* from the left nav menu and ensure the *External login allowed* checkbox is selected.
3. Select the *Save* button.
Select the *Actions* tab from the top menu.
1. Select the *New* button in the *Scripts* section to create a new action script.
2. Copy the *Microsoft Entra ID Action Script* below and paste it into the script text area.
3. Enter `setAttributesOnAzureOIDCAuth` in the *Name* text box.
4. Select the *Add* button.
**File:** `Microsoft Entra ID Action Script`
```javascript theme={null}
function setAttributesOnAzureOIDCAuth(ctx, api) {
let firstName = ctx.getClaim('given_name');
let lastName = ctx.getClaim('family_name');
let email = ctx.getClaim('email');
let groups = ctx.getClaim('groups');
let nameParts = [firstName, lastName];
let filteredParts = nameParts.filter(part => part);
let displayName = filteredParts.join(' ');
if (firstName != undefined) {
api.setFirstName(firstName);
}
if (lastName != undefined) {
api.setLastName(lastName);
}
if (email != undefined) {
email = email.toLowerCase();
api.setEmail(email);
api.setEmailVerified(true);
api.setPreferredUsername(email);
}
if (displayName) {
api.setDisplayName(displayName);
}
api.v1.user.appendMetadata('fiddler_authentication_type', 'SSO:AZURE:OIDC');
if (groups === null || groups === undefined){
groups = []
}
api.v1.user.appendMetadata('fiddler_groups', groups);
}
```
Scroll down to the *Flows* section.
1. Select the *External Authentication* option for the *Flow Type* dropdown.
2. Select the *+ Add trigger* button.
3. Select the *Post Authentication* option for the *Trigger Type* dropdown.
4. Select the *setAttributesOnAzureOIDCAuth* option for the *Actions* dropdown.
5. Select the *Save* button.
Add an organization metadata key so Fiddler can correctly identify and process this SSO connection. Set this once during setup.
1. Go to the *Metadata* section and select *Edit*.
2. Select the *Add* button, then enter the key `fiddler_sso_authentication_type` with the value `SSO:AZURE:OIDC`.
3. Select the *Save* button next to the new entry.
Before validating, ensure your Entra ID account is assigned to the registered application (or that user assignment is not required).
1. Open your Fiddler URL (e.g. `https://idpexample.dev.fiddler.ai`).
2. Ensure you see the Fiddler sign-in page and that it displays an SSO login button labeled with the name you configured.
3. Select the button and confirm that the Fiddler application loads.
The first user to sign in to the Fiddler application is automatically assigned the Fiddler Org Admin role; subsequent members are Org Members by default.
## Enable Group Sync
Fiddler maps identity provider group **names** (with a configurable prefix) to Fiddler teams and roles — see [Mapping AD Groups to Fiddler Teams](/reference/access-control/mapping-ad-groups-to-fiddler-teams) for the naming convention. By default, Entra ID emits group **IDs** (GUIDs) in the token, which Fiddler cannot map — so group sync requires emitting group display names.
### Cloud-native groups
Emitting display names for cloud-native groups requires an **Entra ID P2** license.
1. In *Enterprise applications*, open your application, go to *Users and groups*, and assign the users and groups that should be sent to Fiddler. Only groups assigned to the application are returned.
2. In the registered application, go to *Manage → Manifest*. Download a copy of the manifest first as a backup, then update it:
1. Set `groupMembershipClaims` to `ApplicationGroup`.
2. In `optionalClaims.idToken`, set the `groups` claim's `additionalProperties` to `["cloud_displayname"]` so display names are returned.
3. Save the manifest.
### On-premises-synced groups
For groups synced from on-premises AD, set the groups claim format to `sAMAccountName` in *Token configuration*. This requires no manifest change or P2 license.
## Getting Help
If sign-in fails, review the Entra ID sign-in logs (*Entra ID → Monitoring & health → Sign-in logs*) for the failed attempt and its reason. Common Entra error codes:
* `AADSTS50105` — the user is not assigned to the application. Assign the user (or their group) to the registered application.
* `AADSTS700016` — the application was not found. Verify the Client ID and tenant are correct.
* `AADSTS90094` — admin consent is required. Grant admin consent for the API permissions.
For Fiddler-side issues, see the [SSO Authentication Guide](/reference/access-control/sso-authentication-guide). If the issue persists, contact your Fiddler representative with the specific error message.
## Important Notes
* **Data Storage**: Fiddler stores the following profile attributes from Entra ID: first name, last name, display name, email address, and group memberships (used to map users to Fiddler teams).
* **API Access**: For programmatic API access, users create an API key from the *Credentials* tab in Fiddler's *Settings* page.
* **Single Authentication Method**: Users can only authenticate via either SSO or email authentication, not both.
* **Client Secret Expiration**: Entra ID client secrets expire. Track the expiry date and rotate the secret before it lapses to avoid login outages.
## Next Steps
After successful integration:
* **Train Users**: Provide guidance on accessing Fiddler through Microsoft Entra ID SSO.
* **Configure Teams**: Map your Entra ID groups to Fiddler teams — see [Mapping AD Groups to Fiddler Teams](/reference/access-control/mapping-ad-groups-to-fiddler-teams).
* **Test Group Sync**: Verify automatic group synchronization is working as expected.
* **Monitor Usage**: Review authentication logs and set a reminder for client secret expiration.