VI-SEEM AAI GitLab Integration

From VI-SEEM Wiki
Jump to: navigation, search

Introduction

This page describes how to integrate VI-SEEM AAI login support (as SAML Identity Provider - IdP) into GitLab source code repository acting as the Service Provider (SP), but also can be used for other applications using OmniAuth.

These steps apply to GitLab Omnibus installation, but can be used (with changes to file paths, etc) with other installations as well.

GitLab Settings

Before any changes to GitLab, one should visit VI-SEEM Login integration guide for Service Providers to get the the basic picture. Also useful reading are OmniAuth and SAML documentation from the GitLab Documentation.

Note: Versions before at least GitLab 8.12 have an old version of authentication library that can cause problems - please upgrade to current version of GitLab

After the SP has successfully exchanged the metadata with VI-SEEM AAI as described here there are some changes needed to configuration:

/etc/gitlab/gitlab.rb
...
gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = true
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_auto_link_saml_user'] = true

gitlab_rails['omniauth_providers'] = [
	{
	name: 'saml',
	args: {
			assertion_consumer_service_url: 'https://code.vi-seem.eu/users/auth/saml/callback',
			idp_cert_fingerprint: 'FA:88:E2:9C:62:A5:C1:2A:0D:39:A4:18:03:D6:5F:0D:9B:EE:DB:56',
			idp_sso_target_url: 'https://aai.vi-seem.eu/proxy/saml2/idp/SSOService.php',
			issuer: 'https://code.vi-seem.eu',
			name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:transient',
			},
	label: 'VI-SEEM Login'
	}
]
...

This setup configures VI-SEEM AAI as IdP in SAML OmniAuth provider so that the users are presented with VI-SEEM Login button on the login page. Upon clicking it, they will be transferred over to **aai.vi-seem.eu** where they can choose the way they log in after which they are returned back to GitLab already logged in.

This setup also links user accounts with the same email address regardless of whether they created the account manually or via AAI login. You can change this behaviour by altering the line gitlab_rails['omniauth_auto_link_saml_user'] = true to gitlab_rails['omniauth_auto_link_saml_user'] = false.

Troubleshooting

System Time

The thing that can cause many problems is the discrepancy between the clock at IdP and SP. One should configure NTP on the server if it's not already configured.

Just being redirected back to login page

If this happens, one should watch the log files, like this

tail -f /var/log/gitlab/gitlab-rails/production.log

And if there is a line

Can't verify CSRF token authenticity

in the log then it means that Cross-Site Request Forgery cannot be verified. One possible solution is to turn it off like this

/opt/gitlab/embedded/service/gitlab-rails/config/environments/production.rb
Rails.application.configure do
  # Settings specified here will take precedence over those in config/application.rb
  config.action_controller.allow_forgery_protection = false
...

But there can be better solutions depending on your concrete setup, please refer to GitLab SAML Documentation.