NetID authentication in GitLab

For educational purposes a Gitlab server has been installed where students can learn how to use Git and Gitlab. To access the server students are required to authenticate with their NetID. This document describes how to setup this authentication using both the TU Delft LDAP server and the AD server.

At first GitLab was configured to authenticate the NetID against the TU Delft LDAP server mds.tudelft.nl. Although this worked fine it didn’t allow for fine-grained authorization inside GitLab. The LDAP server would only provide basic user information (name, e-mail, etc. etc.) and not group information. The group information can be used to authorize only certain users to GitLab groups and thereby allow for setting up GitLab for different courses or groups within courses.

The group information however is available when authenticating against the TU Delft AD server tudelft.net. This allows for authorization of groups managed for instance in UMRA. After reconfiguring GitLab the server now authenticate using the AD.

The setup for both methods is described below.

Setting up LDAP

The TU Delft LDAP administrator preferres to log all LDAP queries with a known user account. For this a proxy-account was requested via servicepunttnw@tudelft.nl. The connection from the server is checked with the following command:

# make sure ldap-utils is installed, otherwise:
$ sudo apt install ldap-utils
$ ldapsearch -ZZ -h mds.tudelft.nl -D 'cn=<proxyaccount>,ou=proxyusers,ou=accessmgmt,o=config' -b "ou=people,o=tudelft" -W "(&(objectclass=*)(uid=<netid>))"

Note

Fill in the proxy-account name for <proxyaccount> and your own NetID for <netid>

Note

The -W argument will ask for the proxy-account password. You can do a query without password but not all available information will be shown.

GitLab can then be configured to use LDAP for authentication. This GitLab server is installed with apt following these instructions https://about.gitlab.com/install/#ubuntu:

$ curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
$ sudo EXTERNAL_URL="https://gitlab-imphys.tudelft.nl" apt install gitlab-ce

The LDAP configuration was added to the config file /etc/gitlab/gitlab.rb following these instructions https://docs.gitlab.com/ce/administration/auth/ldap/:

### LDAP Settings
###! Docs: https://docs.gitlab.com/omnibus/settings/ldap.html
###! **Be careful not to break the indentation in the ldap_servers block. It is
###!   in yaml format and the spaces must be retained. Using tabs will not work.**

gitlab_rails['ldap_enabled'] = true
gitlab_rails['prevent_ldap_sign_in'] = false

###! **remember to close this block with 'EOS' below**
gitlab_rails['ldap_servers'] = YAML.load <<-'EOS'
  main: # 'main' is the GitLab 'provider ID' of this LDAP server
    label: 'NetID'
    host: 'mds.tudelft.nl'
    port: 636
    uid: 'uid'
    method: 'ssl'
    bind_dn: 'cn=<proxyaccount>,ou=proxyusers,ou=accessmgmt,o=config'
    password: '<SECRET>'
    active_directory: false
    allow_username_or_email_login: false
    block_auto_created_users: true
    base: 'ou=people,o=tudelft'
    user_filter: ''
EOS

See the line starting with bind_dn for the authentication to LDAP with the proxy-account. Also note the base line which tells LDAP the starting point for LDAP queries.

Particularly note the setting of block_auto_created_users to true. This will allow the authentication of the user in GitLab but will set the block field in the created account. Only after the GitLab administrator unblocks this account the user cannot create anything on the server. This setting is turned on as a safe-guard to missusage of the server.

Finally the server was reconfigured and checked:

$ sudo gitlab-ctl reconfigure
$ sudo gitlab-rake gitlab:ldap:check[10]
Checking LDAP ...

LDAP: ... Server: ldapmain
LDAP authentication... Success
LDAP users with access to your GitLab server (only showing the first 10 results)
    DN: cn=<SNIP>
    <SNIP>
    DN: cn=<SNIP>

Checking LDAP ... Finished

The gitlab-rake command will return the first 10 results of the LDAP query.

As a result the GitLab login-screen now shows the new LDAP authentication method:

Setting up AD

The configuration for AD is very similar to LDAP. The AD queries must be done with a valid user-account. For this a sa-account was requested via servicepunttnw@tudelft.nl. Again access from the server to AD is checked, this time also the query of the groups was checked:

$ ldapsearch -h tudelft.net -D "<sa-account>@tudelft.net" -W -b "dc=tudelft,dc=net" "(uid=<netid>)"
$ ldapsearch -h tudelft.net -D "<sa-account>@tudelft.net" -W -b "dc=tudelft,dc=net" "(uid=<netid>)" "memberOf"

Note

Fill in the sa-account name for <sa-account> and your own NetID for <netid>

Info

Note in the second line the "(uid=<netid>)" "memberOf" part. The part between parentheses is the filter. The second part is the requested attribute. For more information see for instance https://devconnected.com/how-to-search-ldap-using-ldapsearch-examples/

Add the following lines to the GitLab configuration file /etc/gitlab/gitlab.rb

### LDAP Settings
###! Docs: https://docs.gitlab.com/omnibus/settings/ldap.html
###! **Be careful not to break the indentation in the ldap_servers block. It is
###!   in yaml format and the spaces must be retained. Using tabs will not work.**

gitlab_rails['ldap_enabled'] = true
gitlab_rails['prevent_ldap_sign_in'] = false

###! **remember to close this block with 'EOS' below**
gitlab_rails['ldap_servers'] = YAML.load <<-'EOS'
  main: # 'secondary' is the GitLab 'provider ID' of second LDAP server
    label: 'NetID'
    host: 'tudelft.net'
    port: 389
    uid: 'sAMAccountName'
    bind_dn: '<sa-account>@tudelft.net'
    password: '<SECRET>'
    encryption: 'plain' # "start_tls" or "simple_tls" or "plain"
    verify_certificates: true
    smartcard_auth: false
    active_directory: true
    allow_username_or_email_login: false
    lowercase_usernames: false
    block_auto_created_users: false
    base: 'OU=MDS,dc=tudelft,dc=net'
    user_filter: ''
    ## EE only
    group_base: ''
    admin_group: ''
    sync_ssh_keys: false
EOS

As before the server is reconfigured and tested:

$ sudo gitlab-ctl reconfigure
$ sudo gitlab-rake gitlab:ldap:check[10]
Checking LDAP ...

LDAP: ... Server: ldapmain
LDAP authentication... Success
LDAP users with access to your GitLab server (only showing the first 10 results)
    DN: cn=<SNIP>
    <SNIP>
    DN: cn=<SNIP>

Checking LDAP ... Finished

see above for the expected output of gitlab-rake

also see above for an image of the expected login-screen of GitLab

That’s it. Have fun!