MCP 커넥터를 위한 OpenID 설정 수정 방법
이번 주에 원격 MCP 커넥터를 수정하느라 너무 많은 시간을 허비했습니다.
커넥터가 제 OAuth 서버를 계속 찾지 못했습니다. 서버는 정상적으로 작동하고 있었습니다. 문제는 단 하나의 누락된 경로와 리다이렉트였습니다.
MCP에서 OAuth를 사용할 때, 디스커버리 문서(discovery documents)가 제대로 작동할 것이라고 기대하게 됩니다. 대부분의 도구는 다음 두 경로를 찾습니다:
- /.well-known/oauth-authorization-server
- /.well-known/oauth-protected-resource
이 경로들은 클라이언트에게 인증(authorization) 및 토큰 엔드포인트를 어디서 찾을 수 있는지 알려줍니다.
문제는 많은 클라이언트가 해당 특정 경로를 찾지 않는다는 점입니다. 대신, /.well-known/openid-configuration을 찾습니다.
이것은 OpenID Connect 경로입니다. 서로 다른 스펙이지만 같은 위치에 존재합니다. 제 패키지는 OIDC 스펙이 아닌 OAuth 스펙을 따르고 있었기 때문에 이 경로를 등록하지 않았습니다.
클라이언트는 존재하지 않는 문을 두드리는 셈입니다. 그러면 404 에러를 받고 종료됩니다.
저에게는 두 가지 선택지가 있었습니다:
Nginx에서 리버스 프록시(reverse-proxy) 리다이렉트를 사용합니다. 이는 게으른 해결책입니다. 로직을 코드 밖으로 빼내 인프라로 옮기는 것이기 때문입니다. 테스트하기 어렵고 배포 중에 문제가 발생하기 쉽습니다.
애플리케이션 내부에서 수정합니다. 이것이 더 나은 방법입니다.
저는 앱이 해당 요청(probe)에 응답하도록 만드는 쪽을 택했습니다. OpenID 경로를 OAuth 인증 경로로 리다이렉트하는 별칭(alias)을 생성했습니다.
저는 308 Permanent Redirect를 사용했습니다.
302 리다이렉트는 POST 요청을 GET 요청으로 바꿀 수 있습니다. 반면 308 리다이렉트는 엄격합니다. 클라이언트에게 새로운 URL로 이동하되, 기존의 메서드와 바디(body)를 그대로 유지하라고 지시합니다. 이것이 영구적인 이동을 처리하는 올바른 방법입니다.
또한 이 기능을 설정 플래그(configuration flag) 뒤에 두었습니다. 이를 통해 사용자가 자체적인 OIDC 디스커버리를 실행하는 경우 이 기능을 끌 수 있도록 했습니다.
코드로 이 작업을 처리함으로써 다음과 같은 테스트를 작성할 수 있습니다:
- 리다이렉트가 올바르게 발생하는지 확인하는 테스트 하나.
- 리다이렉트를 따라가서 메타데이터가 유효한지 확인하는 테스트 하나.
이렇게 하면 메타데이터 구조가 변경될 경우 테스트가 즉시 실패하게 됩니다. 사용자가 연결할 수 없는 상황에서 오류를 발견하는 대신, 파이프라인 단계에서 오류를 찾아낼 수 있습니다.
실제 환경에서는 스펙이 서로 다른 경우가 많습니다. 두 표준이 유사한 목표를 공유하더라도 클라이언트는 서로 다른 경로를 선택할 수 있습니다. 서버 개발자라면 두 문 모두에 응답할 수 있어야 합니다.
클라이언트를 같은 곳으로 안내하고, 올바른 리다이렉트 코드를 사용하며, 테스트로 이를 뒷받침하십시오.
MCP 커넥터를 즉시 작동하게 만드는 잘 알려진 OpenID 설정 별칭
OpenID Connect (OIDC)를 다뤄본 적이 있다면, .well-known/openid-configuration 엔드포인트를 접해본 적이 있을 것입니다. 이 엔드포인트는 OIDC discovery의 핵심적인 부분으로, 클라이언트가 인증 서버와 통신하는 데 필요한 모든 메타데이터를 제공합니다.
최근 Model Context Protocol (MCP) 커넥터를 구축하면서, 이 "잘 알려진(well-known)" 엔드포인트가 얼마나 중요한 역할을 하는지 다시 한번 깨달았습니다.
OIDC Discovery란 무엇인가?
OIDC discovery는 클라이언트가 인증 서버의 설정을 자동으로 검색할 수 있게 해주는 메커니즘입니다. 개발자가 인증 엔드포인트, 토큰 엔드포인트, JWKS URI 등을 일일이 수동으로 입력할 필요 없이, 단 하나의 URL(보통 Issuer URL 뒤에 .well-known/openid-configuration을 붙인 것)만 알면 됩니다.
이 엔드포인트는 다음과 같은 중요한 정보를 JSON 형식으로 반환합니다:
issuer: 인증 서버의 고유 식별자authorization_endpoint: 사용자가 로그인하는 페이지의 URLtoken_endpoint: 액세스 토큰을 교환하는 URLjwks_uri: 서명 검증을 위한 공개 키 세트 위치scopes_supported: 지원되는 OAuth 2.0 스코프 목록
MCP 커넥터에서의 중요성
MCP(Model Context Protocol) 커넥터는 AI 모델이 외부 도구나 데이터에 접근할 수 있도록 해주는 브릿지 역할을 합니다. 많은 경우, 이 커넥터들은 보안을 위해 OIDC를 사용하여 인증을 처리해야 합니다.
만약 MCP 커넥터가 이 discovery 엔드포인트를 지원한다면, 사용자는 복잡한 설정 대신 Issuer URL 하나만 입력하면 됩니다. 커넥터는 내부적으로 .well-known/openid-configuration을 호출하여 필요한 모든 설정을 자동으로 구성합니다.
이것이 바로 "그냥 작동하게(just work)" 만드는 비결입니다.
결론
.well-known/openid-configuration은 단순한 관례를 넘어, 상호 운용성과 사용자 경험을 극대화하는 강력한 도구입니다. MCP 커넥터를 설계할 때 이 표준을 준수하면, 설정의 복잡성을 획기적으로 줄이고 더 견고한 인증 흐름을 구축할 수 있습니다.