Info
This guide describes how Gitlab CE v13.x can be configured as a SAML Service Provider for eduTEAMS. The integration via SAML provides more benefits than the integration via OIDC, as the SAML implementation in Gitlab has (limited) support for authorizing users using groups. The OIDC implementation in Gitlab supports only authenticating users.

1. In order to set up a basic configuration, which would allow all users from your VO to authenticate via eduTEAMS and access the Gitlab service, you should edit the omniauth section /etc/gitlab/gitlab.rb config file.

Code Block

language	py
title	/etc/gitlab/gitlab.rb
linenumbers	true

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_block_auto_created_users'] = false
 
gitlab_rails['omniauth_auto_link_saml_user'] = true
 
gitlab_rails['omniauth_providers'] = [
   {
      name: 'saml',
      label: 'eduTEAMS',
      args: {
         assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
         idp_cert_fingerprint: '72:8A:6C:6B:63:35:3F:E0:BF:70:8D:41:0E:B7:02:CF:C5:86:53:24',
         idp_sso_target_url: 'https://proxy.eduteams.org/saml2sp/sso/redirect',
         issuer: 'https://gitlab.example.com',
         name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
         uid: ["urn:oasis:names:tc:SAML:attribute:subject-id"],
         email: ["urn:oid:0.9.2342.19200300.100.1.3",],
         first_name: ["urn:oid:2.5.4.42"],
         last_name: ["urn:oid:2.5.4.4"]
      },
      groups_attribute: 'urn:oid:1.3.6.1.4.1.5923.1.1.1.7',
      required_groups: [],
      admin_groups: [],
      audit_groups: []
   }
]

2. in order to fill in this part correctly, you should have the set of information defined and known

Configuration Option	Value	Description
issuer	(example) https://gitlab.example.com ??	A unique name identifying the gitlab application to the proxy
idp_sso_target_url	https://proxy.eduteams.org/saml2sp/sso/redirect ??	This is the eduTEAMS endpoint supporting the HTTP-Redirect SAML 2.0 Binding
idp_cert_fingerprint	72:8A:6C:6B:63:35:3F:E0:BF:70:8D:41:0E:B7:02:CF:C5:86:53:24	This is the SHA1 fingerprint of the signing certificate used by the eduTEAMS SAML frontend
name_identifier_format	urn:oasis:names:tc:SAML:2.0:nameid-format:persistent	The NameID format requested
uid	urn:oasis:names:tc:SAML:attribute:subject-id	See Attributes available to Relying Parties#eduTEAMSIdentifier
email	urn:oid:0.9.2342.19200300.100.1.3	See Attributes available to Relying Parties#Emailaddress
first_name	urn:oid:2.5.4.42	See Attributes available to Relying Parties#GivenName
last_name	urn:oid:2.5.4.4	See Attributes available to Relying Parties#FamilyName
groups_attribute	urn:oid:1.3.6.1.4.1.5923.1.1.1.7	See Attributes available to Relying Parties#Groups
Full group definition: <URN namespace>:group:<VOName>:<Top level group>:<sub group name>#<Base DN of your instance>	(example) urn:geant:eduteams.org:service:eduteams:group:Test_VO:Developers#eduteams.org	You should replace Test_VO with your VO name to which you would like to connect the Gitlab

CONFIGURE GROUPS

The SAML login in Gitlab includes support for limiting access to specific groups from your VO and authorizing users using these groups. There are four groups types that can be configured: required, admin, audit and external.

1. In order to add to a basic configuration, which would allow all users from your VO to authenticate via eduTEAMS and access the Gitlab service, you should edit the omniauth section /etc/gitlab/gitlab.rb config file, after the groups_attribute section.

You can control which groups can access the Gitlab instance using the required_groups configuration option. When required_groups is not set or it is empty, anyone with proper authentication will be able to use the service.
You can control if a user should be assigned the admin role, using the admin_groups configuration option.
You can control if a user should be assigned the auditor role, using the audit_groups configuration option.
You can control if a user should be marked as external, using the external_groups configuration option.

Code Block

language	py
title	/etc/gitlab/gitlab.rb
linenumbers	true

      # Only the following groups in the Test_VO will be able to access this Gitlab instance:
      #
      # - Developers
      # - Admins:Gitlab
      # - Admins:Gitlab:Auditors
      required_groups: [
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Developers#eduteams.org',
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Developers#eduteams.org',
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Admins:Gitlab#eduteams.org',
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Admin:Gitlab:Auditors#eduteams.org',
      ],
      # Users from the following groups in the Test_VO will access this Gitlab instance as admins 
      #
      # - Admins:Gitlab:
      admin_groups: [
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Admins:Gitlab#eduteams.org',
      ],
      # Users from the following groups in the Test_VO will access this Gitlab instance as auditors:
      #
      # - Admins:Gitlab:Auditors
      audit_groups: [
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Admins:Gitlab:Auditors#eduteams.org',
      ],
      # Users from the following gorup in the Test_VO will access the Gitlab instance external users
      #
      # - Guests
      # - Contractors
      external_groups: [
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Guests#eduteams.org',
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Conractors#eduteams.org',

             ]

