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에서 역할과 매퍼를 세부 조정하세요.

토큰 발급 및 검증

사용자 토큰 발급(password grant — 앱 측에서 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를 통해 앱 토큰으로 교환할 수 있습니다(구성에 설정된 Entra ID 자격 증명을 사용하는 PKCE authorization-code 흐름).

자동 프로비저닝

Terraform 모듈 terraform/12_agent-lab-auth-realm/(배포 가이드의 일부)은 레퍼런스 배포를 위한 렐름, 클라이언트, 서비스 계정을 프로비저닝합니다. 실제 환경에서는 수동 단계 대신 이 모듈을 사용하세요.