Skip to content

mcp-authz-server.md

Latest commit

 

History

History
225 lines (156 loc) · 18.1 KB

mcp-authz-server.md

File metadata and controls

225 lines (156 loc) · 18.1 KB
Raw
source https://www.keycloak.org/securing-apps/mcp-authz-server
keycloak_version 26.6.2
translated 2026-06-03
category securing-apps

Model Context Protocol(MCP) 통합하기

원문 제목(EN): Integrating with Model Context Protocol (MCP) 원문: https://www.keycloak.org/securing-apps/mcp-authz-server

현재 Model Context Protocol(MCP) 명세에는 네 가지 버전이 있습니다:

  • 2025-11-25 (최신 버전)
  • 2025-06-18
  • 2025-03-26
  • 2024-11-05 (초기 버전)

초기 버전(2024-11-05)은 권한 부여(authorization)를 다루지 않으므로, 이 가이드에서도 다루지 않습니다.

이 가이드는 다음 사항을 설명합니다:

  • Keycloak이 지원하는 MCP 버전.
  • MCP에서 Keycloak을 권한 부여 서버(authorization server)로 설정하는 방법.

단, 이 가이드가 필요한 모든 내용을 다루지는 않습니다. 따라서 해당 MCP 버전의 권한 부여 섹션도 함께 읽어보시기 바랍니다.

MCP가 요구하는 표준 준수(Standards Compliance)

MCP 명세에 따르면, MCP에서 권한 부여 서버에 관한 여러 표준이 있습니다. 아래 표는 다음을 보여줍니다:

  • 각 MCP 버전이 권한 부여 서버에 어떤 수준(MUST, SHOULD, MAY)으로 어떤 표준을 지원하도록 요구하는지.
  • Keycloak이 준수하는 표준.
표준 2025-11-25 2025-06-18 2025-03-26 Keycloak
The OAuth 2.1 Authorization Framework (Internet Draft) MUST MUST MUST 지원됨
OAuth 2.0 Authorization Server Metadata (RFC 8414) MUST MUST MUST 지원됨
Resource Indicators for OAuth 2.0 (RFC 8707) MUST MUST - 미지원
OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591) MAY SHOULD SHOULD 지원됨
OAuth Client ID Metadata Document (Internet Draft) SHOULD - - 지원됨

경고(WARNING): Keycloak의 OAuth Client ID Metadata Document 지원은 실험적(experimental) 기능입니다. 향후 Keycloak 버전에서 호환성이 깨지는 변경이 발생할 수 있습니다.

MCP 명세는 OAuth 2.0 Protected Resource Metadata (RFC 9728)을 채택합니다. 이 표준은 MCP 서버를 위한 것이며, Keycloak과 같은 권한 부여 서버를 위한 것이 아닙니다. 따라서 위 표에는 포함되지 않습니다.

MCP 버전 준수(MCP version compliance)

이 가이드에서 준수 기준으로, "Keycloak이 MCP를 지원한다"는 것은 Keycloak이 MCP의 모든 MUST 및 SHOULD 요구사항을 충족함을 의미합니다.

이 기준에 따라, 아래 표는 Keycloak이 지원하는 MCP 버전을 보여줍니다.

MCP 버전 준수 여부
2025-03-26 지원됨
2025-06-18 Resource Indicators for OAuth 2.0 없이 부분적으로 지원됨
2025-11-25 Resource Indicators for OAuth 2.0 없이 부분적으로 지원됨

설정(Setup)

MCP 2025-03-26의 경우

별도의 특별한 설정이 필요하지 않습니다.

MCP 2025-06-18 및 2025-11-25의 경우

토큰 대상 바인딩 및 검증(Token Audience Binding and Validation)

보안 이점을 얻기 위해, MCP 명세는 액세스 토큰이 대상(audience)과 바인딩되도록 요구합니다. 이를 위해 MCP 명세는 다음을 요구합니다:

  • MCP 클라이언트는 권한 부여 요청 및 토큰 요청에 Resource Indicators for OAuth 2.0 (RFC 8707)에 정의된 resource 파라미터를 반드시 포함해야 합니다. 파라미터의 값은 MCP 클라이언트가 토큰을 사용하려는 MCP 서버를 식별해야 합니다.
  • MCP 서버는 자신에게 제시된 토큰이 자신을 위해 발급되었는지 반드시 검증해야 합니다.

MCP 명세는 이 바인딩을 수행하는 방법을 설명하지 않습니다. 바인딩의 한 가지 방법은 resource 파라미터의 값을 액세스 토큰의 aud 클레임에 설정하는 것입니다. 그러나 Keycloak은 resource 파라미터를 인식할 수 없습니다.

