Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


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 OIDC 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.

NOTE: The "STEP nnn" comments refer directly to the OmniAuth guide  https://docs.gitlab.com/13.0/ee/integration/saml.html.


Code Block
languagepy
title/etc/gitlab/gitlab.rb
linenumberstrue
# 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_         attribute_service_name: "eduTEAMS Test Gitlab",
         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

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.

Configuration Option

Value

Description

issuer

(example) https://gitlab.example.com

A unique name identifying the gitlab application to the proxyidp_sso_target_urlhttps://proxy.eduteams.org/saml2sp/sso/redirect ??This is the eduTEAMS endpoint supporting the HTTP-Redirect SAML 2.0 Bindingidp_cert_fingerprint72:8A:6C:6B:63:35:3F:E0:BF:70:8D:41:0E:B7:02:CF:C5:86:53:24This is the SHA1 fingerprint of the signing certificate used by the eduTEAMS SAML frontendname_identifier_format
         uid_attribute: 'urn:oid:1.3.6.1.4.1.5923.1.1.1.13',
    
	     request_attributes: [
	         {
		          name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
		          name: "urn:oid:0.9.2342.19200300.100.1.3",
			      is_required: "true",
			      friendly_name: "mail"
	          },
		      {
			      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
		          name: "urn:oid:2.5.4.3",
			      is_required: "true",
			      friendly_name: "cn"
		      },
		      {
			      name_format: "urn:oasis:names:tc:SAML:2.0:
nameid
attrname-format:
persistentThe NameID format requesteduidurn:oasis:names:tc:SAML:attribute:subject-idSee Attributes available to Relying Parties#eduTEAMSIdentifieremailurn:oid:0.9.2342.19200300.100.1.3See Attributes available to Relying Parties#Emailaddressfirst_name
uri",
		          name: "urn:oid:2.5.4.42
See Attributes available to Relying Parties#GivenNamelast_nameurn:oid:2.5.4.4See Attributes available to Relying Parties#FamilyNamegroups_attributeurn:oid:1.3.6.1.4.1.5923.1.1.1.7See 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.orgYou should replace Test_VO with your VO id ?

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.

Code Block
linenumberstrue
      # 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'",
			      is_required: "true",
			      friendly_name: "givenName"
		      },
		      {
			      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
		          name: "urn:oid:2.5.4.4",
			      is_required: "true",
			      friendly_name: "sn"
		      },
		      {
			      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
		          name: "urn:oid:1.3.6.1.4.1.5923.1.1.1.7",
			      is_required: "true",
			      friendly_name: "eduPersonEntitlement"
		      },
		      {
			      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
		          name: "urn:oid:1.3.6.1.4.1.5923.1.1.1.13",
			      is_required: "true",
			      friendly_name: "eduPersonUniqueId"
		      },
              {
			      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
		          name: "urn:oid:1.3.6.1.4.1.5923.1.1.1.6",
			      is_required: "true",
			      friendly_name: "eduPersonPrincipalName"
		      }
          ],
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Developers#eduteams.org',
attribute_statements: {
           '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',
      ],
   name: ["urn:oid:2.5.4.3"],
          # Users from the following groups in the Test_VO will access this Gitlab instance as admins uid: ["urn:oid:1.3.6.1.4.1.5923.1.1.1.13"],
              nickname: ["urn:oid:1.3.6.1.4.1.5923.1.1.1.6"],
      #
      # - Admins:Gitlab: email: ["urn:oid:0.9.2342.19200300.100.1.3"],
      admin_groups: [
          'first_name: ["urn:geantoid:eduteams.org:service:eduteams:group:Test_VO:Admins:Gitlab#eduteams.org'2.5.4.42"],
      ],
      # Users from the following groups in the Test_VO will access this Gitlab instance as auditors:last_name: ["urn:oid:2.5.4.4"]
          },
      #
    private_key:  # - Admins:Gitlab:Auditors
