refactor: 문서 개선 중

2026-09-21 14:30:55 +09:00
parent c93cdea150
commit 805a18f486
1497 changed files with 525837 additions and 59152 deletions
@@ -0,0 +1,111 @@
+---
+id: 39fdf472-82c4-43ed-abec-73de672f08ae
+kind: REFERENCE
+slug: authorization-code-endpoint-credential-movement
+title: Authorization Code Flow의 Endpoint와 Credential 이동 기준
+topic: OAuth/OIDC 인증 경계
+project: KeyCloak Patterns
+status: 게시 중
+version: 32
+verifiedOn: 2026-08-25
+studio: "https://hyeonworks.com/studio/documents/39fdf472-82c4-43ed-abec-73de672f08ae/edit"
+public: "https://hyeonworks.com/references/authorization-code-endpoint-credential-movement"
+---
+
+# Authorization Code Flow의 Endpoint와 Credential 이동 기준
+
+Authorization Code Flow에서 브라우저와 client, Authorization Server, Resource Server가 주고받는 값을 endpoint별로 정리한다. 특히 `client_secret`과 authorization code, access token이 어느 요청에 포함되는지를 구분한다.
+
+## 관계
+
+- **SPA에서 토큰을 직접 관리하면서 드러난 Browser Credential 경계**
+  브라우저가 code를 직접 교환하는 흐름에서 endpoint별 이동을 관측했다.
+- **Mediator가 Refresh Token을 관리하고 Access Token을 Browser에 전달하는 구조**
+  confidential client가 token endpoint에서 client 인증을 수행하는 흐름을 보여 준다.
+- **Public Client와 Confidential Client 구분 기준**
+  public/confidential client 구분에 따라 token endpoint의 client 인증 방식이 달라지고, Authorization Code Flow에서는 PKCE 적용 여부도 함께 결정한다.
+
+## 목적
+
+Authorization Endpoint와 Token Endpoint는 역할과 호출 방식이 다르다.
+이 구분을 해야 SPA에서 client_secret이 어디로 갔는지, PKCE가 어느 구간을 지키는지 이해하기 쉽다.
+
+하나는 브라우저의 full-page navigation이고 하나는 server-to-server 호출이 될 수도 있고 browser-to-server 호출이 될 수도 있다.
+노출되는 것도, 인증하는 방법도 다르다.
+
+Authorization Endpoint
+경로 : 브라우저 주소창   남는 곳 : 히스토리·서버 로그·referrer   client 인증 : x
+
+Token Endpoint
+경로 : body와 Authorization 헤더   보내는 쪽 : client 종류에 따라 server 또는 브라우저   client 인증 : o
+
+## 규칙
+
+### 1. Authorization Endpoint에는 client_secret을 보내지 않는다
+
+Authorization request는 브라우저 navigation으로 전송되므로 URL이 주소창과 브라우저 히스토리, Authorization Server 접근 로그에 기록될 수 있고 이후 navigation에서는 Referrer-Policy 설정에 따라 referrer에도 포함될 수 있다. 여기 실리는 값은 client_id, redirect_uri, response_type, scope, state, code_challenge, code_challenge_method다. secret이 필요한 인증은 아직 하지 않는다.
+
+따라서 authorization request URL에는 노출돼도 되는 값만 포함한다.
+
+### 2. Token Endpoint에서 비로소 client를 인증한다
+
+token request는 authorization code와 `redirect_uri`, `code_verifier` 등을 request body로 보내고, confidential client는 `client_secret_basic` 같은 방식으로 token endpoint에서 client 인증도 수행한다.
+
+주소창과 히스토리에 남지 않는다는 뜻이지 어디에도 기록되지 않는다는 뜻은 아니다. 애플리케이션 debug 로그, reverse proxy 로그, tracing과 APM, packet capture에 남을 수 있어서 credential masking을 따로 둔다.
+
+이 요청을 누가 보내는지는 client 종류에 따라 갈린다. server가 보내면 server-to-server이고, secret이 없는 SPA가 보내면 브라우저가 직접 보낸다. token endpoint를 server 안에서만 부르게 하려면 client 종류부터 confidential로 정해야 한다.
+
+### 3. PKCE는 두 요청을 같은 주체에 묶는다
+
+처음 요청에 code_challenge를 담아서 보내고, 교환할 때 원본인 code_verifier를 보내서 이 두개가 일치하는지 확인 한다.
+이 2개가 일치해야 토큰 교환이 되게 된다.
+
+code를 누가 훔쳐 가도 verifier가 없으면 token으로 바꾸지 못한다.
+
+### 4. issuer 검증값과 JWK 조회 주소를 같은 값으로 맞추려 하지 않는다
+
+issuer는 요청을 보내는 주소가 아니라 token의 canonical issuer identifier다. 검증은 발급된 token의 iss claim이 그 값과 같은지를 본다.
+
+JWK 조회 주소는 실제로 공개키를 가져오는 network 경로다. 이 예제에서는 브라우저가 보는 주소와 컨테이너 안에서 닿는 주소가 다르다. 컨테이너 안에서는 자기 localhost가 그 서버가 아니므로 service 이름을 써야 하고, 브라우저는 그 이름에 닿지 못한다.
+
+issuer 검증값과 endpoint 연결 주소는 따로 구성한다. 둘을 하나로 맞추려 하면 로그인 redirect가 깨지거나 서버가 키를 못 가져온다.
+
+### 5. Resource API는 서명만 보고 끝내지 않는다
+
+서명이 맞다는 것은 그 IdP가 발급했다는 뜻일 뿐이다. 같은 IdP가 다른 API용으로 발급한 token도 서명은 맞다.
+
+Resource Server는 서명과 함께 issuer, 유효 시간, audience를 검증한다. 특히 audience를 검증해야 다른 resource를 대상으로 발급된 token을 현재 API에서 받아들이지 않는다.
+
+### 6. redirect_uri는 exact match로 좁힌다
+
+wildcard allowlist는 학습 환경에서 편하다. 다만 허용 범위가 넓으면 같은 호스트의 다른 경로로도 code가 갈 수 있다.
+
+실제로 쓰는 callback 주소만 등록해 두면 code가 도착할 수 있는 곳이 그 하나로 줄어든다.
+
+등록하지 않은 redirect_uri를 보냈을 때 거부하는지 확인하는 검사도 따로 둔다.
+
+### 7. 로그인 구간과 API 호출 구간을 한 줄로 그리지 않는다
+
+로그인 구간은 authorization request에서 시작해 callback과 code 교환을 지나 로그인 상태를 만드는 데까지다. API 호출 구간은 브라우저 입력, 중간 계층의 credential 변환, 보호 자원의 검증, 최종 응답이다.
+
+로그인 구간과 애플리케이션 API 호출 구간은 호출 주체가 다를 수 있으므로 별도로 그린다. 그래야 code 교환 주체와 Resource Server 호출 주체를 각각 확인할 수 있다.
+
+## 적용 조건
+
+- Authorization Code Flow를 쓰는 client를 설정하거나 문서로 설명할 때
+- 브라우저 요청과 server-to-server 요청이 한 흐름에 섞여 있을 때
+- endpoint별로 무엇이 노출되는지 나눠야 할 때
+- PKCE 적용과 client 인증 방식을 정할 때
+
+## 예외
+
+- Client Credentials처럼 사용자 없이 token을 받는 흐름은 Authorization Endpoint를 지나지 않는다.
+- Device Authorization Grant는 브라우저 redirect가 아니라 device code와 user code를 사용하므로 이 문서의 `redirect_uri` 흐름과는 별도로 본다.
+
+## 예시
+
+- authorization request에는 code_challenge_method=S256이 있고 client secret은 없다
+- token request에는 code_verifier가 있다. secret을 가진 client는 이 요청에서 자기를 인증한다
+- expected issuer는 http://localhost:8080/realms/keycloak-patterns 이고 JWK 조회는 컨테이너 network 주소를 쓴다
+- audience에 keycloak-pattern-api 가 없으면 invalid_token 결과가 되어 401이 된다
+- redirect allowlist에 wildcard가 있으면 등록한 host의 다른 경로로도 code가 갈 수 있다