Keycloak 커뮤니티는 MCP 명세가 기대하는 대로 Keycloak이 resource 파라미터를 인식하고 처리할 수 있도록 Resource Indicators for OAuth 2.0 (RFC 8707)을 Keycloak에 지원할 계획입니다. 이 지원이 완료될 때까지, resource 파라미터 대신 OAuth 2.0의 scope 파라미터를 사용할 수 있습니다. 바인딩을 보여주기 위해 다음 상황을 고려해 보십시오:

  • MCP 서버의 URL은 https://example.com/mcp
  • MCP는 mcp:tools, mcp:prompts, mcp:resources 세 가지 스코프를 지원합니다.
  • MCP 서버에 액세스하기 위한 액세스 토큰을 얻기 위해, MCP 클라이언트는 resource 파라미터 값이 https://example.com/mcp이고 scope 파라미터에 세 가지 스코프의 임의 조합을 포함하는 권한 부여 요청을 Keycloak에 전송합니다.
  • 우리는 Keycloak이 aud 클레임 값이 MCP 서버의 URL, 즉 https://example.com/mcp인 액세스 토큰을 발급하기를 원합니다.

Keycloak이 이러한 액세스 토큰을 발급하도록 하기 위해, Keycloak을 다음과 같이 구성할 수 있습니다:

  • Included Custom Audience 필드가 https://example.com/mcp인 새 Audience 매퍼를 추가한다.
  • 유형이 Optional인 클라이언트 스코프 mcp:tools를 추가한다.
  • 해당 클라이언트 스코프에 Included Custom Audience 필드가 https://example.com/mcp인 새 Audience 매퍼를 추가한다.
  • 유형이 Optional인 클라이언트 스코프 mcp:prompts를 추가한다.
  • 해당 클라이언트 스코프에 Included Custom Audience 필드가 https://example.com/mcp인 새 Audience 매퍼를 추가한다.
  • 유형이 Optional인 클라이언트 스코프 mcp:resources를 추가한다.
  • 해당 클라이언트 스코프에 Included Custom Audience 필드가 https://example.com/mcp인 새 Audience 매퍼를 추가한다.

클라이언트 스코프의 Included Custom Audience 필드는 권한 부여 요청의 resource 파라미터 값 및 MCP 서버의 URL과 동일해야 함에 유의하십시오.

이 구성을 사용하면, MCP 클라이언트가 resource 파라미터 값이 https://example.com/mcp이고 scope 파라미터에 mcp:resources, mcp:tools, mcp:prompts를 포함하는 권한 부여 요청을 Keycloak에 전송할 경우, Keycloak은 다음과 같은 액세스 토큰을 발급할 수 있습니다:

{
  ...
  "aud": "https://example.com/mcp",
  "scope": "mcp:resources mcp:tools mcp:prompts"
  ...
}

MCP Inspector 통합(MCP Inspector integration)

MCP Inspector(MCP 서버의 공식 디버깅 도구)를 Keycloak을 권한 부여 서버로 사용하여 사용하려면, MCP Inspector의 백엔드 서버에서 다운로드된 JavaScript가 MCP 클라이언트를 Keycloak에 동적으로 등록하기 때문에, Keycloak의 클라이언트 등록 엔드포인트에서 CORS에 대한 적절한 설정을 해야 합니다.

클라이언트 등록의 익명 액세스 정책에 대해 다음과 같이 적절히 설정해야 합니다:

  • Allowed Client Scopes: MCP 서버가 지원하는 스코프를 포함해야 합니다.
  • Allowed Registration Web Origins: MCP Inspector 백엔드 서버의 웹 오리진을 포함해야 합니다.
  • Trusted Hosts: Keycloak에 동적 클라이언트 등록 요청을 보내는 머신의 호스트명 또는 IP 주소(즉, 브라우저가 실행되는 머신)를 포함해야 합니다.

MCP 2025-11-25의 경우

클라이언트 등록(Client Registration)

MCP 명세의 Client Registration Approaches 섹션에 따르면, 다음 세 가지 클라이언트 등록 메커니즘이 지원되며 시나리오에 따라 선택할 수 있습니다:

  • Client ID Metadata Documents: 클라이언트와 서버 간에 사전 관계가 없는 경우(가장 일반적)
  • Pre-registration: 클라이언트와 서버 간에 기존 관계가 있는 경우
  • Dynamic Client Registration: 하위 호환성 또는 특정 요구사항을 위해

Keycloak은 OAuth Client ID Metadata Document를 지원합니다. Client ID Metadata Documents를 사용하려면, 기능을 활성화하고 Keycloak이 URL 형식의 client_id 파라미터를 처리하고 해당 URL에서 클라이언트 메타데이터를 가져오도록 클라이언트 정책을 설정해야 합니다.

