Wir möchten gerne unsere Kunden, die in dem Webhosting Management System (WHMCS) verwaltet werden, einen SSO Zugriff auf unser Source Code Management System (GitLab) ermöglichen. Dabei ist unser WHMCS der OpenID Connect Server und GitLab der OpenID Connect Client.

Mit dem Release von GitLab 11.11 im Mai 2019, wurde endlich der Support für OpenID Connect (OAuth 2.0) integriert, was die Grundlage für die WHMCS Integration bildet.

Doch leider war das Vorhaben, die beiden Systeme mit einander zu verbinden, mit einigen Problemstellungen verbunden gewesen. Dank des Support von GitLab Inc, und dem Mitarbeiter "Stan Hu" konnten wir am Ende erfolgreich die Probleme lösen. Die Erfahrung bzw. die Schritte zur Einrichtung möchten wir in diesem Artikel mit euch teilen.

WHMCS Konfiguration

Client API Credentials erstellen

Im WHMCS AdminArea muss als erstes ein neues OpenID Connect Credentials Paar erstellt werden. Navigiere hierzu unter "Setup -> OpenID Connect" und erstelle neue Client API Credentials. Nach dem Klick  auf den Button "Generate Credentials" wird die ClientID und der ClientSecret erstellt. Diese Daten sollten sehr sensible behandelt werden.

Am Ende sieht das Ergebnis wie folgt aus:

Die Client ID wird später in der Gitlab.rb als identifier hinterlegt und den Client Secret als secret Wert hinterlegt.

Erste Hürde..., WHMCS Fit machen

Als erstes sind wir über einige Problem bei dem OpenID Connect Service von WHMCS gestoßen. OpenID hat ein sehr nützliches Feature, dass die Konfiguration des OpenID Server mittels Discovery Endpoint dem OpenID Client zur Verfügung stellt. Bei WHMCS ist dieser Discovery Endpoint unter der folgenden Adresse zur erreichen:

https://kundencenter.isp-serverfarm.de/oauth/openid-configuration.php

Hier ist auch schon das erste Problem, der OpenID OAuth 2.0 Standard sagt, die Discovery URL basiert immer auf der Issuer URL. Laut Beschreibung im WHMCS Manuel (siehe "iss" Wert im "ID token's payload") ist dies immer die WHMCS Url. Somit müssen diese beiden Werte unbedingt identisch sein. Nun hält sich mit dem Release v7.7.1 WHMCS bisher nicht an die Vorgabe, das die Discovery URL wie folgt auszusehen hat.

https://kundencenter.isp-serverfarm.de/.well-known/openid-configuration

Also mussten wir hier erstmal die Webserver Konfig erweitern, in unseren Fall im Plesk unter dem Punkt "Einstellungen für Apache & NGINX" einen Alias setzen, damit unter der URI "/.well-known/openid-configuration" der Apache mit der "/oauth/openid-configuration.php" antwortet.

Folgende Inhalt muss eingefügt werden, der Pfad zur "openid-configuration.php" muss natürlich entsprechend angepasst werden.

Alias "/.well-known/openid-configuration" "/var/www/vhosts/kundencenter.isp-serverfarm.de/httpdocs/kundencenter/oauth/openid-configuration_own.php"

Damit haben wir schon mal das Problem mit dem Discovery Service und der korrekten URL gelöst. Nun wird dem einen oder anderen aufgefallen sein, wir haben als Ziel die "openid-configuration_own.php" und nicht "openid-configuration.php" angegeben. Das ist kein Tippfehler, sondern der nächste Fix bei WHMCS. WHMCS hat es leider versäumt, die Informationen des Discovery Service sorgfältig zu pflegen. Der Wert "subject_types_supported"  ist leider null, was aber eine wichtige Voraussetzung für den Discovery Service ist.

{
    "issuer": "https:\/\/kundencenter.isp-serverfarm.de",
    "authorization_endpoint": "https:\/\/kundencenter.isp-serverfarm.de\/oauth\/authorize.php",
    "token_endpoint": "https:\/\/kundencenter.isp-serverfarm.de\/oauth\/token.php",
    "userinfo_endpoint": "https:\/\/kundencenter.isp-serverfarm.de\/oauth\/userinfo.php",
    "jwks_uri": "https:\/\/kundencenter.isp-serverfarm.de\/oauth\/certs.php",
    "response_types_supported": null,
    "subject_types_supported": [
        "public"
    ],
    "id_token_signing_alg_values_supported": [
        "RS256"
    ],
    "scopes_supported": [
        "openid",
        "email",
        "profile"
    ],
    "claims_supported": [
        "iss",
        "aud",
        "exp",
        "sub"
    ]
}

