Claude Code를 Auth0 API와 통합하는 방법

AI 에이전트가 사용자의 Auth0 테넌트에 실시간으로 접근할 수 있다는 사실을 알고 계셨나요? 정적 분석(static analysis)으로는 절대 찾아낼 수 없는 버그를 잡아낼 수 있습니다. 저는 Claude Code에게 의도적으로 순진한 Flask 앱과 Auth0 MCP Server를 제공했고, 이 에이전트는 제 테넌트가 이미 서명 키(signing keys)를 로테이션하고 있지만 제 앱은 첫 번째 키만을 신뢰한다는 사실을 발견했습니다. 그 결과 완벽하게 유효한 토큰들이 현재 실패하고 있었습니다. 심지어 저의 부정확한 프롬프트 중 하나에 대해서는 맹목적으로 따르기보다 반박하는 모습까지 보여주었습니다.

본 기사에서는 전체 설정 과정과, 제가 에이전트에게 그렇게 많은 접근 권한을 부여하면서도 안심할 수 있게 해준 가드레일(guardrails)들을 안내합니다. 바로 최소 권한 범위(least-privilege scopes), 정적 시크릿 대신 디바이스 인증(device auth), 그리고 제약 조건을 인코딩하는 CLAUDE.md 파일입니다.

인증(Authentication)과 권한 부여(authorization)는 거의 모든 웹 애플리케이션의 핵심 부분이면서, 변화가 가장 자주 일어나는 영역이기도 합니다. 개발자들은 새로운 기능을 위해 토큰 만료 설정, 콜백 URL, 또는 API 권한을 정기적으로 업데이트합니다. 이러한 변경 사항 자체는 보통 작지만, 이를 처리하는 워크플로우는 그렇지 않습니다. 사소한 업데이트를 진행하기 위해서 에디터, Auth0 대시보드, 문서를 오가야 합니다. 점점 더 그 에디터는 Claude Code와 같은 코딩 에이전트가 되고 있으며, 이는 'Claude CLI를 벗어나지 않고도 이러한 업데이트를 처리할 수 있다면 어떨까?'라는 질문을 제기합니다.

Claude Code는 터미널 기반의 AI 에이전트(VS code 확장으로도 사용 가능)로, Auth0의 Management API를 네이티브 타사 도구로 노출하는 Auth0 MCP Server와 결합할 수 있습니다. 이러한 조합은 코드베이스 전체와 Auth0 테넌트에 걸쳐 완벽한 컨텍스트를 가지고 인증 통합을 스캐폴딩(scaffold), 리팩토링(refactor), 업데이트해 줄 수 있는 비서 역할을 제공합니다. 하지만 AI 에이전트에게 민감한 인증 인프라에 대한 접근 권한을 부여하는 것은 당연히 질문을 던집니다. '새로운 보안 위험을 열지 않으면서 어떻게 할 수 있을까?'

이 튜토리얼에서는 Claude Code를 Auth0 MCP Server와 연동하고, 범위가 지정된(scoped) 기계 대 기계 자격 증명 흐름을 생성하며, AI 에이전트가 인증 계층과 안전하게 상호 작용할 수 있도록 보안 가드레일을 설정하는 방법을 다룹니다.

Claude Code와 Auth0 MCP의 작동 방식

사용자의 목표에 따라 Claude Code는 여러 단계(코드 읽기/쓰기, 셸 명령어 실행 등)를 자율적으로 수행하며, 인간 검토가 필요한 결정 지점에서 확인을 요청합니다.

Auth0 MCP Server는 Model Context Protocol (MCP)을 구현하여 Auth0의 Management API를 모든 호환 가능한 AI 에이전트가 직접 호출할 수 있는 일련의 도구로 노출합니다. Claude Code는 원시 HTTP 요청을 구성하거나 API에 대한 잠재적으로 오래된 훈련 데이터에 의존하는 대신, 타입이 지정된 입력과 출력을 가진 잘 정의된 도구를 호출합니다. MCP Server가 Management API 호출을 처리하며, 에이전트는 부여한 권한 내에서 엄격하게 작동합니다. 만약 read-only 모드로 실행하면, 코딩 에이전트는 Auth0 테넌트에서 어떠한 변경도 할 수 없습니다.

