OAuth 표준 기반 에이전트 등록 프로토콜 auth.md 이해와 구현 가이드

이 글은 AI 에이전트가 사람 대신 서비스에 접근하고 작업을 수행하는 시대에 맞춰 제안된 새로운 인증·등록 방식인 auth.md 프로토콜을 정리한 기술 블로그입니다. 기존의 API 키 중심 인증이 왜 한계에 부딪혔는지, auth.md가 무엇을 해결하려는지, 그리고 OAuth 표준 위에서 어떻게 동작하는지를 개념부터 구현 관점까지 단계적으로 설명합니다. 에이전트 기반 서비스나 API를 운영하는 개발자라면, 앞으로 필요한 인증 구조를 이해하는 데 도움이 될 것입니다.

반응형

---

기존 인증 방식의 한계와 문제점

웹 인증은 오랫동안 “사람이 브라우저 앞에 앉아 있다”는 전제를 기반으로 발전해 왔습니다. 버튼 클릭, 폼 입력, 이메일 인증, API 키 복사 같은 방식이 대표적입니다.
하지만 AI 에이전트가 코드를 작성하고, 이슈를 분류하고, 시스템을 조회·갱신하는 환경에서는 이 모델이 잘 맞지 않습니다.
특히 기존의 API 키 또는 세션 토큰을 에이전트에 직접 부여하는 방식은 다음과 같은 문제를 만듭니다.

• 권한 범위가 넓고 세분화가 어렵다
• 세션 단위 감사(audit)가 힘들다
• 일부 권한만 선택적으로 폐기(revoke)하기 어렵다

이 문제를 해결하기 위해 WorkOS는 에이전트 등록을 표준화한 구조적 대안으로 auth.md를 제안했습니다.

---

auth.md란 무엇인가

auth.md는 서비스가 자신의 도메인에 공개하는 작은 Markdown 파일입니다. 일반적으로 다음 위치에 배포됩니다.

• https://service.com/auth.md

이 파일에는 에이전트가 해당 서비스에 등록하기 위해 알아야 할 정보가 정리되어 있습니다.

• 지원하는 인증/등록 플로우
• 사용 가능한 권한(scope)
• 자격 증명 발급, 감사, 폐기 방식

중요한 점은 Markdown 기반의 평문 문서라는 것입니다.
사람에게는 문서로, 에이전트에게는 기계가 읽을 수 있는 런타임 아티팩트로 동시에 활용됩니다. 에이전트는 auth.md를 읽고, 사람의 개입 없이 스스로 적절한 등록 플로우를 선택해 인증을 진행할 수 있습니다.

---

OAuth 기반 디스커버리 구조

auth.md는 단독으로 동작하지 않습니다. OAuth 표준을 기반으로 한 2단계 디스커버리 구조와 함께 사용됩니다.

1단계: Protected Resource Metadata(PRM)

• 위치: /.well-known/oauth-protected-resource
• 역할: 보호된 리소스(API)를 소개하고, 인증 서버 위치를 안내

API 요청 시 인증이 실패하면, 서비스는 다음과 같은 헤더를 반환합니다.

WWW-Authenticate: Bearer resource_metadata="https://api.service.com/.well-known/oauth-protected-resource"

이를 통해 에이전트는 문서를 찾지 않아도 자동으로 인증 경로를 시작할 수 있습니다.

2단계: Authorization Server Metadata

• 위치: /.well-known/oauth-authorization-server
• 역할: agent_auth 블록을 통해 에이전트 등록에 필요한 엔드포인트 정보 제공

여기에는 다음 정보들이 포함됩니다.

• register_uri
• claim_uri
• revocation_uri
• identity_types_supported

auth.md는 이 디스커버리 경로를 사람이 이해하기 쉬운 설명으로 보완하는 역할을 합니다.

---

두 가지 에이전트 등록 플로우

auth.md는 서비스 상황에 따라 선택할 수 있는 두 가지 주요 등록 플로우를 정의합니다.

---

에이전트 검증 플로우 (Agent Verified Flow)

이 방식은 에이전트의 아이덴티티 제공자가 사용자 신원을 보증합니다.
예를 들어 OpenAI, Anthropic, Cursor 같은 플랫폼이 여기에 해당합니다.

동작 흐름

1. 에이전트가 사용자에게 신원 위임에 대한 동의를 받음
2. 제공자로부터 대상 서비스 전용 ID-JAG 발급
3. 에이전트가 /agent/auth 엔드포인트로 ID-JAG 전송
4. 서비스가 서명(JWKS)과 클레임(aud, exp, iat, jti 등)을 검증
5. 즉시 자격 증명(access token) 발급