2. You should be able to check the SAML metadata URL of the Gitlab instance at https://<gitlab.example.com>/users/auth/saml/metadata .

Code Block

language	xml
linenumbers	true

<?xml version='1.0' encoding='UTF-8'?>
<md:EntityDescriptor ID="_9edb3dae-0919-40ff-b7c0-bffc63ba032b" entityID="https://gitlab.example.com/" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
    <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://gitlab.example.com/users/auth/saml/callback" index="0" isDefault="true" />
        <md:AttributeConsumingService index="1" isDefault="true">
            <md:ServiceName xml:lang="en">Required attributes</md:ServiceName>
            <md:RequestedAttribute FriendlyName="Email address" Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false" />
            <md:RequestedAttribute FriendlyName="Full name" Name="name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false" />
            <md:RequestedAttribute FriendlyName="Given name" Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false" />
            <md:RequestedAttribute FriendlyName="Family name" Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false" />
        </md:AttributeConsumingService>
    </md:SPSSODescriptor>
</md:EntityDescriptor>

3. Once you edited the omniauth section of the /etc/gitlab/gitlab.rb file as above indicated, you need to reconfigure gitlab with the command:

sudo gitlab-ctl reconfigure

4. Congratulations, you have successfully configured your Gitlab instance for eduTEAMS. Now you can proceed to register your service following the steps described in Registering services on the eduTEAMS Service.

TO BE DELETED

This guide describes how Gitlab CE can be configured as a SAML Service Provider for eduTEAMS and it assumes:

You are using Gitlab v13.x
You have access to edit the Gitlab configuration file at /etc/gitlab/gitlab.rb
The URL of your Gitlab instance is https://gitlab.example.com/
The name of your VO is Test_VO

It is possible to connect a Gitlab instance with eduTEAMS as a SAML Service Provider. The integration via SAML provides more benefits as the SAML implementation in Gitlab has (limited) support for authorizing users using groups. The OIDC implementation in Gitlab supports only authenticating users. As a reference this guide is available: https://docs.gitlab.com/13.0/ee/integration/saml.html .

In order to configure your Gitlab for eduTEAMS, you need the following information:

Configuration Option	Value	Description
issuer	(example) https://gitlab.example.com	A unique name identifying the gitlab application to the proxy
idp_sso_target_url	https://proxy.acc.eduteams.org/saml2sp/sso/redirect	This is the eduTEAMS endpoint supporting the HTTP-Redirect SAML 2.0 Binding
idp_cert_fingerprint	72:8A:6C:6B:63:35:3F:E0:BF:70:8D:41:0E:B7:02:CF:C5:86:53:24	This is the SHA1 fingerprint of the signing certificate used by the eduTEAMS SAML frontend
name_identifier_format	urn:oasis:names:tc:SAML:2.0:nameid-format:persistent	The NameID format requested
uid	urn:oasis:names:tc:SAML:attribute:subject-id	See Attributes available to Relying Parties#eduTEAMSIdentifier
email	urn:oid:0.9.2342.19200300.100.1.3	See Attributes available to Relying Parties#Emailaddress
first_name	urn:oid:2.5.4.42	See Attributes available to Relying Parties#GivenName
last_name	urn:oid:2.5.4.4	See Attributes available to Relying Parties#FamilyName
groups_attribute	urn:oid:1.3.6.1.4.1.5923.1.1.1.7	See Attributes available to Relying Parties#Groups

Basic integration

In the basic integration, all users from your VO will be able to authenticate via eduTEAMS and access the Gitlab service.

The "STEP nnn" comments refer directly to the OmniAuth guide (see the link at the start of this document).

Below is an example configuration:
/etc/gitlab/gitlab.rb

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# STEP 3
gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_block_auto_created_users'] = false

# STEP 4
gitlab_rails['omniauth_auto_link_saml_user'] = true

# STEP 6
gitlab_rails['omniauth_providers'] = [
   {
      name: 'saml',
      label: 'eduTEAMS',
      args: {
         assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
         idp_cert_fingerprint: '72:8A:6C:6B:63:35:3F:E0:BF:70:8D:41:0E:B7:02:CF:C5:86:53:24',
         idp_sso_target_url: 'https://proxy.eduteams.org/saml2sp/sso/redirect',
         issuer: 'https://gitlab.example.com',
         name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
         uid: ["urn:oasis:names:tc:SAML:attribute:subject-id"],
         email: ["urn:oid:0.9.2342.19200300.100.1.3",],
         first_name: ["urn:oid:2.5.4.42"],
         last_name: ["urn:oid:2.5.4.4"]
      },
      groups_attribute: 'urn:oid:1.3.6.1.4.1.5923.1.1.1.7',
      required_groups: [],
      admin_groups: [],
      audit_groups: []
   }
]