두 기술은 함께 인증 워크플로우를 코드에 더 가깝게 가져옵니다. Claude Code는 애플리케이션과 Auth0 테넌트를 모두 이해하고, 단일 세션 내에서 이들 사이를 작업할 수 있습니다.

범위가 지정된 접근 권한을 가진 Auth0 MCP Server 설정

Claude Desktop, Cursor, Windsurf 외에도 Auth0 MCP 서버는 Claude와 원활하게 작동합니다.

전제 조건

이 튜토리얼을 완료하려면 다음이 필요합니다:

전제 조건

이 튜토리얼을 완료하려면 다음이 필요합니다:

• Node.js v18 이상 (node --version으로 확인)
• 설치된 Claude Code CLI
• 대상 테넌트에서 관리자 권한을 가진 활성 Auth0 계정
• 테넌트 도메인 (예: dev-xxxx.us.auth0.com)
• 참고용 GitHub 저장소의 데모 코드 (선택 사항).

설치 및 초기화

전용 작업 디렉토리를 생성합니다:

mkdir Claude-Code-With-Auth0-MCP && cd Claude-Code-With-Auth0-MCP  

그 다음

Auth0 MCP 서버는 정적인 API 키나 클라이언트 시크릿 대신 OAuth 2.0 디바이스 인증 흐름(Device Authorization Flow) (RFC 8628)을 사용합니다. 정적 시크릿은 어딘가에 존재해야 하므로(일반적으로 설정 파일이나 .env 파일), 소스 제어에서 노출될 위험이 있습니다. OAuth 액세스 토큰은 이를 우회합니다. 이들은 위임된 권한을 나타내고, 제한된 스코프를 가지며, 자동으로 만료됩니다. 디바이스 인증 흐름은 토큰 발급에 인간의 로그인 단계를 추가하여, 대화형 세션과 연결된 감사 추적(audit trail) 및 Auth0 대시보드에서의 즉각적인 취소 기능을 제공합니다. MCP 서버는 결과로 나온 토큰을 OS 키체인에 저장하므로 소스 제어에 절대 접근하지 않습니다.

단점은 이 흐름이 브라우저 기반의 로그인 단계를 필요로 하므로 CI 파이프라인에는 적합하지 않다는 것입니다. 비대화형 액세스의 경우, 클라이언트 자격 증명을 사용한 스코프가 지정된 M2M(Machine-to-Machine) 애플리케이션이 더 적합합니다.

MCP 서버 스코핑 (Scoping the MCP server)

Auth0 MCP 서버는 기본적으로 어떠한 스코프도 부여하지 않습니다. --scopes 플래그를 사용하여 초기화 시점에 명시적으로 요청해야 합니다. 이 튜토리얼 데모의 경우, 모든 스코프가 init 과정 중에 선택되었습니다. 더 목표 지향적인 설정을 위해서는 필요한 것을 정확히 지정할 수 있습니다:

# 모든 읽기 권한 부여  
npx @auth0/auth0-mcp-server init --scopes 'read:*'

...

스코프는 관리 API(Management API) 작업에 직접 매핑됩니다. 예를 들어, read:clients는 에이전트가 auth0_get_application을 호출할 수 있게 하며, create:actions는 auth0_create_action을 호출할 수 있게 합니다. 일부 스코프는 중요한 의미를 가집니다. update:actions는 사용자 지정 코드를 프로덕션에 푸시할 수 있으며, read:logs는 상세한 사용자 활동 및 인증 이벤트를 노출합니다. 더 자세한 내용은 스코프 참고 자료를 참조하십시오.

이 튜토리얼에서는 모든 스코프(scope)를 init 단계에서 데모용으로 부여했습니다. 하지만 애플리케이션을 코딩할 때는 최소 권한의 원칙(principle of least privilege)을 따라 실제로 워크플로우가 필요로 하는 것만 부여해야 합니다.

Claude Code와 Auth0 통합하기

Auth0 MCP Server를 Claude Code에 통합하려면, Claude-Code-With-Auth0-MCP 디렉토리 내에서 다음 명령어를 실행하십시오:

$ claude mcp add auth0 -- npx -y @auth0/auth0-mcp-server run  

다음과 유사한 출력을 볼 수 있습니다:

