Extend Azure Active Directory integration to also support mapping via group names

Release notes

Support for group synchronization via group names in Microsoft Azure Active Directory integration

Problem to solve

When using SAML Group Sync with Microsoft Entra (Azure AD), the latter only provides up to 150 groups in the SAML response in order to limit the size of the returned token. To provide Group Sync also in such a scenario, GitLab support retrieving group memberships via the Microsoft Graph API (see Microsoft Azure Active Directory integration). However, in this case, the Group links cannot be defined using the (speaking) AD group names but their unique IDs (like 12345678-9abc-def0-1234-56789abcde).

This approach has disadvantages:

1. Users who are responsible for GitLab groups and who need to have the latter synchronized to AD groups do usually not have access to AD group IDs.
2. Even if users have access to the group IDs, it is hard to impossible to tell who has access to a GitLab group by looking at the SAML Group Links.
3. If SAML Group Links have been set up without configuring the Azure AD integration (i. e. Microsoft Graph API access, e. g. because a company does not yet have so many groups), they will probably be based on group names and not IDs. If later the number of AD groups grows and the Azure AD integration is to be added to the configuration, all existing SAML Group Links need to be replaced in GitLab, which is tedious and bears a high risk of group memberships getting lost.

AD group synchronization is becoming more and more important due increasing requirements regarding data security and intellectual property protection. We see a clear tendency and even pressure from that side that users will have to be managed centrally across several applications (GitLab being one of them). We also see that in consequence to this, the the number of AD groups in our company increases considerably, such that we already hit the limit of 150 groups.

Proposal

The background for the limitation probably is that the Microsoft Graph API only returns group IDs when the group membership of a user is requested. The proposal is to add another API call requesting the group details for all group IDs that had been returned for a user (presumably via https://graph.microsoft.com/v1.0/groups/{group-id}. This should allow to get the group names, such that users can continue to configure Group Links based on group names.

The current mechanism would be extended, such that links based on group IDs continue to be supported to provide compatibility to the current behavior.

Considering that this will probably affect the performance of the group sync mechanism (since additional requests need to be executed), it might be worth spending an option in the 'Azure AD Integration' global settings to activate or deactivate this feature.

The benefit would be better transparency, reduced risk for misconfigured Group Links and thus saved time on the users' sides.

Intended users

• Parker (Product Manager)
• Delaney (Development Team Lead)
• Sasha (Software Developer)
• Sidney (Systems Administrator)
• Allison (Application Ops)
• Amy (Application Security Engineer)
• Isaac (Infrastructure Engineer)
• Cameron (Compliance Manager)

Feature Usage Metrics

Monitor the usage of the proposed option in 'Azure AD Integration' global settings (number of instances with the proposed "extended" Azure AD integration vs. number of instances without).

Does this feature require an audit event?

Not sure. I generally propose to provide details on Azure ID integration in the logs, i. e. requests sent and responses received for troubleshooting, comparable to the SAML responses. This would then include the proposed additional requests to the Microsoft Graph API.