How to Configure SAML Group Mapping with Microsoft Entra ID

SAML group mapping assigns Apidog team access from the groups included in a user's SAML assertion. It reduces manual team membership work while keeping the identity provider as the source of group membership.

This tutorial uses Microsoft Entra ID. You will add a groups claim, map an Entra group to an Apidog team, and verify the initial project permissions assigned at sign-in.

Before you start

You need:

• an Apidog Enterprise organization with SAML SSO already configured;
• Organization Owner or Organization Admin access in Apidog;
• administrator access to the Microsoft Entra enterprise application used for Apidog;
• at least one Entra group and a test user assigned to that group.

If SAML is not configured yet, complete Configuring Microsoft Entra ID first.

SAML group mapping controls access to Apidog teams and projects. It does not grant access to production APIs or replace runtime authorization.

How initial project access is assigned

When a group matches, Apidog adds the user to the mapped team and derives initial project access from the selected team role.

Apidog creates missing project memberships or updates project memberships that do not yet have a role. An existing manually assigned project role is not overwritten during later SAML sign-ins.

Step 1: Add the groups claim in Microsoft Entra ID

1. Sign in to the Microsoft Entra admin center.
2. Go to Enterprise applications and open the application used for Apidog SSO.
3. Select Single sign-on, then open Attributes & Claims.
4. Select Add a group claim.
5. Choose All groups.
6. Enable Customize the name of the group claim and enter groups as the claim name.
7. Save the claim.

Configure the group claim so Apidog receives Entra group Object IDs in the groups attribute.

Apidog uses the group Object IDs in this claim. It does not retrieve other information about the groups from Microsoft Entra ID.

Step 2: Copy the Entra group name and Object ID

1. In Microsoft Entra ID, open Groups.
2. Select the group that should receive access in Apidog.
3. Copy its Name and Object ID.

Use the Object ID shown on the Entra group page. Do not use an application ID, tenant ID, or display name in place of the Object ID.

Keep this page available while you configure the mapping in Apidog.

Step 3: Map the group to an Apidog team

1. Open the organization in Apidog.
2. Go to the organization's SAML Group settings.
3. Add a group mapping.
4. Enter the Entra group name and paste its Object ID.
5. Select the Apidog team or teams the group should access.
6. Choose the required team role for each mapped team.
7. Save the mapping.

Map the Entra group Object ID to the required Apidog teams and team roles.

There is no separate project-role selector in SAML group mapping. The initial project role comes from the team role shown in the table above. Adjust a user's project role later from project member settings when different access is required.

Step 4: Test the mapping

Use a test account rather than an administrator account.

1. Confirm that the test user belongs to the mapped Entra group.
2. Sign out of Apidog.
3. Sign in through the organization's SSO entry point.
4. Open the mapped team and confirm that it is available.
5. Check the user's team role.
6. Open the team's projects and confirm the initial project role.

If the user already had a manually assigned project role, confirm that the role remains unchanged after another SSO sign-in.

Verify membership removal

Group removal should also be tested before rollout.

1. Remove the test user from the mapped Entra group.
2. Allow the identity-provider change to complete.
3. Have the user sign in through SSO again.
4. Check the corresponding team membership and project memberships.

When a user is no longer included in a mapped group, Apidog may remove the user from the corresponding team during SAML synchronization. If the team membership is removed, project memberships in that team are also removed.

Do not use a production account for the first removal test. Record the observed result for your identity configuration and offboarding procedure.

Troubleshooting

Important limitations

• Apidog does not create or delete identity-provider groups through SCIM.
• SAML group mapping does not provide a separate role setting for each project.
• Existing assigned project roles are not reset on later SSO sign-ins.
• If several mappings could apply to the same user and team, test the result before rollout rather than assuming a precedence rule.
• Workspace roles do not authorize calls to deployed APIs.

Related API governance tutorials:

These tutorials cover complementary controls for governing an enterprise API workspace:

• API Governance Framework — connect ownership, controls, evidence, and lifecycle decisions.
• SAML Group Mapping with Microsoft Entra ID — assign team access from identity-provider groups.
• Secret Scanner — review possible exposed credentials in supported Apidog assets.
• Audit Logs — investigate and export administrative organization activity.
• SCIM Provisioning — manage organization users through the identity lifecycle.
• Enterprise Policies — configure credential, membership, SSO-session, and invitation controls.
• Self-Service API Teams — allow member-created teams while retaining ownership oversight.
• GitHub Enterprise Cloud Integration — connect supported GHE.com repositories for OpenAPI workflows.

Related official documentation:

• Mapping Groups to Teams
• Configuring Microsoft Entra ID
• Introduction to SCIM Provisioning
• Organization Role and Permissions