경고(WARNING): OAuth Client ID Metadata Document 지원은 Keycloak의 실험적(experimental) 기능입니다. 따라서 향후 Keycloak 버전에서 호환성이 깨지는 변경이 발생할 수 있습니다. 이를 활성화하려면 --features=cimd로 Keycloak을 시작합니다.

OAuth Client ID Metadata Document를 위한 클라이언트 프로파일 설정

client_id 메타데이터가 Client ID Metadata Document를 가리키는 URL인 권한 부여 요청을 처리하려면, client-id-metadata-document 실행자(executor)를 포함하는 프로파일을 생성해야 합니다.

실행자를 구성하려면 Keycloak Admin Console에서 클라이언트 정책 프로파일을 생성합니다:

  1. Realm Settings → Client Policies → Profiles 탭으로 이동합니다.
  2. Create client profile을 클릭합니다.
  3. 프로파일에 cimd-profile과 같은 이름을 지정하고 Save를 클릭합니다.
  4. Add executor를 클릭하고 목록에서 client-id-metadata-document를 선택합니다.
  5. 다음 옵션으로 실행자를 구성합니다:
    • Allow http scheme: ON인 경우, Client ID URL 및 클라이언트 메타데이터 URL(예: client_uri, logo_uri, tos_uri, policy_uri, jwks_uri)에 대해 http 스킴을 허용합니다. 개발 환경에서만 ON이어야 하며, 프로덕션 환경에서는 반드시 OFF여야 합니다.
    • Trusted domains: 실행자가 Client ID URL 및 클라이언트 메타데이터 URL 속성에 허용하는 도메인 패턴(와일드카드) 목록입니다. 예를 들어, *.example.org를 사용하면 example.org의 모든 서브도메인을 허용합니다. 비어 있으면 모든 도메인이 거부됩니다.
    • Restrict same domain: ON인 경우, 실행자는 권한 부여 요청의 Client ID URL 및 Redirect URI, 그리고 클라이언트 메타데이터의 URL 값 속성이 모두 동일한 신뢰할 수 있는 도메인 아래에 있는지 확인합니다.
    • Required properties: Client ID Metadata Document에 반드시 있어야 하는 클라이언트 메타데이터 속성 목록입니다. 가져온 문서에 나열된 모든 속성이 없으면 요청이 거부됩니다.
    • Only Allow Confidential Client: ON인 경우, 실행자는 기밀 클라이언트(confidential client)를 나타내는 Client Metadata Document만 허용합니다. 이 경우 클라이언트 메타데이터에 jwks 또는 jwks_uri 속성이 포함되어야 하며 토큰 엔드포인트 인증 방법으로 private_key_jwt 또는 tls_client_auth를 사용해야 합니다.
  6. Save를 클릭합니다.
OAuth Client ID Metadata Document를 위한 클라이언트 정책 설정

권한 부여 요청의 client_id 파라미터가 지정된 스킴(예: https)과 일치하는 URI일 때 위에서 생성한 프로파일을 트리거하려면, client-id-uri 조건을 포함하는 정책을 생성해야 합니다.

조건을 구성하려면 Keycloak Admin Console에서 클라이언트 정책을 생성합니다:

  1. Realm Settings → Client Policies → Policies 탭으로 이동합니다.
  2. Create client policy를 클릭합니다.
  3. 정책에 cimd-policy와 같은 이름을 지정하고 Save를 클릭합니다.
  4. Conditions 아래에서 Add condition을 클릭하고 목록에서 client-id-uri를 선택합니다.
  5. 다음 옵션으로 조건을 구성합니다:
    • URI scheme: client_id 파라미터와 매칭할 URI 스킴 목록(예: https). 프로덕션 환경에서는 https만 사용해야 합니다.
    • Trusted domains: 조건이 client_id URI의 호스트 부분에 허용하는 도메인 패턴(와일드카드) 목록입니다. 도메인이 입력된 경우, 조건은 client_id의 호스트 부분이 도메인 중 하나와 일치할 때만 true로 평가됩니다. 입력되지 않으면 조건은 항상 false로 평가됩니다. 예를 들어, *.example.org를 사용하면 example.org의 모든 서브도메인을 허용합니다.
  6. Save를 클릭합니다.
  7. Associated client profiles 아래에서 이전 단계에서 생성한 cimd-profile 프로파일을 추가합니다.
  8. Save를 클릭합니다.

이 구성으로, MCP 클라이언트가 신뢰할 수 있는 도메인과 일치하는 https URL인 client_id 값으로 권한 부여 요청을 보내면, Keycloak은 해당 URL에서 Client ID Metadata Document를 가져와 요청을 처리하는 데 메타데이터를 사용합니다.

Client ID Metadata Document 실행자의 시스템 전체 설정

