Keycloak による認証

Agent-Lab における Keycloak の使い方

Keycloak は、OpenID Connect による認証と認可を管理します。 auth.enabled が true の場合（設定リファレンスを参照）、次のように動作します。

FastAPI のミドルウェアが、すべてのリクエストでレルムの JWKS に対して Bearer トークンを検証します。標準の除外パス（/auth/*、/status/*、/docs、 /openapi.json、/mcp、/static）は対象外です。
/auth ルーターが、ログイン、トークンの更新、プロフィール、Microsoft Entra ID のトークン交換エンドポイントを公開します。
MCP サーバーは、同じレルムを基盤とする OAuth プロキシを介してクライアントを認証し、標準の .well-known メタデータエンドポイントを公開します。

レルム、クライアント、サービスアカウントの設定

以下の手順では Keycloak Admin API を使用します。まず、管理者の認証情報とエンドポイントを設定します。

export ADMIN_USER=<admin_username>
export ADMIN_PASS=<admin_password>
export ADMIN_TOKEN=$(curl -s -X POST "https://<auth_fqdn>/realms/master/protocol/openid-connect/token" \
    -d "username=${ADMIN_USER}&password=${ADMIN_PASS}&grant_type=password&client_id=admin-cli" | jq -r '.access_token')

レルムを作成します（<realm_name> を置き換えてください）。

curl -X POST https://<auth_fqdn>/admin/realms \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{"realm": "<realm_name>", "enabled": true}'

Agent-Lab 用のクライアントを作成します。

curl -X POST https://<auth_fqdn>/admin/realms/<realm_name>/clients \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{
    "clientId": "<client_name>",
    "enabled": true,
    "protocol": "openid-connect",
    "publicClient": false,
    "redirectUris": ["https://<agent_lab_fqdn>/*"],
    "standardFlowEnabled": true,
    "clientAuthenticatorType": "client-secret"
  }'

クライアントシークレットを取得します。

export CLIENT_ID=$(curl -X GET "https://<auth_fqdn>/admin/realms/<realm_name>/clients?clientId=<client_name>" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq -r '.[0].id')

export CLIENT_SECRET=$(curl -X GET "https://<auth_fqdn>/admin/realms/<realm_name>/clients/${CLIENT_ID}/client-secret" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq -r '.value')

これらの値は auth.* 設定キー（auth.url、auth.realm、 auth.client_id、auth.client_secret）に対応します。設定リファレンスに従って、Vault のペイロードに保存してください。

サービスアカウントのユーザーを作成します。

curl -X POST https://<auth_fqdn>/admin/realms/<realm_name>/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{
    "username": "<username>",
    "enabled": true,
    "email": "<username>@example.com",
    "credentials": [{"type": "password", "value": "<user_password>", "temporary": false}]
  }'

必要に応じて、Keycloak の UI でロールやマッパーを細かく調整してください。

トークンの発行と検証

ユーザートークンを取得します（パスワードグラント。アプリ側で POST /auth/login が実行するのと同じフローです）。

export USER_TOKEN=$(curl -s -X POST https://<auth_fqdn>/realms/<realm_name>/protocol/openid-connect/token \
  -d "grant_type=password" \
  -d "client_id=<client_name>" \
  -d "client_secret=${CLIENT_SECRET}" \
  -d "username=<username>" \
  -d "password=<user_password>" | jq -r '.access_token')

curl -s https://<agent_lab_fqdn>/agents/list -H "Authorization: Bearer $USER_TOKEN" | jq

トークンは POST /auth/renew で更新できます。また、Microsoft Entra ID で認証されたユーザーは、 POST /auth/exchange を通じてアプリのトークンと交換できます（PKCE を用いた認可コードフローで、設定内の Entra ID 認証情報を使用します）。

プロビジョニングの自動化

Terraform モジュール terraform/12_agent-lab-auth-realm/（デプロイガイドの一部）は、リファレンスデプロイ用のレルム、クライアント、サービスアカウントをプロビジョニングします。実際の環境では、手動の手順の代わりにこのモジュールを使用してください。