byteforce

CPN 한국어 자습서 · 외부 문서 한국어 미러

MCP 문서 · Specification

인가

Authorization · 원문: modelcontextprotocol.io/specification/2025-11-25/basic/authorization

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

소개

목적 및 범위

Model Context Protocol은 전송 레이어에서 인가 기능을 제공하여 MCP 클라이언트가 리소스 소유자를 대신해 제한된 MCP 서버에 요청할 수 있게 합니다. 이 명세는 HTTP 기반 전송의 인가 흐름을 정의합니다.

프로토콜 요구사항

인가는 MCP 구현에서 선택 사항(OPTIONAL)입니다. 지원하는 경우:

HTTP 기반 전송을 사용하는 구현체는 이 명세를 따르는 것이 좋습니다(SHOULD).
STDIO 전송을 사용하는 구현체는 이 명세를 따르지 말고 환경에서 자격증명을 가져와야 합니다(SHOULD NOT).
대체 전송을 사용하는 구현체는 해당 프로토콜의 확립된 보안 모범 사례를 따라야 합니다(MUST).

표준 준수

이 인가 메커니즘은 다음 명세를 기반으로 합니다:

OAuth 2.1 IETF DRAFT (draft-ietf-oauth-v2-1-13)
OAuth 2.0 Authorization Server Metadata (RFC8414)
OAuth 2.0 Dynamic Client Registration Protocol (RFC7591)
OAuth 2.0 Protected Resource Metadata (RFC9728)
OAuth Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document-00)

역할

보호된 MCP 서버는 액세스 토큰을 사용하여 보호된 리소스 요청을 수락하고 응답하는 OAuth 2.1 리소스 서버 역할을 합니다.

MCP 클라이언트는 리소스 소유자를 대신하여 보호된 리소스 요청을 하는 OAuth 2.1 클라이언트 역할을 합니다.

인가 서버(authorization server)는 사용자와 상호작용하고(필요한 경우) MCP 서버에서 사용할 액세스 토큰을 발급하는 역할을 합니다.

개요

인가 서버는 적절한 보안 조치를 갖춘 OAuth 2.1을 구현해야 합니다(MUST).
인가 서버와 MCP 클라이언트는 OAuth Client ID Metadata Documents를 지원해야 합니다(SHOULD).
인가 서버와 MCP 클라이언트는 OAuth 2.0 Dynamic Client Registration Protocol(RFC7591)을 지원할 수 있습니다(MAY).
MCP 서버는 OAuth 2.0 Protected Resource Metadata(RFC9728)를 구현해야 합니다(MUST). MCP 클라이언트는 인가 서버 탐색에 이를 사용해야 합니다(MUST).
MCP 인가 서버는 다음 탐색 메커니즘 중 하나 이상을 제공해야 합니다(MUST): * OAuth 2.0 Authorization Server Metadata (RFC8414) * OpenID Connect Discovery 1.0

인가 서버 탐색

인가 서버 위치

MCP 서버는 OAuth 2.0 Protected Resource Metadata(RFC9728) 명세를 구현해야 합니다(MUST). 반환되는 Protected Resource Metadata 문서에는 authorization_servers 필드가 포함되어야 합니다(MUST).

Protected Resource Metadata 탐색 요구사항

MCP 서버는 다음 탐색 메커니즘 중 하나를 구현해야 합니다(MUST):

WWW-Authenticate 헤더: 401 Unauthorized 응답 시 resource_metadata 아래에 리소스 메타데이터 URL을 포함합니다.
Well-Known URI: RFC9728에 지정된 well-known URI에서 메타데이터를 제공합니다: * 경로: https://example.com/.well-known/oauth-protected-resource/public/mcp * 루트: https://example.com/.well-known/oauth-protected-resource

MCP 클라이언트는 두 탐색 메커니즘 모두 지원해야 합니다(MUST).

MCP 서버는 WWW-Authenticate 헤더에 scope 파라미터를 포함해야 합니다(SHOULD).

scope 안내가 포함된 401 응답 예시:

코드 · 명령

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         scope="files:read"

인가 서버 메타데이터 탐색

