Skip to content

Use Shibboleth as an authentication provider

DETAILS: Tier: Free, Premium, Ultimate Offering: Self-managed, GitLab Dedicated

NOTE: Use the GitLab SAML integration to integrate specific Shibboleth identity providers (IdPs). For Shibboleth federation support (Discovery Service), use this document.

To enable Shibboleth support in GitLab, use Apache instead of NGINX. Apache uses the mod_shib2 module for Shibboleth authentication, and can pass attributes as headers to the OmniAuth Shibboleth provider.

You can use the bundled NGINX provided in the Linux package to run a Shibboleth service provider on a different instance using a reverse proxy setup. However if you are not doing this, the bundled NGINX is difficult to configure.

To enable the Shibboleth OmniAuth provider, you must:

To enable Shibboleth:

  1. Protect the OmniAuth Shibboleth callback URL:

    <Location /users/auth/shibboleth/callback>
  AuthType shibboleth
  ShibRequestSetting requireSession 1
  ShibUseHeaders On
  require valid-user
</Location>

Alias /shibboleth-sp /usr/share/shibboleth
<Location /shibboleth-sp>
  Satisfy any
</Location>

<Location /Shibboleth.sso>
  SetHandler shib
</Location>

  2. Exclude Shibboleth URLs from rewriting. Add RewriteCond %{REQUEST_URI} !/Shibboleth.sso and RewriteCond %{REQUEST_URI} !/shibboleth-sp. An example configuration:

    # Apache equivalent of Nginx try files
RewriteEngine on
RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_URI} !/Shibboleth.sso
RewriteCond %{REQUEST_URI} !/shibboleth-sp
RewriteRule .* http://127.0.0.1:8080%{REQUEST_URI} [P,QSA]
RequestHeader set X_FORWARDED_PROTO 'https'

  3. Add Shibboleth to /etc/gitlab/gitlab.rb as an OmniAuth provider. User attributes are sent from the Apache reverse proxy to GitLab as headers with the names from the Shibboleth attribute mapping. Therefore the values of the args hash should be in the form of "HTTP_ATTRIBUTE". The keys in the hash are arguments to the OmniAuth::Strategies::Shibboleth class and are documented by the omniauth-shibboleth-redux gem (take care to note the version of the gem packaged with GitLab).

    The file should look like this:

    external_url 'https://gitlab.example.com'
gitlab_rails['internal_api_url'] = 'https://gitlab.example.com'

# disable Nginx
nginx['enable'] = false

gitlab_rails['omniauth_allow_single_sign_on'] = true
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_providers'] = [
  {
    "name"  => "shibboleth",
    "label" => "Text for Login Button",
    "args"  => {
        "shib_session_id_field"     => "HTTP_SHIB_SESSION_ID",
        "shib_application_id_field" => "HTTP_SHIB_APPLICATION_ID",
        "uid_field"                 => 'HTTP_EPPN',
        "name_field"                => 'HTTP_CN',
        "info_fields"               => { "email" => 'HTTP_MAIL'}
    }
  }
]

    If some of your users appear to be authenticated by Shibboleth and Apache, but GitLab rejects their account with a URI that contains "e-mail is invalid" then your Shibboleth Identity Provider or Attribute Authority may be asserting multiple email addresses. In this instance, consider setting the multi_values argument to first.

  4. For the changes to take effect:

    • For Linux package installations, reconfigure GitLab.
    • For self-compiled installations, restart GitLab.

On the sign in page, there should now be a Sign in with: Shibboleth icon below the regular sign-in form. Select the icon to begin the authentication process. You are redirected to the appropriate IdP server for your Shibboleth module configuration. If everything goes well, you are returned to GitLab and signed in.