Also müssen wir hier eingreifen und diesen Fehler mit einem Workaround umgehen, bis WHMCS den Bug behoben hat. Daher erstellen wir im Ordner "oauth" parallel zu der "openid-configuration.php" eine  zusätzliche Datei "openid-configuration_own.php" mit dem folgenden Inhalt:

<?php
header('Content-Type: application/json');
$json_source = file_get_contents("https://kundencenter.isp-serverfarm.de/oauth/openid-configuration.php");
$json_array = json_decode($json_source, true);
$json_array['response_types_supported'] = ["code", "access_token", "id_token"];
echo json_encode($json_array, JSON_PRETTY_PRINT);
?>

Mit der neuen Datei, holen wir uns den Output der Original Ausgabe und erweitern die Ausgabe um die benötigten Werte. Damit sieht die Ausgabe unserer selbstgebauten Discovery URL (https://kundencenter.isp-serverfarm.de/.well-known/openid-configuration) wie folgt aus:

{
    "issuer": "https:\/\/kundencenter.isp-serverfarm.de",
    "authorization_endpoint": "https:\/\/kundencenter.isp-serverfarm.de\/oauth\/authorize.php",
    "token_endpoint": "https:\/\/kundencenter.isp-serverfarm.de\/oauth\/token.php",
    "userinfo_endpoint": "https:\/\/kundencenter.isp-serverfarm.de\/oauth\/userinfo.php",
    "jwks_uri": "https:\/\/kundencenter.isp-serverfarm.de\/oauth\/certs.php",
    "response_types_supported": [
        "code",
        "access_token",
        "id_token"
    ],
    "subject_types_supported": [
        "public"
    ],
    "id_token_signing_alg_values_supported": [
        "RS256"
    ],
    "scopes_supported": [
        "openid",
        "email",
        "profile"
    ],
    "claims_supported": [
        "iss",
        "aud",
        "exp",
        "sub"
    ]
}

Zum Schluss kommt noch der letzte Fix für das WHMCS System. Leider werden in einigen Situationen die HTTP Basic Authentication nicht ins PHP weitergegeben. Daher müssen wir die .htaccess des WHMCS um den folgenden Inhalt erweitern:

# Make Bearer Auth-Header available to PHP Backend (needed for OAUTH2)
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]

Vielen Dank an Stan Hu für den erlösenden Tipp an dieser Stelle.

Omnibus GitLab.rb Konfiguration erweitern

Wir konzentrieren uns auf die Omnibus Konfiguration von GitLab, hier gibt es in der Datei "/etc/gitlab/gitlab.rb" folgenden Bereich, den wir entsprechend anpassen müssen.

### OmniAuth Settings
###! Docs: https://docs.gitlab.com/ce/integration/omniauth.html
gitlab_rails['omniauth_enabled'] = true
# gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
# gitlab_rails['omniauth_sync_email_from_provider'] = 'saml'
# gitlab_rails['omniauth_sync_profile_from_provider'] = ['twitter', 'google_oauth2', "github", "gitlab", "facebook"]
# gitlab_rails['omniauth_sync_profile_attributes'] = ['name', 'email', 'location']
# gitlab_rails['omniauth_auto_sign_in_with_provider'] = 'saml'
# gitlab_rails['omniauth_block_auto_created_users'] = false
# gitlab_rails['omniauth_auto_link_ldap_user'] = false
# gitlab_rails['omniauth_auto_link_saml_user'] = false
# gitlab_rails['omniauth_external_providers'] = ['twitter', 'google_oauth2']
gitlab_rails['omniauth_providers'] = [
   { 'name' => 'openid_connect',
     'label' => 'ISP-Serverfarm.de',
     'args' => {
       'name' => 'openid_connect',
       'scope' => ['openid','profile', 'email'],
       'response_type' => 'code',
       'issuer' => 'https://kundencenter.isp-serverfarm.de',
       'discovery' => true,
       'client_auth_method' => 'query',
       'client_options' => {
         'identifier' => 'WHMCS_Client_ID',
         'secret' => 'WHMCS_Client_Secret',
         'redirect_uri' => 'https://git.isp-serverfarm.de/users/auth/openid_connect/callback'
       }
     }
   }
]

Hier ist der Issuer Wert unbedingt identisch mit der WHMCS System URL identisch zu definieren. Mit dem Wert "label" wird der Name für den SSO Button definiert. Alle weiteren Werte und deren Bedeutung kann in der GitLab Dokumentation nachgelesen werden.

Nach dem die Konfiguration gespeichert wurde, muss der GitLab Konfiguration Wizard ausgeführt und anschließend die GitLab Dienste einmal neugestartet werden.

root@git:~# gitlab-ctl reconfgure && gitlab-ctl restart

Anschließend ist auf der Loginseite von GitLab der SSO Button zu sehen. 

Mit einigen Einstellungen in den GitLab OmniAuth kann das Verhalten der OpenID Integration mit WHMCS noch verfeinert werden.