How to Configure SAML Group Mapping with Microsoft Entra ID

Map Microsoft Entra ID Groups to Apidog Teams with SAML

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

Try Apidog today

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, first complete Configuring Microsoft Entra ID.

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 works

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

Mapped team role	Initial project role
Team Admin	Project Maintainer
Team Member	Project Readonly
Team Guest	Project Readonly

Apidog creates missing project memberships or updates project memberships without 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 additional group information 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 substitute an application ID, tenant ID, or display name.

Keep this page open while configuring 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 team.
7. Save the mapping.

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

SAML group mapping has no separate project-role selector. The initial project role comes from the team role shown above. To grant different access later, adjust the user's project role from the project member settings.

Step 4: Test the mapping

Use a test account instead of 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, verify that it remains unchanged after another SSO sign-in.

Verify membership removal

Test group removal before rolling out the mapping.

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 and project memberships.

When a user is no longer included in a mapped group, Apidog may remove them from the corresponding team during SAML synchronization. If 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

Problem	What to check
The user signs in but is not added to the team	Confirm the claim is named exactly groups, the assertion contains the expected Object ID, and the Object ID in Apidog has no extra spaces.
The assertion has no group values	Confirm the user belongs to the group and the Entra enterprise application sends group claims. For users with many group memberships, review Microsoft's group-claim overage guidance.
The user has the wrong project role	Check the mapped team role. Existing project roles are not overwritten by later SAML synchronization.
A group change is not reflected	Confirm the change has reached Entra, then start a new SSO sign-in so Apidog can synchronize the current assertion.
The user remains in the organization	SAML group mapping manages mapped team access. Organization membership may also be managed through invitations, SSO, or SCIM.

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 during later SSO sign-ins.
• If several mappings could apply to the same user and team, test the result before rollout instead of 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