특징

• 사람 개입 없음
• 이메일·OTP 절차 불필요
• 세션 단위 위임 기록 생성
• 제공자가 언제든 위임을 폐기 가능

단, 이 플로우에서는 리프레시 토큰을 발급하지 않는 것이 필수 조건입니다. 접근 연장이 필요하면 에이전트는 새로운 ID-JAG를 다시 제시해야 합니다.

---

사용자 클레임 플로우 (User Claimed Flow)

이 방식은 OTP 기반 인증으로, 에이전트 제공자와의 연동이 필요 없습니다.
이메일을 통해 사용자가 직접 소유권을 확인합니다.

1) 익명 시작(Anonymous Start)

• 에이전트가 신원 없이 먼저 등록
• 제한된 사전 권한으로 즉시 작업 가능
• 이후 OTP 인증으로 사용자와 바인딩
• 자격 증명은 유지되고, 권한만 업그레이드

2) 이메일 필수(Email Required)

• 등록 시 사용자 이메일 필수
• OTP 인증 완료 전까지 자격 증명 미발급
• 사전 접근 자체가 허용되지 않는 경우에 적합

주요 엔드포인트

• POST /agent/auth/claim : OTP 이메일 발송
• POST /agent/auth/claim/complete : OTP 제출 및 검증

---

자격 증명 발급과 사용 방식

서비스는 상황에 따라 access token 또는 API key를 선택해 발급할 수 있습니다.

• 공통 사용 방식
• Authorization: Bearer <credential>

유형별 특징

• access token
  • ID-JAG 플로우에서 사용
  • 만료 시 새 ID-JAG 필요
• api_key
  • OTP 기반 플로우에서 사용
  • 기본적으로 만료 없음
  • 클레임 완료 후 권한만 확장

이 구조를 통해 자격 증명은 사용자에 귀속되고, 범위가 명확하며, 독립적으로 폐기 가능해집니다.

---

사용자 매칭과 감사(Audit) 전략

자격 증명을 발급할 때 서비스는 이를 어떤 사용자 계정과 연결할지 결정해야 합니다. 권장되는 우선순위는 다음과 같습니다.

1. 기존 위임 기록의 (iss, sub) 매칭
2. 검증된 이메일 주소 매칭
3. 정책에 따른 JIT(Just-In-Time) 사용자 생성 또는 거부

또한 보안과 사고 대응을 위해 다음과 같은 이벤트 로그를 남기는 것이 권장됩니다.

• REGISTRATION.CREATED
• CLAIM.REQUESTED
• CLAIM.CONFIRMED
• REGISTRATION.EXPIRED
• REGISTRATION.REVOKED

ID-JAG 플로우의 경우 iss, sub, agent_platform 정보를 함께 기록하면 제공자 로그와의 상관 분석이 쉬워집니다.

---

auth.md 도입을 위한 최소 구현 체크리스트

서비스에 auth.md를 도입하려면 최소한 다음을 준비해야 합니다.

1. 서비스 루트에 auth.md 배포
2. /.well-known/oauth-protected-resource 공개
3. 모든 401 응답에 WWW-Authenticate 헤더 반환
4. /agent/auth 엔드포인트 구현
5. OTP 플로우용 /claim, /claim/complete 구현
6. ID-JAG 검증을 위한 제공자 신뢰 목록과 JWKS 검증 로직 구축

---

728x90

auth.md는 단순한 문서가 아니라, 에이전트 시대에 맞는 등록·인증의 공통 언어입니다.
OAuth 표준을 그대로 활용하면서도, 사람 중심 인증 모델의 한계를 넘어 에이전트가 스스로 등록하고, 감사 가능하며, 안전하게 폐기 가능한 구조를 제시합니다.
앞으로 에이전트 기반 API와 자동화 서비스가 늘어날수록, 이런 표준화된 접근 방식은 선택이 아니라 필수 인프라가 될 가능성이 큽니다. auth.md는 그 출발점으로서 충분한 실용성과 확장성을 보여주고 있습니다.

300x250

https://www.marktechpost.com/2026/05/25/workos-releases-auth-md-an-open-agent-registration-protocol-built-on-oauth-standards/?fbclid=IwY2xjawSB2e5leHRuA2FlbQIxMQBzcnRjBmFwcF9pZBAyMjIwMzkxNzg4MjAwODkyAAEeV76aamfuk0DB1Yp7eiBuQpisaP5i60MvOL9Y27Owh7HtGVTj6UQqJ4SnNmY_aem_fKwiP7X8q7u3MD9JzLGwhA

WorkOS Releases auth.md: An Open Agent Registration Protocol Built on OAuth Standards