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

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

TL;DR

Keycloakはオープンソースの統合ID管理ツールです。OpenID ConnectやSAMLによる認証を提供しています。（こちらの記事が参考になります）
GitLabはオープンソースのソースコード管理ツールです。OmniAuth IntegrationでソーシャルアカウントやSAMLによるSSOに対応しています。
KeycloakとGitLabの連携にはSAMLを利用します。

Keycloakの設定

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

Client ID: https://gitlab.example.com *1
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の設定にあたっては下記が参考になります。

qiita.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.com や keycloak.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