Advanced integration

The SAML login in Gitlab includes support for limiting access to specific groups from your VO. You can control which groups can access the Gitlab instance using the required_groups configuration option. When required_groups is not set or it is empty, anyone with proper authentication will be able to use the service.

It is also possible to automatically identify whether a user should be considered an external user based on the user’s group membership in your VO in eduTEAMS This feature does not allow you to automatically add users to GitLab Groups, it simply allows you to mark users as External if they are members of certain groups of users. You can control the users of which groups will be marked as External using the the external_groups configuration option.

This setting works very similarly to the External Groups setting. The requirements are the same, your IdP needs to pass Group information to GitLab, you need to tell GitLab where to look for the groups in the SAML response, and which group should be considered admin groups

This setting also follows the requirements documented for the External Groups setting. GitLab uses the Group information provided by your IdP to determine if a user should be assigned the auditor role.

Below is an example configuration:
/etc/gitlab/gitlab.rb

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

# STEP 3
gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_block_auto_created_users'] = false

# STEP 4
gitlab_rails['omniauth_auto_link_saml_user'] = true

# STEP 6
gitlab_rails['omniauth_providers'] = [
   {
      name: 'saml',
      label: 'eduTEAMS',
      args: {
         assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
         idp_cert_fingerprint: '72:8A:6C:6B:63:35:3F:E0:BF:70:8D:41:0E:B7:02:CF:C5:86:53:24',
         idp_sso_target_url: 'https://proxy.eduteams.org/saml2sp/sso/redirect',
         issuer: 'https://example.gitlab.com',
         name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
         uid: ["urn:oasis:names:tc:SAML:attribute:subject-id"],
         email: ["urn:oid:0.9.2342.19200300.100.1.3",],
         first_name: ["urn:oid:2.5.4.42"],
         last_name: ["urn:oid:2.5.4.4"]
      },

             # STEP(s) "Required Groups", "Admin Groups", "Auditor Groups"
      groups_attribute: 'urn:oid:1.3.6.1.4.1.5923.1.1.1.7',
      # Only the following groups in the Test_VO will be able to access this Gitlab instance:
      #
      # - Developers
      # - Admins:Gitlab
      # - Admins:Gitlab:Auditors
      required_groups: [
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Developers#eduteams.org',
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Developers#eduteams.org',
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Admins:Gitlab#eduteams.org',
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Admin:Gitlab:Auditors#eduteams.org',
      ],
      # Users from the following groups in the Test_VO will access this Gitlab instance as admins
      #
      # - Admins:Gitlab:
      admin_groups: [
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Admins:Gitlab#eduteams.org',
      ],
      # Users from the following groups in the Test_VO will access this Gitlab instance as auditors:
      #
      # - Admins:Gitlab:Auditors
      audit_groups: [
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Admins:Gitlab:Auditors#eduteams.org',
      ],
      # Users from the following gorup in the Test_VO will access the Gitlab instance external users
      #
      # - Guests
      # - Contractors
      external_groups: [
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Guests#eduteams.org',
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Conractors#eduteams.org',

             ],
      }
   }
]

Next Steps

Check the SAML metadata URL of the Gitlab instance at https://gitlab.example.com/users/auth/saml/metadata (replace gitlab.example.com with the domain of your Gitlab instance). You should should something like the following:
Gitlab SAML Metadata

1
2
3
4
5
6
7
8
9
10
11
12
13
14

<?xml version='1.0' encoding='UTF-8'?>
<md:EntityDescriptor ID="_9edb3dae-0919-40ff-b7c0-bffc63ba032b" entityID="https://gitlab.example.com/" xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
    <md:SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://gitlab.example.com/users/auth/saml/callback" index="0" isDefault="true" />
        <md:AttributeConsumingService index="1" isDefault="true">
            <md:ServiceName xml:lang="en">Required attributes</md:ServiceName>
            <md:RequestedAttribute FriendlyName="Email address" Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false" />
            <md:RequestedAttribute FriendlyName="Full name" Name="name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false" />
            <md:RequestedAttribute FriendlyName="Given name" Name="first_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false" />
            <md:RequestedAttribute FriendlyName="Family name" Name="last_name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic" isRequired="false" />
        </md:AttributeConsumingService>
    </md:SPSSODescriptor>
</md:EntityDescriptor>

Congratulations, you have successfully configured your Gitlab instance for eduTEAMS. Now you can proceed registering your following the steps described in Registering services on the eduTEAMS Service

Page tree

Versions Compared

Old Version 16

New Version 17

Key

Basic integration

Advanced integration

Next Steps

Page tree

Page History

Versions Compared

Old Version 16

New Version 17

Key

Basic integration

Advanced integration

Next Steps