Single sign-on from Azure AD to GitLab based on groups

Table of contents

Configure single sign-on

Create enterprise apps in Azure AD

SAML basic configuration

配置 Azure “Attributes & Claims”

Configure User Synchronization

Create SCIM Token in Jihu GitLab

Configure Azure Provisioning

Azure manual user provisioning

Test single sign-on

Azure automatic user synchronization

Configure group sync

Configure SAML Group Links

Azure Configuration Group Claim

possible problems

After single sign-on, it jumps to Jihu GitLab login page, prompting that association is required

The login is unsuccessful, jumping to the login page, no prompt to associate

User disappears from group immediately after login

---

This article comes from

Liu Kang Jihu (GitLab) Senior Site Reliability Engineer

Many organizations have a unified identity authentication platform, usually based on organizational structure or team division of labor, and organize users in groups, such as LDAP, Azure Active Directory (Azure AD), Google Workspace, OneLogin, Authing, etc., this authentication The service is also called Identity Provider (hereinafter referred to as IdP).

Based on the IdP, organization members can access various services or systems in the organization based on assigned permissions through single sign-on, such as mailboxes, OA, and employee self-service systems.

Jihu GitLab also supports access to each organization's own IdP.

In Jihu GitLab, organizations such as enterprises or teams are usually managed based on groups. Single sign-on from IdP to Jifox GitLab can be realized by establishing association between IdP and Jifox GitLab group. Among them, SAML is a widely supported protocol for establishing single sign-on.

This article will introduce in detail how to configure single sign-on from Azure AD to GitLab based on "Group SAML SSO". Certainly, for other IdPs, similar processes are also performed.

Note: Jifox GitLab Professional Edition and Ultimate Edition support this function.

Configure single sign-on

---

As an IdP, Azure AD's single sign-on to other systems is managed through an enterprise application (Enterprise Application).

Create enterprise apps in Azure AD

Log in to Azure with an account with Azure AD permissions to create an enterprise application.

1. Enter "Azure Active Directory";

2. Click on "Enterprise applications" in the left navigation bar;

3. Click the "+ New application" button;

4. Click "+ Create your own application" and select "Integrate any other application you don't find in the gallery (Non-gallery)" (not library));

5. Give the application an easily recognizable name, such as "jihulab.com" or "jihulab.com/mygroup1", and click the "Create" button to create it.

Then go into the enterprise application, click on "Single sign-on" and select "SAML".

SAML basic configuration

In Jihu GitLab, enter the group that needs to configure SAML, click "Setting" (Settings) → "SAML SSO" (SAML SSO (single sign-on)).

Note:

1. The example in this article is to  azure-saml-test configure single sign-on for groups.

2. The screenshots in this article were taken in the staging environment, so the link is  staging.jihulab.com.

Please fill in the information for each other as shown in the figure below (the left side is the Azure single sign-on configuration page, and the right side is the Jihu GitLab SAML SSO configuration page):

Note: On the Jihu GitLab SAML SSO configuration page, in the "Configuration" section, if you check "Enforce SSO-only authentication for web activity for this group" , the group will only support single sign-on identities, and cannot log in through conventional login methods.

配置 Azure “Attributes & Claims”

When the two systems perform authentication and authorization, they need to determine the mapping relationship of user attributes. For example, SAML authentication requires a unique field for user association, and we usually map Azure users  objectid as this field ( user.userprincipalname it is unique and can also be used).

In the "Attributes & Claims" section of Azure, click "Edit" to adjust the default mapping:

in,

1. For "Unique User Identifier", select "Persistent" for "Name identifier format", select "Source attribute"  user.objectid;

2. Others are just tweaks involving claim names.

At this point, the initial configuration of the part related to single sign-on is completed.

Configure User Synchronization

---

User provisioning (User provision) is one of the functions of SCIM, which can automatically create users under the enterprise application program to Jihu GitLab, and when the user is added, modified, deleted, etc., it will be automatically synchronized to Jihu GitLab.

Create SCIM Token in Jihu GitLab

This Token is used by Azure to create and update users in Jihu GitLab.

At the bottom of Jihu GitLab SAML SSO settings page, click the "Generate a SCIM token" button.

The generated token is as follows:

Configure Azure Provisioning

Click "Provisioning" in the left navigation bar of "Enterprise application", and click "Get started" for initial configuration.

Select "Automatic" for "Provisioning Mode" and fill in the URL and Token just generated. Click Save after the test is successful.