client-id-metadata-document 실행자에는 캐싱 및 메타데이터 크기 제한을 제어하는 다음과 같은 시스템 전체 설정이 있습니다. 이 설정은 Admin Console을 통해 구성할 수 없습니다. 대신, Keycloak을 시작할 때 SPI 옵션으로 구성합니다.

  • min-cache-time: 가져온 Client ID Metadata Document가 캐시되는 최소 시간(초). 기본값: 300 (5분).
  • max-cache-time: 가져온 Client ID Metadata Document가 캐시되는 최대 시간(초). 기본값: 259200 (3일).
  • upper-limit-metadata-bytes: Keycloak이 허용하는 Client ID Metadata Document의 최대 크기(바이트). 기본값: 5000 (5 KB).

이 설정을 구성하려면, Keycloak을 시작할 때 --spi-client-policy-executor--client-id-metadata-document--<property>=<value> 커맨드라인 옵션을 사용합니다. 예를 들어:

bin/kc.[sh|bat] start --spi-client-policy-executor--client-id-metadata-document--min-cache-time=600 --spi-client-policy-executor--client-id-metadata-document--max-cache-time=86400 --spi-client-policy-executor--client-id-metadata-document--upper-limit-metadata-bytes=10000

Visual Studio Code 데스크톱 통합(Visual Studio Code desktop integration)

Microsoft Visual Studio Code (VS Code) 데스크톱은 OAuth Client ID Metadata Document를 지원하는 MCP 클라이언트입니다. VS Code 데스크톱이 권한 부여가 필요한 MCP 서버에 연결하면, vscode.dev에 호스팅된 https URL(예: https://vscode.dev/mcp-client)인 client_id 파라미터와 함께 권한 부여 요청을 보냅니다. Keycloak은 이 URL에서 Client ID Metadata Document를 가져와 요청을 처리하는 데 메타데이터를 사용합니다.

VS Code 데스크톱은 OAuth 리다이렉트를 위해 로컬호스트 콜백을 사용합니다. 로컬 HTTP 서버를 시작하고 http://127.0.0.1:<port>/callback과 같은 리다이렉트 URI를 사용합니다. 리다이렉트 URI가 vscode.dev 도메인이 아닌 127.0.0.1에 있기 때문에, 클라이언트 프로파일 실행자의 Restrict same domain 옵션은 반드시 OFF로 설정해야 합니다.

VS Code 데스크톱의 MCP 클라이언트에 대해 Keycloak을 구성하려면 아래 단계를 따르십시오.

참고(NOTE): VS Code 데스크톱은 OAuth에 PKCE(Proof Key for Code Exchange)를 사용하는 공개 클라이언트(public client)입니다. 클라이언트 시크릿을 사용하지 않습니다.

CIMD 기능으로 Keycloak 시작하기

cimd 기능 플래그를 활성화하여 Keycloak을 시작합니다:

bin/kc.[sh|bat] start --features=cimd

VS Code 데스크톱을 위한 클라이언트 프로파일 설정

  1. Realm Settings → Client Policies → Profiles 탭으로 이동합니다.
  2. Create client profile을 클릭합니다.
  3. 프로파일에 vscode-cimd-profile과 같은 이름을 지정하고 Save를 클릭합니다.
  4. Add executor를 클릭하고 목록에서 client-id-metadata-document를 선택합니다.
  5. 다음 옵션으로 실행자를 구성합니다:
    • Allow http scheme: OFF
    • Trusted domains: vscode.dev, 127.0.0.1
    • Restrict same domain: OFF (VS Code 데스크톱은 vscode.dev와 동일한 도메인이 아닌 http://127.0.0.1:<port>/callback과 같은 로컬호스트 리다이렉트 URI를 사용합니다)
    • Only Allow Confidential Client: OFF (VS Code 데스크톱은 공개 클라이언트입니다)
  6. Save를 클릭합니다.

VS Code 데스크톱을 위한 클라이언트 정책 설정

  1. Realm Settings → Client Policies → Policies 탭으로 이동합니다.
  2. Create client policy를 클릭합니다.
  3. 정책에 vscode-cimd-policy와 같은 이름을 지정하고 Save를 클릭합니다.
  4. Conditions 아래에서 Add condition을 클릭하고 목록에서 client-id-uri를 선택합니다.
  5. 다음 옵션으로 조건을 구성합니다:
    • URI scheme: https
    • Trusted domains: vscode.dev
  6. Save를 클릭합니다.
  7. Associated client profiles 아래에서 이전 단계에서 생성한 vscode-cimd-profile 프로파일을 추가합니다.
  8. Save를 클릭합니다.

이 구성으로, VS Code 데스크톱이 권한 부여 요청을 보내면, Keycloak은 client_id를 vscode.dev의 URL로 인식하고, Client ID Metadata Document를 가져오며, 로컬호스트 콜백을 사용하여 OAuth 흐름을 완료합니다.