@int128

int128.hatenablog.com

KeycloakのSAML SSOでGitLabやMattermostにログインする

KeycloakとGitLabでSAML SSOを設定する方法を説明します。ユーザ管理をKeycloakで行いながら、GitLabやMattermostにSSOできるのでとても便利です。

TL;DR

Keycloakの設定

Keycloakで新しいClientを追加します。認証連携したいユーザがいるRealmで作業してください。

  • Client Protocol: saml
  • Client Signature Required: OFF
  • Root URL: https://gitlab.example.com
  • Valid Redirect URIs: https://gitlab.example.com/*

それから属性のマッピングを設定します。

SAML属性名 Keycloakのユーザプロパティ
email email
first_name firstName
last_name lastName
username username

SAML OmniAuth Providerの説明 によると groups 属性が含まれていたらGitLabグループとして認識されるようですが、ユーザを自動的にグループに追加してくれるわけではないので、あまり役に立たなさそうです。

デフォルトではRealmに存在するすべてのユーザがGitLabでログインできます。

Clientを作成したら、IdPの証明書を取得しておきます。InstallationタブでSAML Metadata IDPSSODescriptorを選択するとXMLが表示されるので、<dsig:X509Certificate> 要素に入っているBASE64文字列をメモしておきます。

なお、Clientの設定にあたっては下記が参考になります。

https://qiita.com/katakura__pro/items/1e65e0bde7fda75332a1qiita.com

GitLabの設定

/etc/gitlab/gitlab.rb でOmniAuthを設定します。DockerやKubernetesを利用している場合は GITLAB_OMNIBUS_CONFIG 環境変数で設定します。

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_block_auto_created_users'] = false
gitlab_rails['omniauth_auto_link_saml_user'] = true
gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    label: 'EXAMPLE LOGIN',  # ログインボタンのラベル。日本語は利用できないようです
    args: {
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
      idp_cert: '-----BEGIN CERTIFICATE-----
MII****
-----END CERTIFICATE-----',  # Keycloakで取得した証明書
      idp_sso_target_url: 'https://keycloak.example.com/auth/realms/YOUR_REALM/protocol/saml',
      issuer: 'https://gitlab.example.com',
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
      attribute_statements: { username: ['username'] }  # GitLabのユーザ名で使う属性を指定 (optional)
    }
  }
]

上記の gitlab.example.comkeycloak.example.com は実際のドメイン名に置き換えてください。また、IdPの証明書はKeycloakで取得したものを入れます。

デフォルトではメールアドレスの @ より前がGitLabのユーザ名になりますが、 attribute_statements を設定すると任意のSAML属性をユーザ名に指定できます(Use different SAML claim to set username? (#12841) · Issues · GitLab.org / GitLab Community Edition · GitLab)。上記では username 属性をユーザ名に割り当てています。

設定が完了したらGitLabを再起動します。ログイン画面で EXAMPLE LOGIN というボタンが表示されたら成功です。

うまくいかない場合は、KeycloakやGitLabのログを確認しましょう。

docs.gitlab.com

Mattermostの設定

MattermostでGitLab SSOを設定します。これにより、Mattermost→GitLab→KeycloakのSSOを実現できます。

https://docs.mattermost.com/deployment/sso-gitlab.html

KeycloakのusernameがそのままGitLabやMattermostのユーザ名(@int128)になるので、ユーザ管理の設計はよく考えた方がよいと思います。もちろん、Keycloakのマッピングを変更すれば別の属性をユーザ名にできます。

まとめ

  • KeycloakでSAML Clientを作成する。
  • GitLabでOmniAuth SAMLを設定する。
  • MattermostでGitLab SSOを設定する。

残念ながら、GitLabやMattermostからのSLO(シングルログアウト)は対応していないようです(Explore SAML Single Sign Out (#17344) · Issues · GitLab.org / GitLab Community Edition · GitLab)。