At this point, the "Mapping" (mapping) menu will appear below, expand and set "Provision Azure Active Directory Groups" to Enabled=No (enabled = No), currently GitLab does not support Jihu.

Here is the automatic creation and synchronization of the subgroup hierarchy, which GitLab does not support. However, the information of the group to which the user belongs can be synchronized. For example, if the user adjusts from group A to B, this situation can be synchronized.

Next, configure the attribute mapping relationship when users are created and synchronized. Click "Provision Azure Active Directory Users" to enter, and adjust the mapping relationship as follows:

This defines which fields of the Azure AD user correspond to which fields of the Jihu GitLab user when Azure pushes user attributes to Jihu GitLab and creates a user in Jihu GitLab.

1. Please make sure that the configured user attributes with mapping relationships have values, otherwise it will cause failure to create users, especially the fields required by Jihu GitLab , including:

• externalId, the "Unique User Identifier" (unique user identifier) ​​when configuring single sign-on earlier;

• userName, corresponding to the Jihu GitLab user account, cannot be empty;

• emails[type eq "work"].value, Jihu GitLab uses it as the user mailbox, which cannot be empty. Note that user.mail it is sometimes empty. If the mailbox of the Azure user is maintained in other fields (such as userPrincipalName), you can replace it with the corresponding field here  mail.

2. The adjustment of the mapping relationship should be consistent with the Attribute Mapping of SAML SSO. For example externalId, if the previous configuration is  user.objectid, it must be consistent here. The special feature of this field is that it is a unique user identifier for matching, so "Match objects using this attribute" (using this attribute to match objects) is enabled, and the matching priority is the highest . As shown below:

For the "required" field, you can configure it in the "Edit customappsso attributes list" (edit customappsso attribute list) under "advanced options" (display advanced options), tick "Required?".

Azure manual user provisioning

At this point, we can manually push an Azure user to GitLab Jihu and try to perform single sign-on to confirm whether the configuration of single sign-on and user provisioning is correct.

Only after the users or groups managed by Azure AD are added to the enterprise application configured with SAML SSO can SSO be performed.

Click on "Users and groups" in the left navigation bar of Azure's enterprise application, then click on "+ Add user/group" and select the group or user as required.

Users included in the selected users and groups can perform user provisioning and single sign-on.

Click "Provision on demand" under "Provisioning", select the user to be pushed, and click the "Provision" button; then confirm whether the result of user creation (or update) is correct, Are the values ​​of each field correct?

At this time, on the SAML SSO configuration page of Jihu GitLab, you should be able to see that the user has been created and assigned to the group.

The user can also be seen in the member list of the group, and the SAML tag identifies that the user was created through SAML.

At this time, the mailbox of the pushed user will receive a welcome email and a confirmation email. Please click the link in the confirmation email to complete email verification.

Test single sign-on

Then, we can test whether the user who has just been pushed manually can achieve single sign-on normally.

There are various methods of single sign-on, such as:

1. Log in through the "GitLab single sign-on URL" (GitLab single sign-on URL) in the SAML SSO configuration page, usually an https://jihulab.com/groups//-/saml/sso?token=xxxxxxxx address like this;

