Single-Sign-On into GitLab using Admidio as an OpenID 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 GitLab using Admidio as an OpenID 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 GitLab 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 OpenID Provider** (OP). This has to be done once and is not specific to GitLab. Please follow this guide: [[en:2.0:single_sign_on|#a_basic_setup_for_admidio_as_an_oidc_id_provider]]
{{ :en:2.0:sso:sso_oidc_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 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.

===== Quick Overview =====

Setting up a client (OpenID "Relying Party" - short RP) to use Admidio's user accounts for logging in consists of two steps: (1) The client (RP, GitLab in our case) needs to be set up with the data about the OpenID Provider (OP). Typically this is done via the metadata provided in the discovery URL of the provider. Since Admidio provides those URLs with copy buttons in the preferences screen, even the manual configuration is rather straigtforward. (2) Admidio needs to be told about the client. In particular, the entity ID and the redirect URL must be given, and a custom-generated (random) secret must be copied to the client configuration.

The concrete steps are:
  * GitLab needs to be configured in the ''config/gitlab.rb'' config file.
    * Copy the issuer URL (the base for all endpoints, including the discovery URL) into the 'issuer' setting
    * Choose which scopes (groups of profile fields) should be requested from Admidio ("openid" is required; If Admidio's groups/roles should be mapped to the client's groups, the "groups" scope is also required).
  * In **Admidio**, **create a new OpenID client**. 
    * Choose an easily understood **label for the client** (only used in Admidio's list of clients, but has no technical use)
    * Choose a good **ClientID** to uniquely identify the GitLab client (typically, use the base URL of your installation). 
    * Copy both the ClientID and the Client Secret from Admidios client config to the GitLab config file.
    * Enter the redirect URL of GitLab in Admidio: 'https://[[YOUR_GITLAB]]/users/auth/openid_connect/callback'.
  * Optionally select (both in Admidio and the RP) which **profile fields should be mapped** to OpenID claims (attributes) and sent to the client, and configure which **group memberships** should be transmitted.


===== GitLab-specific instructions =====

==== Configuring the Service Provider (GitLab) ====

OpenID Connect login in GitLab is provided out of the box without the need for additional extensions. Its configuration is done entirely in the ''config/gitlab.rb'' config file in the 'config/' directory of the GitLab installation.

There is a [[https://docs.gitlab.com/administration/auth/oidc/|good documentation provided by the GitLab team]], which is the basis for the example configuration shown here: https://docs.gitlab.com/administration/auth/oidc/.

  * Open the ''config/gitlab.rb'' configuration file of GitLab and append the following lines to the end of the file:
    * The ''issuer'' key is the base URL for the endpoints, without the endpoint names themselves. One has to copy over the OpenID Issuer from Admidio's OpenID preferences (it has a copy button). {{ :en:2.0:sso:sso_oidc_01-01_setup_admidio_endpoints.png?direct&600 |}}
    * The **Client ID** and **Client Secret** will later come from Admidio's client configuration.
    * The 'client_auth_method' should not be left out or left empty, because then basic http authenatication will be used, which does not allow colons in the cliend ID. So if one wants to the use installation URL as client ID, one must switch to anything else than 'basic'. GitLab's documentation uses "query".
    * If other login methods should be enabled, too, one can add more list entries to the ''gitlab_rails['omniauth_providers']'', and optionally include all single-sign-on methods to the 'omniauth_allow_single_sign_on' list.

<code php>
gitlab_rails['omniauth_enabled'] = true

gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']
gitlab_rails['omniauth_auto_link_user'] = true
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_sync_profile_attributes'] = true
gitlab_rails['omniauth_sync_profile_from_provider'] = ['saml', 'openid_connect']

gitlab_rails['omniauth_providers'] = [
  {
    name: "openid_connect",
    label: "Admidio via OpenID",
    icon: "https://www.admidio.org/images/favicon-16x16.png?v=2",
    groups_attribute: "roles",
    args: {
    #   name: "openid_connect",
      scope: ["openid","profile","email", "groups", "custom", "phone", "address"],
      response_type: "code",
      issuer: "https://admidio.local/modules/sso/index.php/oidc",
      discovery: true,
      client_auth_method: "query",
      uid_field: "username",
      send_scope_to_token_endpoint: "true",
      pkce: true,
      client_options: {
        identifier: "https://gitlab.local/",
        secret: "VMjNB7vFAeb1dmMSFpjcyz27i24Ytti7",
        redirect_uri: "https://gitlab.local/users/auth/openid_connect/callback"
      }
    }
  }
]
</code>

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

It is now a good idea to keep two browser windows open so one can easily select and copy the settings. Admidio even provides little "copy" buttons/icons to copy the various settings to the clipboard for easy pasting into GitLab's configuration.

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


  - The **Client Name** is the label of the client in Admidio's client list, it can be anything you like.
  - The **"Client ID"** and **"Client Secret"** in Admidio have to match exactly the **"clientID"** and **"clientsecret"** entries in GitLab's configuration. The ID is typically the client's URL, i.e. ''https://[YOUR_GITLAB]/''. The client secret is randomly generated and must be copied exactly to the GitLab configuration, as it will serve like a password. Admidio will create one and allow it to be copied to the client. Afterwards it is only stored as a hash in the database and can not be recovered any more. However, one can create a new Client Secret in Admidio and copy that to the client's configuration.
  - GitLab's redirect URL is the Special:PluggableAuthLogin page, i.e. ''https://[YOUR_INSTALLATION]/index.php/Special:PluggableAuthLogin''. Enter that URL in Admidio's client config.
  - Enter the **scopes** you used in GitLab's config and make sure that Admidio's config matches it. At least **openid must be included** (Admidio will implicitly add it). If groups/roles are supposed to be used for access permissions, the **"groups" scope** also must be included in both GitLab's and Admidio's scope setting and the roles included as an OpenID claim. (The groups mapping that Admidio offers is optional, one can also send all groups verbatim without mapping. This can be achieved by checking the checkbox below the mapping table in Admidio).


This is a typical configuration of the GitLab OpenID client in Admidio:

{{:en:2.0:sso:sso_oidc_gitlab_03_client.png?direct&450|}}{{:en:2.0:sso:sso_oidc_gitlab_04_client.png?direct&450|}}

The clientID and the client secret in the Admidio client page and GitLab's ''config/gitlab.rb'' have to match exactly. Similarly, the scopes should coincide, otherwise not all desired profile fields will be transmitted. To make use of the group mapping in GitLab (see the [[https://docs.gitlab.com/administration/auth/oidc/#configure-users-based-on-oidc-group-membership|Gitlab documentation for details]]), make sure to include the 'groups' scope in Admidio and GitLab, and map the 'Roles - roles' Profile Field to an OIDC claim.



==== 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 (or open a new incognito browser window) and try to log in again, the login form with have an additional button (with the label given in the config file) to initiate an OpenID login. If you click it, you will be shown the Admidio login screen (if you are not already logged in) and then redirected back to GitLab after successful login. 

{{:en:2.0:sso:sso_oidc_gitlab_07_loginform.png?direct&400|}}{{:en:2.0:sso:sso_oidc_gitlab_07a_admidio_loginform.png?direct&450|}}{{:en:2.0:sso:sso_oidc_gitlab_08_loginsuccess.png?direct&600|}}



==== Caveats and Things to Consider ====

  * GitLab allows group memberships based on OpenID claims only in the premium (i.e. paid) versions.
  * If an account with the same email address already exists, GitLab will offer to merge them (i.e. link the OpenID login to the existing user account) upon login or create a separate user for the OpenID access.