OAuth2 PKCE 구현 가이드: code_verifier/code_challenge, state, redirect URI 실수 줄이기

OAuth2 PKCE 구현 가이드: code_verifier/code_challenge, state, redirect URI 실수 줄이기

PKCE는 SPA/모바일에서 코드 가로채기 리스크를 줄이기 위한 표준이라 검색 수요가 높습니다. 구현에서 가장 많이 깨지는 부분은 인코딩, 저장(새로고침/앱 전환), redirect URI 등록 불일치입니다. 이 글은 PKCE 핵심 파라미터를 실무 체크리스트로 정리합니다.

PKCE는 code_challenge/code_verifier 쌍으로 토큰 교환을 보호합니다.

옵션/핵심 요소(3~6개)

항목	의미	언제 쓰는지(실무 상황)
code_verifier	클라이언트 비밀 문자열	토큰 교환 단계에서 본인 증명
code_challenge	verifier의 변환값(S256)	authorize 요청에 포함
state	CSRF 방지	redirect 응답의 state 검증
redirect URI	복귀 주소	등록값과 완전 일치가 필수
저장 위치	verifier/state 보관	웹은 세션 스토리지, 모바일은 안전 저장소

예시(개념)

// authorize(개념)
response_type=code
code_challenge_method=S256
code_challenge=...
state=...

// token(개념)
grant_type=authorization_code
code=...
code_verifier=...

문제 상황(정확히 1개)

상황: 토큰 교환에서 invalid_grant 또는 PKCE verification failed가 발생한다

원인: authorize 단계에서 만든 code_verifier/state를 올바르게 저장/복원하지 못했거나, challenge 생성/인코딩이 규격과 다르다

해결: code_verifier/state를 플로우 동안 안전하게 보관하고, S256 기반 challenge 생성/인코딩을 RFC대로 맞춘다. redirect URI 등록값을 점검한다

예방 팁: PKCE 플로우를 E2E 테스트로 고정하고, 민감정보 마스킹을 전제로 파라미터를 로깅해 디버깅 시간을 줄인다

참고/출처

• RFC 7636: PKCE
• RFC 6749: OAuth 2.0