※ 2/21追記: 本記事は初のKeycloak構築・設定だったためなんとなくReal名を vault としたが、「ローカル環境のSSO管理」を目的としてlab-ssoとかの方が良さそう。それならVault以外のシステム(AWXとか)の認証を管理しても自然だからね。

VaultのGitLab認証編の続き。

VaultにはGitHubの認証設定はあるが、サポートされているのはパーソナルアクセストークンを使った認証。
これだとログインのたびにトークンを入力する必要があり利便性をあまり感じられなかったので、GitLabのアカウントを使ったOIDC認証と同じようにできないかいろいろ調べたところ、Keycloakを間に挟めば実現できたのでそのまとめ。

Vault <-> Keycloak <-> GitHub構成

認証の流れのイメージとしては以下の通り。

GitHub OAuthアプリの作成

docs.github.com

OAuthアプリ作成の入力値と後述のKeycloakで作成するproviderの入力値は相互にやりとりするので、手作業の場合は同時進行がやりやすい。
callback URLはKeycloakのIdentity provider作成時に表示されるURLをセットする。
ただ書式はhttps://{keycloakのFQDN}/realms/{realm-name}/broker/github/endpointなので、入力値が決まっているなら決め打ちで入力可能。

Application Name: vault-keycloak
Homepage URL: vaultのURL (https://vault.example.org)
Authorization callback URL: https://keycloak.example.org/realms/vault/broker/github/endpoint

入力したら「Register application」押下する。
画面遷移するとClient IDの確認と、「Generate a new client secret」でSecretを生成し内容を確認。
この値をKeycloakのGitHub Identity provider作成で入力する。

Keycloak

手元の環境ではKeycloak自体のデプロイからだと情報量が多いので詳細は後述。
ポイントは以下

「Identity provider」から「GitHub」を作成、GitHub OAuthアプリの情報をもとにClient ID/Secret/Scopeを入力
「Clients」でVault認証用のリソースを作成、IDとredirect URLを入力し、credentialsでsecretを確認

Vault

手元の環境ではデフォルトのパスはGitLab用に使ったので、-path=でパス指定で作成する。
ここではgithubとする。

/ $ vault auth enable -path=github oidc
Success! Enabled oidc auth method at: keycloak/

確認 (disableするときはgithubを引数にする)

/ $ vault auth list
Path       Type     Accessor               Description                Version
----       ----     --------               -----------                -------
github/    oidc     auth_oidc_f5fd3516     n/a                        n/a
oidc/      oidc     auth_oidc_7341c424     n/a                        n/a
token/     token    auth_token_c8a88b52    token based credentials    n/a

設定投入。
Keycloakはローカルに自前のルートCAを使ってたてているので、GitLabのときと同様にTLS検証のためルートCAのcrtファイルをoidc_discovery_ca_pemで指定。
oidc_client_secretにはKeycloakで生成したSecretの値を指定する。

vault write auth/github/config \
   oidc_discovery_url="https://keycloak.exmaple.org/realms/vault" \
   oidc_client_id="vault" \
   oidc_client_secret="$secret" \
   oidc_discovery_ca_pem=@/opt/ca/root-ca/ca.crt

ロール作成
allowed_redirect_urisにはコールバックのURLを指定する。書式としてはhttps://{vault-fqdn}/ui/vault/auth/{path}/oidc/callbackで、OIDCのパスをgithubにしているのであればhttps://{vault-fqdn}/ui/vault/auth/github/oidc/callbackとなる。

vault write auth/github/role/{role-name} \
  bound_audiences="vault" \
  allowed_redirect_uris="https://vault.example.org/ui/vault/auth/github/oidc/callback" \
  user_claim="preferred_username" \
  policies="kv-read-list" \
  ttl="1h"

これでVaultのwebログインでMethodをOIDC、Roleにロール作成時のロール名、パスはOIDC以外の場合(本記事でいえば-path=githubなのでgithub)を入力すればKeycloak経由でGitHub認証ができる。
また、ログインすればkv-read-listポリシーでVaultを利用できる。

Keycloak構築

Keycloakはこれまで一度も触れたことなくて認証系の何か程度しか認識してなかったけど、一言で言うと認証系の何か(雑)
OSS(Apache License version 2)なので無料で利用でき、ID管理やSSOなどをこれで実現できる。

www.keycloak.org

そういや以前OurBoardをたてたときに認証基盤として付属してたけど、でも個人用途で認証不要だったため不使用だった。

zaki-hmkc.hatenablog.com

デプロイ

※ GitLabの場合と同様、VaultからTLS検証をパスできるようにちゃんとした証明書か手元にあるルートCAで署名したサーバー証明書でデプロイすること。

zaki-hmkc.hatenablog.com

Docker版も早そうだけどVaultをKubernetes(K3s)でたててるので隣(同じクラスタの別ネームスペース)にデプロイすることにする。
bitnamiのHelmチャートが以前はあったようだが現在は(bitnamiが)使用不可。

ということで、公式で用意されてるマニフェストを使用してデプロイ。
マニフェストを確認すればわかるがKeycloak pod自体はStatefulSet、PostgreSQLが付属する。
また、初期パスワードは admin / admin となる。

github.com

$ kubectl create -f https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/refs/heads/main/kubernetes/keycloak.yaml -n keycloak 
service/keycloak created
service/keycloak-discovery created
statefulset.apps/keycloak created
deployment.apps/postgres created
service/postgres created

$ kc get pod -n keycloak 
NAME                       READY   STATUS    RESTARTS   AGE
keycloak-0                 1/1     Running   0          80s
keycloak-1                 1/1     Running   0          38s
postgres-764d8fc66-pbjvp   1/1     Running   0          80s

Ingressも用意されている。ホスト名を入力すればK3sのTraefik Ingressコントローラーでそのまま使用できる。
(VaultからOpenIDでKeycloakを登録する際にGitLabのときと同様にHTTPSアクセスが必要なので、TraefikはルートCAで署名されたサーバー証明書を使用する)

wget -q -O - https://raw.githubusercontent.com/keycloak/keycloak-quickstarts/refs/heads/main/kubernetes/keycloak-ingress.yaml | \
sed "s/KEYCLOAK_HOST/自分の環境のKeycloak用FQDN/" | \
kubectl create -f -

adminアカウントの初期設定は万物を解説し続けるとほほのKeycloak入門のチュートリアルも参照。

www.tohoho-web.com

ログインしたら別途管理者ユーザーを作成・admin権限付与・ログインし、初期のadminユーザーを削除する。
ユーザー設定が済んだら「Manage realms」からVault認証用のRealmも作成する。ここではvaultとした。
(realm内へのユーザー作成は不要。GitHub認証で自動追加される。)

以降はvault realmで作業

Identity provider

左側メニューの「Identity providers」で「GitHub」を選択。

表示されているRedirect URLをGitHubのOAuth Appsの「Authorization callback URL」に入力。
Client IDとClient SecretにGitHubのOAuth Appsで取得した値をそれぞれ入力し「Add」押下
「Add」押下で入力欄が画面下部に追加され、scopeにread:user user:emailを入力。

ほかは未入力・未チェックで良いはず。
これでKeycloak <-> GitHub間の認証設定ができる。

Clients

次にVaultからKeycloakで認証するための設定。

「Clients」メニューで「Create client」押下。

General settings
- Client type: OpenID Connect
- Client ID: vault
- Name: vault
Capability config
- Client authentication: チェック
Login settings
- Root URL: vaultのFQDN
- Valid redirect URIs: https://vault.example.org/ui/vault/auth/{path}/oidc/callback
  - {path}はvault auth enableしたときのパス。デフォルトoidc

作成したら「Credentials」タブでClient Secretの値を確認。この値をvault write auth/{path}/configのパラメタに使う。

(おまけ) GitHub パーソナルアクセストークン設定

前提として、ユーザーは組織に属しており、組織に対して認証可能とする仕組みになっている。

GitHub - Auth Methods | Vault | HashiCorp Developer

GitHub認証の有効化。

/ $ vault auth enable github
Success! Enabled github auth method at: github/

認証設定で組織名を指定する。

/ $ vault write auth/github/config organization=認証を許可したい組織名
Success! Data written to: auth/github/config

また、作成するパーソナルアクセストークンにはread:orgのscopeが必要。無いと下記エラー

* GET https://api.github.com/user/orgs?per_page=100: 403 You need at least read:org scope or user scope to list your organizations. []

課題

試した限り、Keycloak経由GitHub認証を行う際は「GitHubのアカウントがありさえすれば認証できる」状態のため、「VaultとKeycloakのweb UIにアクセスできる環境でGitHubのアカウントがある」であれば、誰でもVaultへログインできてしまう。
特定組織に所属するGitHubアカウントだけに制限できればベストだったが、やり方がわからなかった。

VaultとKeycloakがインターネットへのアウトバウンド接続のあるオンプレ環境で動作して特定ユーザーしかアクセスできないという条件ならさほど問題はないが、インバウンドのパブリックアクセスができる環境だとかなりよろしくないので、その点は注意。
(制限かける手段があるならぜひ知りたい)