Single-Sign-On into a local Gitlab installation using Admidio as a SAML 2.0 Identity Provider [Admidio-Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Single-Sign-On into a local Gitlab installation using Admidio as a SAML 2.0 Identity Provider ======

Starting with version 5.0, Admidio can be used by other applications to authenticate users against Admidios user base. These instructions will guide you through the process of connecting a local Gitlab installation to Admidio to use Admidio's login. For general instructions, and other apps, please visit the [[en:2.0:single_sign_on|general Single-Sign-On overview page]].

===== Prerequisites =====

Throughout the document we will assume you have both Admidio and Gitlab already set up properly at https://admidio.local/ and https://gitlab.local/. Please modify these URLs to your actual installation.
 
As a first step, one needs to **configure Admidio to act as an SAML 2.0 Identity Provider** (IdP). This has to be done once and is not specific to any client. Please follow this guide: [[en:2.0:single_sign_on|#a_basic_setup_for_admidio_as_a_saml_id_provider]]
{{ :en:2.0:sso:sso_saml_01-05_setup_admidio_preferences.png?direct&600 |}}

Basically, one (1) needs to **create a cryptographic key** to sign message and **choose a unique EntityID**.
The page preferences https://admidio.local/adm_program/modules/preferences.php?panel=sso also provides the link to the metadata xml, and the individual settings in case a client does not support auto-configuration via metadata.

===== TL;DR; - Quick Overview =====

Setting up a client (SAML "Service Provider" - short SP) to use Admidio's user accounts for logging in consists of two steps. If both the IdP (Admidio in our case) and the SP (Gitlab in this document) support metadata loading, the setup is very straightforward and easy. Otherwise, one has to copy URLs manually to the client, but Admidio already provides these in a single place, so this situation is not as bad, either.

  * At the **Service Provider (SP)** - Gitlab in our case - **install the extension** to support SAML login.
  * Configure it either with Admidio's link to the **metadata file**, or enter the EntityID, the Single-Sign-On Endpoint, the SLO Endpoint and the public certificate manually (Admidio provides a simple table to copy these values from).
  * Choose whether sent messages **should be signed and/or encrypted** (these features require an additional private key and certificate for the SP!), and whether received messages are checked for signatures or encryption is expected. 
  * In **Admidio**, **create a new SAML client**. If the SP provides a **metadata URL**, paste it and let Admidio automatically load the configuration from the SP. One can also manually paste these settings.
    * Choose an easily understood **label for the client** (only used in Admidio's list of clients, but has no technical use)
    * Enter the **ClientID from the SP**, as well as the ACS URL and the SLO response URL. These values must be provided by the client.
  * In Admidio, also choose whether sent messages should be **signed or encrypted**. The crypto key generated in the general SAML setup will be used.
  * Optionally select which **profile fields should be mapped** to SAML attributes and sent to the client, and configure which **group memberships** should be transmitted.

===== Gitlab-specific instructions =====

==== Configuring the Service Provider (Gitlab) ====

Gitlab does not provide a graphic config interface to set up SAML. However, it is easy to set up SAML in the config file (gitlab.rb) as described in https://docs.gitlab.com/17.10/integration/saml/. 

An example would be as follows. The URLs and the certificate can again be copied from Admidios SSO preferences page.
<code>
gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml', 'gitlab']
gitlab_rails['omniauth_block_auto_created_users'] = false 
gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml' # don't show gitlabs login screen at all
gitlab_rails['omniauth_auto_link_saml_user'] = true
gitlab_rails['omniauth_providers'] = [
  { "name" => "gitlab", ...},
  {
    "name" => "saml",
    "label" => "Admidio SAML SSO",
    "groups_attribute" => "groups",
    "admin_groups" => ["admin"],
    "args" => {
      "assertion_consumer_service_url" => "https://gitlab.open-tools.net/users/auth/saml/callback",
      "sp_entity_id" => "https://gitlab.open-tools.net",
      "idp_cert" => "-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----",
      "idp_sso_service_url" => "https://admidio.demo.open-tools.net/adm_program/modules/sso/index.php/saml/sso",
      "idp_slo_service_url" => "https://admidio.demo.open-tools.net/adm_program/modules/sso/index.php/saml/slo",
      "issuer" => "https://gitlab.open-tools.net",
      "attribute_statements" => { "email" => ['email'], "nickname" => ['username'] },
      "name_identifier_format" => "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
      "uid_attribute" => 'username'
    }
  }
]
</code>

Gitlab also supports encryption, which needs its own public + private key pair configured in gitlab. To generate keys, one can use Admidio's key administration (RSA 2048 key), export the Key (saved as PKCS#12 with file extension .p12 and a password) and then open the key file in any application that handles PKCS#12 Key and copy the private key and the public certificate in PEM format into the gitlab.rb file. The corresponding config keys are documented in the gitlab documentation mentioned above.

After editing gitlab.rb, one needs to reconfigure gitlab by running:

  sudo gitlab-ctl reconfigure

Gitlab will provide the SP metadata as an XML at the URL

  https://[GITLAB_SERVER_URL]/users/auth/saml/metadata
 

==== Setting up the Client (SP) in Admidio ====

Now, return to Admidio's SSO preferences page, go to the "Single-Sign-On Client Administration" (the button right above the "Save" button), and create a new client.
{{ :en:2.0:sso:sso_saml_03-00_admidio_saml_preferences.png?direct&400 |}}

Gitlab provides its SAML SP client settings as a metadata XML at the URL

  https://[GITLAB_SERVER_URL]/users/auth/saml/metadata
     
Paste that metadata URL into the corresponding input field at the top and click "Load Client Metadata". This should load all settings from Gitlab and pre-fill the following fields correctly. Only the Client Name needs to be entered. Choose any name to clearly identify the client in the list of SAML clients. There is no functionality depending on the name.

{{ :en:2.0:sso:sso_saml_05-01_gitlab_saml_idp1.png?direct&400 |}}

In addition to the Entity ID and URLs to connect SP and IdP and the certificate, which are configured automatically, one also needs to define the attribute and role mapping. The username is the most relevant and must match the uid_attribute configured in gitlab.rb. To use Admidio's group memberships as Gitlab groups, make sure to include the "Roles" field and provide the correct field name in Gitlab. Unfortunately, it seems that this features is only available in Gitlab EE (Enterprise Edition).

{{ :en:2.0:sso:sso_saml_05-02_gitlab_saml_idp2.png?direct&400 |}}


==== Setup completed, test Single-Sign-On ====

Admidio and Gitlab should now be set up to use Admidio for logging in to Gitlab. If you log out of Gitlab and try to log in again, you will be shown the Admidio login screen and then redirected back to Gitlab after successful login.

{{:en:2.0:sso:sso_saml_05-03_gitlab_login_selection.png?direct&200|}}
{{:en:2.0:sso:sso_saml_05-03a_gitlab_login_admidio.png?direct&300|}}
{{:en:2.0:sso:sso_saml_05-04_gitlab_saml_loggedin.png?direct&200|}}