2. If on the SAML SSO configuration page, "Configuration" section, check "Enforce SSO-only authentication for web activity for this group" (Enforce SSO-only authentication for web activity for this group), then access the group When the group address is set ( https://jihulab.com/), it will automatically jump to the Azure login page.

Under normal circumstances, after completing the login on the Azure login page, or when Azure is already logged in, you will be redirected to the related page of Jifox GitLab. When logging in for the first time, you need to complete email and mobile phone number verification, and then you can enter the group page:

Azure automatic user synchronization

After testing, the single sign-on and user synchronization are configured correctly, and then the automatic user synchronization of Azure can be enabled.

In the Azure "Provisioning" interface, click "Started provisioning" to enable automatic user synchronization, and the users and groups (users in the group) added to the current enterprise application will be automatically Synchronized to Jifox GitLab, and automatically updated with the adjustment of user information in Azure.

As shown in the figure, you can view the creation or update of users in the log.

Note that users in subgroups under the selected group will not be created.  For example, if there is such a user and group structure  , if it is selected but not selected  group_a/group_aa/user_aa0in the enterprise application  , the user   will not be created and synchronized.group_agroup_aauser_aa0

Configure group sync

---

Some users want to be able to completely synchronize the organizational structure of groups and users on the Azure side to GitLab. This function can be partially realized:

• Groups in Azure will not be automatically synchronized to Jifox GitLab, and need to be created in Jifox GitLab in advance;

• The corresponding relationship between Azure and Jihu GitLab groups needs to be maintained manually;

• The user's affiliation to the group can be automatically updated to GitLab.

Suppose the organizational structure in Azure AD is like this:

Azure AD
├── group_a
│   ├── group_aa
│   │   └── user_aa0
│   ├── user_a0
│   └── user_a1
└── group_b    
     └── user_b0

Jihu GitLab also has a corresponding subgroup relationship:

Then you need to configure the association relationship of all groups in sequence.

Configure SAML Group Links

First find the "Object Id" of each group under Azure AD "Groups":

Then enter "Settings → SAML Group Links" (Settings → SAML Group Links) under the corresponding subgroup of Jihu GitLab to configure the association relationship and access level:

Azure Configuration Group Claim

When the groups association relationship between the two systems is established, when the user logs in through SSO, if he carries the group ID information, it will be assigned to the corresponding subgroup by GitLab according to the preset access level.

Therefore, it is necessary to configure the "Attribute & Claims" information of SAML SSO:

Please note that here is to select the "+ Add a group claim" button, and the claim name needs to be customized as Groups.

In this way, when users log in to GitLab through Azure SAML SSO, they can have the correct subgroup permissions. Groups If the user in Azure AD is migrated to another group, when the user logs in again, Jihu GitLab will give the user the correct subgroup permission according to the information carried in the SAML response, of course, the  premise is that the relevant subgroup The group is linked with the corresponding group in Azure.

possible problems

---

After single sign-on, it jumps to Jihu GitLab login page, prompting that association is required

As shown below:

After the user reaches Jihulab.com through SSO, he jumps to the login page, and the above prompt is as follows:

• English: Sign in to GitLab to connect your organization's account

• English: Log in to GitLab to connect your organization's account

The reason is that according to the user information given by SAML login (the above user attribute mapping information, especially the Unique User Identifier), the corresponding user is not found on Jihulab.com, so the user is prompted to log in to Jihu GitLab (usually used for The customer already has a SaaS account, otherwise the customer is not recommended to do this ), the system will associate the SAML account with the account logged in at this time, and the SAML user can log in to GitLab normally through SSO in the future.

possible reason:

• The mapping relationship between "Unique User Identifier" (unique user identifier) ​​configured in Azure SSO and Azure Provisioning (provisioning) is inconsistent.

  For example, one uses  user.objectidand the other uses  user.userPrincipalName;

• The corresponding email address of the Azure user already exists in Jihu GitLab, so Provisioning is not successful, but Jihu GitLab finds that the mailbox already exists, so it prompts that there may already be an account and asks the user to associate it.

Suggested approach:

• For those who already have a SaaS account, such as a customer migrating from Gitlab.com to Jihu GitLab, the SSO login of Azure AD has been established on Gitlab.com before, and there is already a user, and the user needs to perform an associated login operation , make sure that the accounts of Azure AD and SaaS are corresponding.

• If you do not have a SaaS account, you need to operate User Provisioning in Azure first to create the user.

Sometimes the group on the GitLab side of Jihu is created by the customer's IT engineer through a user registered in Jihu GitLab, then the engineer can be guided to associate the account, and other users on the customer's side are still created by user push.

The login is unsuccessful, jumping to the login page, no prompt to associate

Please contact technical support and ask the technician to confirm the cause.

Users can also use SAML browser plug-ins (such as SAML, WS-Federation and OAuth tracer) to analyze whether the "Claims" part of the SAML Response is missing some information (such as email), and check whether the Attribute & Claims mapping in Azure is correct.

User disappears from group immediately after login

Typical performance:

• After logging in, the user is not directly redirected to the configured group, but a page similar to the first login of a new user after registration, such as asking what role is it, what do you want to do with Jihu GitLab, etc.;

• The group administrator checked and found that the user is no longer in the member list, and checked "Security & Compliance → Audit events" (Security → Audit events) and found that the user was removed from the group, and the removal time occurred one day after login. within two seconds;

• Please check with Jihu GitLab technical support and find that the user is still there, but not under the group it should be in.

The possible reason is that the group claim of Azure SAML single sign-on is configured, but the "SAML group link" of Jihu GitLab is not configured correctly.

reference

1.  SAML SSO single sign-on

2.  Azure AD SAML single sign-on configuration example

3. SAML Group Sync