Added stdio MCP server auth0 with command: npx -y @auth0/auth0-mcp-server run to local config  
File modified: /home/<user-name>/.claude.json [project: /path-to/Claude-Code-With-Auth0-MCP]  

참고: --scope local/project/user는 Claude Code 플래그이며, MCP 서버 설정이 어디에 표시되는지를 제어합니다: 현재 프로젝트만, 팀 전체에서 공유, 또는 모든 프로젝트입니다. 이 튜토리얼의 경우, 로컬(기본값)이 적절한 선택입니다.

이렇게 하면 Auth0 MCP Server 구성 블록이 ~/.claude.json에 추가됩니다:

"mcpServers": {  
    "auth0": {  
        "type": "stdio",  
...

대안으로, 구성 JSON을 수동으로 생성하여 claude mcp add-json으로 등록할 수도 있습니다.

자격 증명(Credentials)은 이 JSON에 저장되지 않습니다. MCP 서버는 시작 시 OS 키체인에서 토큰을 읽습니다. 디버그 로깅을 활성화하려면 env 블록에 `

Claude Code 프로젝트에 컨텍스트 제공하기: CLAUDE.md

CLAUDE.md는 프로젝트 루트에 위치한 마크다운 파일로, Claude Code가 세션 시작 시마다 읽습니다. 이 파일은 에이전트에게 자신이 어떤 종류의 프로젝트에서 작업하고 있는지, 어떤 제약 조건이 적용되는지, 그리고 민감한 파일들이 어디에 있는지 알려줍니다. 이것이 없으면, Claude Code는 환경 전반에 걸쳐 공유되는 콜백 URL을 업데이트하거나 보안 정책이 허용하는 범위를 넘어 더 넓은 스코프를 부여하는 등 기술적으로는 정확하지만 컨텍스트상으로는 잘못된 변경을 할 수 있습니다.

Auth0 프로젝트의 좋은 CLAUDE.md에는 다음 내용들이 포함되어야 합니다:

## Auth0 Context  
- Active tenant: dev-xxxx.us.auth0.com (development only)  
- Auth-sensitive files: src/auth/config.ts, .env.local  
...

이것을 설정해두면, Claude Code는 사람이 동료에게 자연스럽게 적용할 것과 같은 가드레일(guardrails)을 가지고 작동합니다. 실제 예시는 데모 프로젝트의 CLAUDE.md에서 확인하실 수 있습니다.

Claude CLI를 사용한 Auth0 통합 리팩토링하기

이 워크플로우를 실제로 시연하기 위해, 이 예시는 단일 보호 엔드포인트(/api/protected)를 가진 최소한의 Flask 앱을 사용합니다. 이는 python-jose를 사용하여 Auth0 JWT 토큰을 검증합니다. 작동은 하지만, 실제 코드베이스에서 흔히 발생하는 여러 문제가 있습니다: 시작 시 한 번만 가져오고 절대 새로 고치지 않는 JWKS, 서명 키를 선택할 때 kid 매칭이 없는 경우, 모든 검증 오류를 동일하게 처리하는 빈 except, 그리고 모듈 레벨 전역 변수로 저장된 Auth0 설정입니다.

# 시작 시 한 번만 가져오는 JWKS — 새로 고치지 않음  
JWKS = requests.get(f

이 [전체(최적화되지 않은/순진한) 구현은 GitHub](https://github.com/manishh/Claude-Code-With-Auth0-MCP/blob/suboptimal-implementation)\(https://github.com/manishh/Claude-Code-With-Auth0-MCP/blob/suboptimal-implementation\)에 있습니다. 이 코드는 Claude Code와 Auth0 MCP를 사용하여 반복적으로 수정하고 개선할 예정입니다.

### Auth0 설정 및 보호된 API

Auth0 측에서는 식별자(`https://mh-test-api.example.com`)가 지정된 [API](https://auth0.com/docs/get-started/auth0-overview/set-up-apis) (리소스 서버) 하나가 필요합니다. 이 식별자 URI는 앱 내에서 고유해야 하지만, 실제로 해석될 필요는 없습니다。

![Auth0: Claude Demo API](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fimages.ctfassets.net%2F23aumh6u8s0i%2F6Ud6f4PCL7ebeZL3ihfNAE%2Fa087d73acde6664634a5cc9955314e6d%2FAuth0Claude_Demo_API.png)