경로 구성 요소가 있는 발급자 URL(예: https://auth.example.com/tenant1)의 경우, 클라이언트는 다음 우선순위로 엔드포인트를 시도해야 합니다(MUST):

https://auth.example.com/.well-known/oauth-authorization-server/tenant1
https://auth.example.com/.well-known/openid-configuration/tenant1
https://auth.example.com/tenant1/.well-known/openid-configuration

경로 구성 요소가 없는 발급자 URL의 경우:

https://auth.example.com/.well-known/oauth-authorization-server
https://auth.example.com/.well-known/openid-configuration

인가 서버 탐색 시퀀스 다이어그램

코드 · 명령

sequenceDiagram
    participant C as Client
    participant M as MCP Server (Resource Server)
    participant A as Authorization Server

    Note over C: Attempt unauthenticated MCP request
    C->>M: MCP request without token
    M-->>C: HTTP 401 Unauthorized (may include WWW-Authenticate header)

    alt Header includes resource_metadata
        C->>M: GET resource_metadata URI
        M-->>C: Resource metadata with authorization server URL
    else No resource_metadata in header
        C->>M: GET /.well-known/oauth-protected-resource/mcp
        alt Sub-path metadata found
            M-->>C: Resource metadata with authorization server URL
        else Sub-path not found
            C->>M: GET /.well-known/oauth-protected-resource
            alt Root metadata found
                M-->>C: Resource metadata with authorization server URL
            else Root metadata not found
                Note over C: Abort or use pre-configured values
            end
        end
    end

    C->>A: GET Authorization server metadata endpoint
    A-->>C: Authorization server metadata

    C->>A: Token request
    A-->>C: Access token

    C->>M: MCP request with access token
    M-->>C: MCP response

클라이언트 등록 방식

MCP는 세 가지 클라이언트 등록 메커니즘을 지원합니다:

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

우선순위:

사용 가능한 경우 사전 등록된 클라이언트 정보 사용
인가 서버가 지원하는 경우 Client ID Metadata Documents 사용
인가 서버가 지원하는 경우 Dynamic Client Registration을 대안으로 사용
다른 옵션이 없는 경우 사용자에게 클라이언트 정보 입력 요청

Client ID Metadata Documents

MCP 클라이언트와 인가 서버는 OAuth Client ID Metadata Documents를 지원해야 합니다(SHOULD). 이 방식은 클라이언트가 HTTPS URL을 클라이언트 식별자로 사용할 수 있게 합니다.

MCP 클라이언트의 경우: * 클라이언트는 HTTPS URL에 메타데이터 문서를 호스팅해야 합니다(MUST) * client_id URL은 "https" 스킴을 사용하고 경로 구성 요소를 포함해야 합니다(MUST) * 메타데이터 문서에는 client_id, client_name, redirect_uris가 포함되어야 합니다(MUST)

인가 서버의 경우: * URL 형식의 client_id를 만나면 메타데이터 문서를 가져와야 합니다(SHOULD) * 가져온 문서의 client_id가 URL과 정확히 일치하는지 검증해야 합니다(MUST)

메타데이터 문서 예시:

코드 · 명령

{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "client_uri": "https://app.example.com",
  "logo_uri": "https://app.example.com/logo.png",
  "redirect_uris": [
    "http://127.0.0.1:3000/callback",
    "http://localhost:3000/callback"
  ],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

인가 서버는 다음을 통해 지원을 알립니다:

코드 · 명령

{
  "client_id_metadata_document_supported": true
}

사전 등록(Preregistration)

MCP 클라이언트는 사전 등록 흐름에서 제공된 정적 클라이언트 자격증명을 위한 옵션을 지원해야 합니다(SHOULD).

Dynamic Client Registration

MCP 클라이언트와 인가 서버는 하위 호환성을 위해 RFC7591을 지원할 수 있습니다(MAY).

범위 선택 전략(Scope Selection Strategy)

인가 흐름을 구현할 때 MCP 클라이언트는 다음 우선순위를 따라야 합니다(SHOULD):

401 응답의 WWW-Authenticate 헤더에서 scope 파라미터를 사용합니다
scope를 사용할 수 없는 경우 Protected Resource Metadata의 scopes_supported에 정의된 모든 범위를 사용합니다

인가 흐름 단계

코드 · 명령

sequenceDiagram
    participant B as User-Agent (Browser)
    participant C as Client
    participant M as MCP Server (Resource Server)
    participant A as Authorization Server

    C->>M: MCP request without token
    M->>C: HTTP 401 Unauthorized with WWW-Authenticate header

    C->>M: Request Protected Resource Metadata
    M->>C: Return metadata

    C->>A: GET Authorization server metadata endpoint
    A-->>C: Authorization server metadata

    alt Client ID Metadata Documents
        Note over C: Client uses HTTPS URL as client_id
        A->>C: Fetch metadata from client_id URL
        C-->>A: JSON metadata document
    else Dynamic client registration
        C->>A: POST /register
        A->>C: Client Credentials
    else Pre-registered client
        Note over C: Use existing client_id
    end

    C->>B: Open browser with authorization URL + code_challenge + resource
    B->>A: Authorization request with resource parameter
    Note over A: User authorizes
    A->>B: Redirect to callback with authorization code
    B->>C: Authorization code callback
    C->>A: Token request + code_verifier + resource
    A->>C: Access token (+ refresh token)
    C->>M: MCP request with access token
    M-->>C: MCP response

리소스 파라미터 구현

MCP 클라이언트는 RFC 8707에 정의된 OAuth 2.0용 Resource Indicators를 구현해야 합니다(MUST). resource 파라미터는:

인가 요청과 토큰 요청 모두에 포함되어야 합니다(MUST).
클라이언트가 토큰을 사용할 MCP 서버를 식별해야 합니다(MUST).
MCP 서버의 표준 URI를 사용해야 합니다(MUST).

유효한 표준 URI 예시: * https://mcp.example.com/mcp * https://mcp.example.com * https://mcp.example.com:8443

유효하지 않은 예시: * mcp.example.com (스킴 없음) * https://mcp.example.com#fragment (fragment 포함)

MCP 클라이언트는 인가 서버의 지원 여부에 관계없이 resource 파라미터를 전송해야 합니다(MUST).

액세스 토큰 사용

토큰 요구사항

MCP 클라이언트는 Authorization 요청 헤더를 사용해야 합니다(MUST):

코드 · 명령

Authorization: Bearer <access-token>

인가는 모든 HTTP 요청에 포함되어야 합니다(MUST).

액세스 토큰은 URI 쿼리 문자열에 포함해서는 안 됩니다(MUST NOT).

요청 예시:

코드 · 명령

GET /mcp HTTP/1.1
Host: mcp.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

토큰 처리

MCP 서버는 액세스 토큰을 검증하고 해당 서버를 위해 발급된 것인지 확인해야 합니다(MUST). 유효하지 않거나 만료된 토큰은 HTTP 401 응답을 받아야 합니다(MUST).

MCP 클라이언트는 MCP 서버의 인가 서버가 발급하지 않은 토큰을 전송해서는 안 됩니다(MUST NOT).

MCP 서버는 자신을 대상으로 하는 토큰만 수락해야 하며(MUST) 다른 토큰을 수락하거나 전달해서는 안 됩니다(MUST NOT).

오류 처리

상태 코드	설명	사용
401	Unauthorized	인가 필요 또는 토큰 유효하지 않음
403	Forbidden	유효하지 않은 범위 또는 권한 부족
400	Bad Request	잘못된 인가 요청

범위 챌린지 처리

클라이언트가 토큰을 가지고 있지만 추가 권한이 필요한 경우:

서버는 HTTP 403 Forbidden으로 응답해야 합니다(SHOULD)
error="insufficient_scope" 및 필요한 scope를 포함하는 WWW-Authenticate 헤더와 함께

예시:

코드 · 명령

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
                         scope="files:read files:write user:profile",
                         resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         error_description="Additional file write permission required"

단계적 인가 흐름(Step-Up Authorization Flow)

WWW-Authenticate 헤더에서 오류 정보를 파싱합니다
필요한 범위를 결정합니다
결정된 범위로 재인가를 시작합니다
새 토큰으로 원래 요청을 재시도합니다(재시도 횟수 제한 적용)

보안 고려사항

구현체는 OAuth 2.1 보안 모범 사례를 따라야 합니다(MUST).

토큰 대상 바인딩 및 검증

MCP 클라이언트는 인가 및 토큰 요청에 resource 파라미터를 포함해야 합니다(MUST)
MCP 서버는 토큰이 자신을 위해 발급되었는지 검증해야 합니다(MUST)

토큰 도용

클라이언트와 서버는 안전한 토큰 저장소를 구현해야 합니다(MUST)
인가 서버는 단기 액세스 토큰을 발급해야 합니다(SHOULD)
공개 클라이언트의 경우 인가 서버는 리프레시 토큰을 순환해야 합니다(MUST)

통신 보안

모든 인가 서버 엔드포인트는 HTTPS를 통해 제공되어야 합니다(MUST).
모든 리디렉션 URI는 localhost이거나 HTTPS를 사용해야 합니다(MUST).

인가 코드 보호

MCP 클라이언트는 S256 코드 챌린지 방법을 사용하여 PKCE를 구현해야 합니다(MUST).

MCP 클라이언트는 인가 서버 메타데이터에서 code_challenge_methods_supported를 확인하고 없으면 진행을 거부해야 합니다(MUST).

오픈 리디렉션

MCP 클라이언트는 인가 서버에 리디렉션 URI를 등록해야 합니다(MUST).
인가 서버는 사전 등록된 값에 대해 정확한 리디렉션 URI를 검증해야 합니다(MUST).
MCP 클라이언트는 state 파라미터를 사용하고 검증해야 합니다(SHOULD).

액세스 토큰 권한 제한

MCP 서버가 업스트림 API에 요청하는 경우, MCP 클라이언트로부터 받은 토큰을 전달해서는 안 됩니다(MUST NOT).

MCP 인가 확장

핵심 프로토콜에 대한 인가 확장은: * 선택 사항 — 구현체가 선택적으로 채택할 수 있습니다 * 부가적 — 핵심 프로토콜 기능을 수정하거나 손상시키지 않습니다 * 조합 가능 — 충돌 없이 함께 동작하도록 설계되었습니다 * 독립적으로 버전 관리 — 핵심 MCP 버전 관리 주기를 따릅니다

MCP Authorization Extensions 리포지터리를 참조하세요.

원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Model Context Protocol)에게 있습니다.

원문(영어): https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization

문서 이동

‹ 전송 주요 변경사항 › · 전체 목차