'-----BEGIN PRIVATE KEY-----
         audit_groups: [
 ...
          -----END PRIVATE 'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Admins:Gitlab:Auditors#eduteams.org',KEY-----'
      ],
    certificate:  # Users from the following gorup in the Test_VO will access the Gitlab instance external users'-----BEGIN CERTIFICATE-----
          ...
      #
      # - Guests-----END CERTIFICATE-----'
      # - Contractors
  security: {
   external_groups: [
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Guests#eduteams.org'authn_requests_signed: true,
          'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Conractors#eduteams.org',

    want_assertions_signed: false,
             ]

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
languagexml
linenumberstrue
<?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">
 want_assertions_encrypted: false,
              embed_sign: true,
              <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:persistent</md:NameIDFormat>
metadata_signed: false,
              <mdsignature_method: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" /> 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
        <md:AttributeConsumingService index="1" isDefault="true">
            <md:ServiceName xml:lang="en">Required attributes</md:ServiceName>digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
          }
  <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" /> },
      groups_attribute: 'urn:oid:1.3.6.1.4.1.5923.1.1.1.7',
      required_groups: [],
      admin_groups: [],
      audit_groups: []
   }
]


The URL of your Gitlab instance is 

2. In order to edit this part of the config file correctly, you should have the values for the configuration options defined and known.


Also you need to generate a private / public key pair that will be used by the SAML SP to digitally sign and optionally decrypt SAML Assertsions. You can generate a key pair with the following command from your terminal:


Code Block
languagebash
openssl req -x509 -nodes -newkey rsa:2048 -keyout /dev/stdout \
        -days 
