Keycloak Realm Inspector

순수하게 OAuth 2.0 보호 리소스로만 동작하는 MCP 서버로, Client ID 메타데이터 문서(draft-ietf-oauth-client-id-metadata-document-02)에 관한 KeyConf 2026 발표를 위한 것입니다.

아무것도 발급하지 않습니다 — /authorize도, /token도, 클라이언트 시크릿도 없습니다. Keycloak이 토큰을 발급하고, 이 서버는 Keycloak의 JWKS를 기준으로 해당 토큰을 검증하며, RFC 9728 디스커버리를 제공하고, 리소스 서버 내부에서 CIMD를 볼 수 있게 해주는 세 가지 도구를 노출합니다.

의도적으로 분리된 세 주체

이 서버는 클라이언트의 메타데이터 문서를 호스팅하거나 읽거나 가져오지 않습니다. /client-metadata.json 라우트도 로컬 사본도 없습니다. Keycloak은 /authorize 중에 네트워크를 통해 해당 URL을 가져옵니다. 이 코드베이스에서 URL은 azp 클레임에 담겨 도착하는 불투명한 문자열로만 나타납니다 — 이것이 데모의 핵심이며, 문서가 별도 포트의 별도 프로세스에서 서비스되는 이유이기도 합니다.

Related MCP server: mcpauth

실행

Keycloak이 실행 중이고, realm이 생성되었으며 CIMD 클라이언트 정책이 이미 적용된 상태를 가정합니다. 클라이언트, 해당 메타데이터 문서 및 토큰 헬퍼는 이 리포지토리와 함께 ../cimd-demo/auth-server/에 있습니다.

# terminal 1 — the client's document. Its own party, its own port.
cd ../cimd-demo/auth-server && python -m http.server 9000

# terminal 2 — the resource server
pip install -r requirements.txt
python server.py                     # http://localhost:9001

# terminal 3 — get a token, then point an MCP client at :9001/mcp
cd ../cimd-demo/auth-server && python get-token.py

흐름

1. 클라이언트는 토큰 없이 /mcp를 호출하고, WWW-Authenticate: Bearer ..., resource_metadata="…"와 함께 401을 받습니다.

2. 클라이언트는 이를 따라 /.well-known/oauth-protected-resource/mcp로 이동하여, 유효한 토큰을 발급하는 인증 서버가 어디인지 확인합니다.

3. 클라이언트는 메타데이터 문서 URL을 client_id로 사용하여 Keycloak에 직접 인증합니다. Keycloak은 해당 URL을 가져와 클라이언트를 구체화합니다.

4. 클라이언트는 베어러 토큰으로 /mcp를 다시 시도합니다.

RFC 9728 §3.1은 well-known 세그먼트를 호스트와 리소스 경로 사이에 배치하므로, 디스커버리 문서는 /.well-known/oauth-protected-resource/mcp에 위치합니다. 경로만 있는 URL은 404입니다.

도구

• whoami() — 호출자의 토큰에서 sub, preferred_username, azp, scope, exp, iss를 추출하고, registered_via_cimd도 함께 제공합니다. 토큰만 읽으므로 Keycloak 호출이 없으며, 관리자 자격 증명이 잘못되어도 작동합니다.

• list_clients(only_cimd=False) — realm의 클라이언트 목록. URL 형태의 client_id가 맨 위로 정렬되어 호출한 클라이언트가 첫 줄에 표시됩니다.

• get_client_metadata(client_id) — Keycloak이 보유한 클라이언트 표현. 게시된 문서가 아니라 Keycloak의 파생 뷰입니다.

CIMD는 client_id가 http:// 또는 https://로 시작하는지로 감지합니다. URL 형태의 client_id가 바로 그 신호입니다.

get_client_metadata는 반환 전에 secret과 registrationAccessToken을 제거합니다. 둘 다 유효한 베어러 자격 증명이며, 이 출력은 프로젝터와 녹화에 그대로 노출됩니다.

알려진 두 가지 한계

RFC 8707 리소스 표시자. audience=는 존재하지만 JWTVerifier에서 주석 처리되어 있습니다. 토큰에 audience를 제한하려면 클라이언트가 /authorize에서 resource를 보내야 하는데, Keycloak 26.7의 CIMD 경로는 아직 이를 지원하지 않습니다(keycloak#45106, keycloak#45284). 따라서 토큰은 Keycloak의 일반적인 account audience를 담고 있으며, 이 서버는 audience를 제한할 수 없습니다. 의도적으로 드러나 있습니다.

scope 강제 없음. required_scopes가 설정되어 있지 않으므로, realm에서 발급된 서명이 유효하고 만료되지 않은 모든 토큰이 허용됩니다 — admin-cli 비밀번호 그랜트로 발급된 토큰도 포함됩니다. 이것은 무대에서 유용합니다: 관리자 토큰(azp는 불투명한 문자열)으로 whoami()를 실행하고, CIMD 토큰(azp는 URL)으로 다시 실행하면, 같은 도구, 같은 서버에서 그 차이는 단 한 필드에서 나타납니다. 또한 어떤 토큰을 들고 있는지 확신해야 함을 의미합니다.

구성

모든 os.getenv는 localhost 기본값을 사용합니다.

KEYCLOAK_ISSUER와 KEYCLOAK_JWKS_URI는 서로 파생되지 않고 각각 별도로 구성할 수 있습니다. Kubernetes에서 issuer는 공개 URL이므로 iss는 클라이언트가 보는 값과 일치하는 반면, JWKS 가져오기는 클러스터 내부 Service로 향해야 합니다.

fastmcp는 정확한 버전으로 고정되어 있습니다. 인증 관련 API는 계속 바뀝니다 — resource_server_url이 base_url이 되었고, AccessToken.claims는 2.11.3에서 추가되었습니다 — 그리고 allowed_client_redirect_uris는 문서에 표시된 것과 달리 어떤 릴리스에서도 RemoteAuthProvider 매개변수가 아닙니다. 이것은 이 서버가 사용하지 않는 OAuthProxy에 속합니다.