7.1 KiB
id, kind, slug, title, topic, project, status, version, verifiedOn, studio, public
| id | kind | slug | title | topic | project | status | version | verifiedOn | studio | public |
|---|---|---|---|---|---|---|---|---|---|---|
| 39fdf472-82c4-43ed-abec-73de672f08ae | REFERENCE | authorization-code-endpoint-credential-movement | Authorization Code Flow의 Endpoint와 Credential 이동 기준 | OAuth/OIDC 인증 경계 | KeyCloak Patterns | 게시 중 | 32 | 2026-08-25 | https://hyeonworks.com/studio/documents/39fdf472-82c4-43ed-abec-73de672f08ae/edit | 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가 갈 수 있다