Keycloak Authorization Code Flow — 왜 2단계인가

Keycloak 은 로그인과 토큰 발급을 대신 처리해 주는 오픈소스 인증 서버(Identity Provider)입니다.

OAuth2/OIDC 의 Authorization Code Flow 를 보면 궁금해집니다. 로그인에 성공했으면 그냥 토큰을 주면 될 텐데, 왜 code 를 먼저 주고 그걸 다시 토큰으로 교환하는 2단계일까요.

흐름

브라우저 → Keycloak 로그인 (ID/PW·소셜)
   ↓  Keycloak 세션 쿠키 발급(SSO용)
브라우저 → redirect_uri?code=ABC123      ← Authorization Code 전달
   ↓
서버 → Keycloak 토큰 엔드포인트로 code + client_secret 전송
   ↓
Keycloak → Access Token(JWT) + Refresh Token

브라우저는 로그인 후 code 만 받습니다. 그 code 를 서버가 받아, 뒤에서 client_secret 과 함께 토큰으로 바꿉니다.

짧고 1회용인 code

Authorization Code 는 “이 사용자는 인증에 성공했다” 는 1회용 티켓입니다. 유효기간이 매우 짧고(보통 1분), 한 번 쓰면 만료됩니다. 그 자체엔 사용자 정보나 권한이 안 담겨 있습니다. 오직 토큰 교환 용도로만 씁니다.

왜 토큰을 바로 안 주나 — URL 유출

Access Token 을 브라우저 URL(리다이렉트)에 바로 실으면 새어 나갑니다.

• 브라우저 히스토리에 URL 이 남습니다.
• 서버·프록시 접근 로그에 URL 이 찍힙니다.
• 다음 페이지로 넘어갈 때 Referer 헤더에 URL 이 실려 나갑니다.

Access Token 은 API 접근 권한 그 자체(JWT, 안에 roles·exp 포함)라, 이게 새면 그대로 도용됩니다. 그래서 URL 에는 짧고 1회용이라 새도 덜 위험한 code 만 싣고, 진짜 토큰은 서버가 뒤에서 받습니다.

그리고 code 를 토큰으로 바꿀 때 client_secret 이 필요합니다. 이건 서버만 아는 값이라, code 를 가로챈 쪽이 있어도 secret 없이는 토큰으로 못 바꿉니다. 브라우저(공개된 곳)에는 secret 을 두지 않는다는 원칙과 맞물립니다.

ID Token vs Access Token — 역할 차이

OIDC 를 얹으면 토큰이 둘로 나뉩니다.

• ID Token — “누구인가”(신원). 로그인한 사용자가 누군지 담습니다.
• Access Token — “무엇을 할 수 있나”(권한). API 접근 인가에 씁니다.

신원 확인과 권한 부여를 다른 토큰으로 분리한 겁니다.

2단계의 이유 — URL 노출 회피

Authorization Code Flow 가 2단계인 건 토큰을 URL 에 노출하지 않으려고 입니다. 새도 덜 위험한 짧은 code 를 앞단에 두고, 진짜 토큰은 client_secret 을 쥔 서버가 뒤에서 교환합니다. “왜 한 번에 안 주지?” 의 답은 “URL 은 여러 경로로 샌다” 입니다.