<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
  • 3650 -subj "/CN=SAML Certificate"


    Note: The private and the public key are going to be printed in the standard output.


    Configuration Option

    Value

    Description

    attribute_service_name:(example) eduTEAMS Test GitlabThe name of your service. This name will be visible to the end users
    assertion_consumer_service_url(example)https://gitlab.example.com/users/auth/saml/callbackThe HTTPS endpoint of your GitLab instance
    idp_cert_fingerprint72:8A:6C:6B:63:35:3F:E0:BF:70:8D:41:0E:B7:02:CF:C5:86:53:24This is the SHA1 fingerprint of the signing certificate used by the eduTEAMS SAML frontend
    idp_sso_target_urlhttps://proxy.eduteams.org/saml2sp/sso/redirect This is the eduTEAMS endpoint supporting the HTTP-Redirect SAML 2.0 Binding
    issuer

    (example)

    /

     

  • 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

    A unique name identifying the gitlab application to the proxy. This should be changed to the toplevel domain of your Gitlab instance
    name_identifier_formaturn:oasis:names:tc:SAML:2.0:nameid-format:persistentThe NameID format requested
    uid_attributeurn:oid:1.3.6.1.4.1.5923.1.1.1.13By default Gitlab uses the NameID attribute as the unique identifier. With this configuration option we configure gitlab to use urn:oid:1.3.6.1.4.1.5923.1.1.1.13 (eduPersonUniqueId)
    request_attributes


    Code Block
    languageruby
    linenumberstrue
    [
    {
      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
      name: "urn:oid:0.9.2342.19200300.100.1.3",
      is_required: "true",
      friendly_name: "mail"
    },
    {
      name_format: "
    issuer

    (example) https://gitlab.example.com

    A unique name identifying the gitlab application to the proxyidp_sso_target_url

    https://proxy.acc.eduteams.org/saml2sp/sso/redirect

    This is the eduTEAMS endpoint supporting the HTTP-Redirect SAML 2.0 Bindingidp_cert_fingerprint72:8A:6C:6B:63:35:3F:E0:BF:70:8D:41:0E:B7:02:CF:C5:86:53:24This is the SHA1 fingerprint of the signing certificate used by the eduTEAMS SAML frontendname_identifier_format
    urn:oasis:names:tc:SAML:2.0:
    nameid-format:persistentThe NameID format requesteduid
    attrname-format:uri",
      name: "urn:oid:2.5.4.3",
      is_required: "true",
      friendly_name: "cn"
    },
    {
      name_format: "urn:oasis:names:tc:SAML:
    attribute
    2.0:
    subject-idSee Attributes available to Relying Parties#eduTEAMSIdentifieremailurn:oid:0.9.2342.19200300.100.1.3See Attributes available to Relying Parties#Emailaddressfirst_name
    attrname-format:uri",
      name: "urn:oid:2.5.4.42
    See Attributes available to Relying Parties#GivenNamelast_nameurn:oid:2.5.4.4See Attributes available to Relying Parties#FamilyNamegroups_attributeurn:oid:1.3.6.1.4.1.5923.1.1.1.7See 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",],
             
    ",
      is_required: "true",
      friendly_name: "givenName"
    },
    {
      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
      name: "urn:oid:2.5.4.4",
      is_required: "true",
      friendly_name: "sn"
    },
    {
      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
      name: "urn:oid:1.3.6.1.4.1.5923.1.1.1.7",
      is_required: "true",
      friendly_name: "eduPersonEntitlement"
    },
    {
      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
      name: "urn:oid:1.3.6.1.4.1.5923.1.1.1.13",
      is_required: "true",
      friendly_name: "eduPersonUniqueId"
    },
    {
      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
      name: "urn:oid:1.3.6.1.4.1.5923.1.1.1.6",
      is_required: "true",
      friendly_name: "eduPersonPrincipalName"
    }
    ]



    This option controls the SAML attributes that are going to be include in the SAML of metadata for Gitlab.


    The attributes required are:

    • mail
    • cn (Full name)
    • givenName (First name)
    • sn (Surname)
    • eduPersonEntitlement (the groups the user is assigned to)
    • eduPersonUniqueID (the unique identifier of the user)
    • eduPersonPrincipalName (the username of the user)

    For more information on the attributes that are available to services from eduTEAMS, you can read Attributes available to Relying Parties

    attribute_statements


    Code Block
    languageruby
    {
      name: ["urn:oid:2.5.4.3"],
      uid: ["urn:oid:1.3.6.1.4.1.5923.1.1.1.13"],
      nickname: ["urn:oid:1.3.6.1.4.1.5923.1.1.1.6"],
      email: ["urn:oid:0.9.2342.19200300.100.1.3"],
      first_name: 
    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: [


    This configure options controls the mapping from the SAML attributes to the Gitlab internal attributes
    private_key


    Code Block
    -----BEGIN PRIVATE KEY-----
    
    ...
    
    -----END PRIVATE KEY-----


    This is the private key that is going to be used to sign the and optionally decrypt encrypted SAML assertions.


    Copy the private key that you generated in your terminal


    certificate


    Code Block
    -----BEGIN CERTIFICATE-----
    
    ...
    
    -----END CERTIFICATE-----


    This is the certificate that is going to be used to sign the and optionally decrypt encrypted SAML assertions.


    Copy the certificate that you generated in your terminal

    security


    Code Block
    languageruby
    {
      authn_requests_signed: true,
      want_assertions_signed: false,
      want_assertions_encrypted: false,
      embed_sign: true,
      metadata_signed: false,
      signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
      digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
    }


    This configuration option controls several aspects of the security configuration for the SP

    Full group definition:

    urn:geant:eduteams.org:service:eduteams:group:<VO_Name>:<Top_level group>[:<Sub_group_name>]#eduteams.org

    (examples) 

    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

    You should replace the <VO_Name> with your VO name to which you would like to connect the Gitlab service;

    You should replace the <Top_level group>:[<Sub_group_name>] with your group (and subgroup) name which should have access to the Gitlab service;


    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
    languagepy
    title/etc/gitlab/gitlab.rb
    linenumberstrue
     # 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: {
             attribute_service_name: "eduTEAMS Test Gitlab",
             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_attribute: 'urn:oid:1.3.6.1.4.1.5923.1.1.1.13',
        
    	     request_attributes: [
    	         {
    		          name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
    		          name: "urn:oid:0.9.2342.19200300.100.1.3",
    			      is_required: "true",
    			      friendly_name: "mail"
    	          },
    		      {
    			      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
    		          name: "urn:oid:2.5.4.3",
    			      is_required: "true",
    			      friendly_name: "cn"
    		      },
    		      {
    			      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
    		          name: "urn:oid:2.5.4.42",
    			      is_required: "true",
    			      friendly_name: "givenName"
    		      },
    		      {
    			      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
    		          name: "urn:oid:2.5.4.4",
    			      is_required: "true",
    			      friendly_name: "sn"
    		      },
    		      {
    			      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
    		          name: "urn:oid:1.3.6.1.4.1.5923.1.1.1.7",
    			      is_required: "true",
    			      friendly_name: "eduPersonEntitlement"
    		      },
    		      {
    			      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
    		          name: "urn:oid:1.3.6.1.4.1.5923.1.1.1.13",
    			      is_required: "true",
    			      friendly_name: "eduPersonUniqueId"
    		      },
                  {
    			      name_format: "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
    		          name: "urn:oid:1.3.6.1.4.1.5923.1.1.1.6",
    			      is_required: "true",
    			      friendly_name: "eduPersonPrincipalName"
    		      }
              ],
              attribute_statements: {
                  name: ["urn:oid:2.5.4.3"],
                  uid: ["urn:oid:1.3.6.1.4.1.5923.1.1.1.13"],
                  nickname: ["urn:oid:1.3.6.1.4.1.5923.1.1.1.6"],
                  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"]
              },
              private_key: '-----BEGIN PRIVATE KEY-----
              ...
              -----END PRIVATE KEY-----'
              certificate: '-----BEGIN CERTIFICATE-----
              ...
              -----END CERTIFICATE-----'
              security: {
                  authn_requests_signed: true,
                  want_assertions_signed: false,
                  want_assertions_encrypted: false,
                  embed_sign: true,
                  metadata_signed: false,
                  signature_method: 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',
                  digest_method: 'http://www.w3.org/2001/04/xmlenc#sha256',
              }
          },
    
          # 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:
    Developers#eduteams
    Gitlab:Auditors#eduteams.org',

              'urn:geant:eduteams.org:service:eduteams:group:Test_VO:Developers#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:
    Admins:Gitlab#eduteams
    Guests#eduteams.org',

    
              'urn:geant:eduteams.org:service:eduteams:group:Test_VO:
    Admin:Gitlab:Auditors#eduteams
    Conractors#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.  Once you edited the omniauth section of the /etc/gitlab/gitlab.rb file as above indicated, you need to reconfigure gitlab with the command:




    Code Block
    sudo gitlab-ctl reconfigure


    3. 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
    languagexml
    titleGitlab SAML Metadata
    linenumberstrue
    <?xml version='1.0' encoding='UTF-8'?>
    <md:EntityDescriptor ID="_44a6dfeb-7bc8-463c-8c4a-363bcdaebd8e" 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="true" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
            <md:KeyDescriptor use="signing">
                <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                    <ds:X509Data>
                        <ds:X509Certificate>MIICsjCCAZoCCQC+5DOdpjdhhDANBgkqhkiG9w0BAQsFADAbMRkwFwYDVQQDDBBTQU1MIENlcnRpZmljYXRlMB4XDTIwMTAwMzEyMzM1OVoXDTMwMTAwMTEyMzM1OVowGzEZMBcGA1UEAwwQU0FNTCBDZXJ0aWZpY2F0ZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAPn1WdKVdIxOAHNJWJgAxNldX3Vlrb0T18yXCRTiSZX2EDPFkVQDXFIi5NPVIgW3kxMyi28eR7kg1KnpYcPT4cZbHBaTIliJOrpkvUlXKUFuIHZuRsaFoHv0kDY/T3BUZul6jx6rnb8AgpHkBAeZludySwYzf5/DcqXaUVLekpZfUUEyrIe6dqFL/ehGzSXtGl6hWn8ms5lEcmlZeG01l2F/1FmpXaCwCSNo0QTIwAnlpZ6CvDsnZIzrOvvPOvKrgvmWKqU/vY5rB8eJSNodp6/gi1+r5TUV95UHGmg3bIe0Flo/SrYYsp9vp/f1IWlcaM7XjuvsGFMaj4CgVzCCRGsCAwEAATANBgkqhkiG9w0BAQsFAAOCAQEAASjSsy9TltbfbRvxp21mkxhj6LOx33yuYOmVODs170V+GeDId8bQTi+ddO+YmKHg18zzpz+EA69HVQozshtf7/5gB8dS1zknvs78xbLevrBZ7Fw8h8Q68je+3MOV/UYhHd1ViQ+S3Qdeph1RMwv7s9XsJGqCsxF5skrKef2VLqQAsKitNk0ao69H87aDrnSAb88v6kFeT08MZWTnw64jYj8jH2gaT33WkiAtzVUNJygIrVuqWX9GCZsQK6AehFnSr/jUUirSMms78rJM8JmPTygWrHveM8BC2QSsSyS9X4YEe/ah2YIfazioDUh8JRPgdbHMUdHwN/4+heqP1JyirA==</ds:X509Certificate>
                    </ds:X509Data>
                </ds:KeyInfo>
            </md:KeyDescriptor>
            <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

                 ],
          }
       }
    ]

    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
    users/auth/saml/callback" index="0" isDefault="true" />
            <md:AttributeConsumingService index="1" isDefault="true">
                <md:ServiceName xml:lang="en">eduTEAMS Test Gitlab Instance</md:ServiceName>
                <md:RequestedAttribute FriendlyName="mail" Name="urn:oid:0.9.2342.19200300.100.1.3" NameFormat="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
    :attrname-format:uri" isRequired="true" />
                <md:RequestedAttribute FriendlyName="cn" Name="urn:oid:2.5.4.3" NameFormat="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" 
    attrname-format:uri" isRequired="true" />
                <md:RequestedAttribute FriendlyName="givenName" Name="urn:oid:2.5.4.42" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" isRequired="true" />
                <md:RequestedAttribute FriendlyName="sn" Name="urn:oid:2.5.4.4" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:
    basic
    uri"
     
     isRequired="
    false
    true"
     />
                <md:RequestedAttribute 
     />
                <md:RequestedAttribute FriendlyName="
    Full name
    eduPersonEntitlement"
     
     Name="
    name" 
    urn:oid:1.3.6.1.4.1.5923.1.1.1.7" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:
    basic
    uri"
     
     isRequired="
    false" />
                <md:RequestedAttribute FriendlyName="Given name" Name="first_name" 
    true" />
                <md:RequestedAttribute FriendlyName="eduPersonUniqueId" Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.13" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:
    basic
    uri"
     
     isRequired="
    false
    true"
     />
                <md:RequestedAttribute 
     />
                <md:RequestedAttribute FriendlyName="
    Family name
    eduPersonPrincipalName"
     
     Name="
    last_name" 
    urn:oid:1.3.6.1.4.1.5923.1.1.1.6" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:
    basic
    uri"
     
     isRequired="
    false
    true"
     
     />

            
    
            </md:
    AttributeConsumingService>
        
    AttributeConsumingService>
        </md:
    SPSSODescriptor>
    SPSSODescriptor>
    </md:EntityDescriptor>



    4. Congratulations

    EntityDescriptor>

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