Use Shibboleth as an authentication provider
- Tier: Free, Premium, Ultimate
- Offering: GitLab Self-Managed, GitLab Dedicated
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:
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>
Exclude Shibboleth URLs from rewriting. Add
RewriteCond %{REQUEST_URI} !/Shibboleth.sso
andRewriteCond %{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'
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 theargs
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 theomniauth-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 tofirst
.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.
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support