OAuth 보호된 리소스 메타데이터

MCP 클라이언트 인증 발견을 위한 RFC 9728 보호된 리소스 메타데이터 엔드포인트.

OAuth 보호된 리소스 메타데이터 엔드포인트 (RFC 9728)를 통해 MCP 클라이언트는 AACWorkflow의 API를 보호하는 OAuth 인증 서버를 사전 구성 없이 발견할 수 있습니다. Claude, ChatGPT 및 기타 MCP 호스트와의 원활한 통합이 가능합니다.

발견 엔드포인트

GET /.well-known/oauth-protected-resource

반환:

{
  "resource": "https://aacworkflow.example.com/mcp",
  "authorization_servers": ["https://aacworkflow.example.com"],
  "scopes_supported": [
    "issues:read",
    "issues:write",
    "comments:read",
    "comments:write",
    "agents:read",
    "agents:write",
    "runtimes:read",
    "autopilot:run",
    "dashboard:read"
  ],
  "bearer_methods_supported": ["header"]
}

필드	의미
`resource`	보호되는 MCP 리소스 URL
`authorization_servers`	이 리소스에 대한 액세스 토큰을 발급할 수 있는 OAuth 인증 서버 URL 배열
`scopes_supported`	리소스가 인식하는 범위 목록
`bearer_methods_supported`	토큰 전달 방법 (`header` = `Authorization: Bearer <token>`)

WWW-Authenticate header 발견

MCP 클라이언트가 토큰 없이 또는 유효하지 않은 토큰으로 보호된 리소스에 요청하면 서버는 401 Unauthorized로 응답하고 WWW-Authenticate header 포함:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://aacworkflow.example.com/.well-known/oauth-protected-resource"

이 header는 클라이언트에 알립니다: 「이 리소스는 OAuth로 보호됩니다. 이 URL에서 메타데이터를 가져와 인증 방법을 알아보세요.」

클라이언트는 그 후:

resource_metadata의 URL에서 메타데이터 가져오기
authorization_servers 읽어 등록 및 토큰 획득 위치 찾기
메타데이터를 사용하여 OAuth 흐름 완료
새 액세스 토큰으로 요청 재시도

흐름: 영 설정 클라이언트

AACWorkflow API URL만 알고 있는 클라이언트가 인증을 부트스트랩할 수 있습니다:

클라이언트: GET /api/issues
          (Authorization header 없음)

서버: 401 Unauthorized
     WWW-Authenticate: Bearer resource_metadata="https://aacworkflow.example.com/.well-known/oauth-protected-resource"

클라이언트: GET /.well-known/oauth-protected-resource
서버: 200 OK
     {
       "authorization_servers": ["https://aacworkflow.example.com"],
       "scopes_supported": ["issues:read", "issues:write", ...],
       ...
     }

클라이언트: https://aacworkflow.example.com으로 OAuth 시작
          (/.well-known/oauth-authorization-server에서 AS 메타데이터 발견)
          auth-code + PKCE 흐름 완료
          액세스 토큰 수신

클라이언트: GET /api/issues
          Authorization: Bearer <access_token>
서버: 200 OK
     [issue 목록]

RFC 9728 준수

메타데이터 엔드포인트는 RFC 9728 — OAuth 2.0 보호된 리소스 메타데이터를 따릅니다:

필수 필드: resource, authorization_servers, scopes_supported
선택 필드: bearer_methods_supported (명확성 위해; 헤더만 사용)
캐시 헤더: 응답이 적절한 캐시 제어 지시사항 포함

인증 서버 메타데이터와 통합

보호된 리소스 메타데이터 엔드포인트는 인증 서버 메타데이터 엔드포인트와 함께 작동합니다:

엔드포인트	RFC	목적
`/.well-known/oauth-protected-resource`	9728	리소스를 보호하는 AS 발견
`/.well-known/oauth-authorization-server`	8414	AS 엔드포인트 및 능력 발견

완전한 부트스트랩 흐름:

1. /api/issues 접근 시도 → 401 + WWW-Authenticate header
2. /.well-known/oauth-protected-resource 가져오기 → AS URL 학습
3. /.well-known/oauth-authorization-server 가져오기 → 엔드포인트 학습
4. 해당 엔드포인트에서 OAuth 흐름 완료
5. 토큰으로 재시도

사용 사례

Claude (MCP 통해)

Claude.ai 또는 Claude Desktop의 Claude 플러그인:

사용자가 AACWorkflow URL만 제공
Claude가 보호된 리소스 메타데이터 가져오기
Claude가 OAuth 로그인 표시
사용자 승인; Claude가 토큰 수신
Claude가 이제 사용자 대신 MCP 도구 호출 가능

ChatGPT

ChatGPT 커넥터 설정:

사용자가 ChatGPT 설정에 AACWorkflow URL 입력
ChatGPT가 AS 발견하기 위해 보호된 리소스 메타데이터 가져오기
ChatGPT가 OAuth 흐름 처리 (사용자가 로그인 봄)
ChatGPT가 토큰 안전하게 저장
ChatGPT가 이후 대화에서 도구 호출 가능

사용자 정의 MCP 서버

AACWorkflow를 래핑하는 사용자 정의 MCP 서버:

보호된 리소스 메타데이터 읽기
리소스 URL이 일치하는지 확인
모든 필수 범위가 scopes_supported에 있는지 확인
OAuth 요청을 정확히 어디로 보낼지 알기

인증 서버 URL의 수동 구성 불필요. 클라이언트가 메타데이터에서 읽음.

보안

메타데이터는 공개 — 인증 필요 없음
메타데이터는 캐시 가능 — CDN/브라우저 캐싱 가능
메타데이터는 정적 — 인증 서버 URL 자주 변경 안 됨
토큰 검증은 여전히 완전한 범위 및 서명 확인 필요; 메타데이터는 발견만

OAuth 보호된 리소스 메타데이터

이 페이지에서