문제 해결

오류 코드별 원인과 조치, 사용자에게 표시되는 화면, 자주 묻는 질문, stage 점검 목록, 운영 및 문의 방법을 설명합니다.

상태 확정 · 최종 확인 2026-09-30

---

오류 전달 위치

구분	위치	예시
연동 서비스로 전달 가능한 오류	redirect_uri?error=…&error_description=…&state=…&iss=… (response_type 오류만 fragment #)	사용자 취소, PKCE 누락
전달할 수 없는 오류	통합회원 오류 화면(사용자에게 표시)	미등록 client_id · redirect_uri
토큰 · 폐기 엔드포인트 오류	HTTP 400/401, {"error": "…", "error_description": "…"}	인가 코드 재사용, PKCE 불일치
사용자 정보 조회 오류	HTTP 400(헤더 누락) / 401	만료 · 폐기된 토큰

오류 코드

error	위치	의미	주요 원인	조치
invalid_client	토큰 · 폐기 401 / 인가 요청 시 오류 화면(client is invalid)	클라이언트 인증 실패 또는 미등록 client_id	client_id 오타, stage/prod 값 혼용, 잘못된 client_secret, 재발급 전 시크릿 사용, HTTP Basic 헤더 사용(요청 본문 방식만 지원)	값과 전달 방식을 확인합니다. Basic 헤더 거절은 인가 코드를 소모하지 않으므로 같은 코드로 다시 요청할 수 있습니다
invalid_redirect_uri	오류 화면	등록되지 않은 redirect_uri	마지막 슬래시, http/https, 포트 차이	등록값과 정확히 일치하도록 수정합니다
invalid_request	콜백 / 토큰 400 / 사용자 정보 400 / 로그아웃 오류 화면	요청 형식 오류	code_challenge 누락("Authorization Server policy requires PKCE…"), prompt=none 을 다른 값과 함께 사용("prompt none must only be used alone"), 토큰 요청 필수 파라미터 누락, Authorization 헤더 누락("no access token provided"), 미등록 post_logout_redirect_uri("post_logout_redirect_uri not registered")	파라미터를 확인합니다. nonce · state 누락은 서버가 검사하지 않습니다
unsupported_response_type	콜백 fragment	code 이외의 response_type	response_type=token 등	code 를 사용합니다
invalid_grant	토큰 400	인가 코드 · 리프레시 토큰 오류("grant request is invalid")	인가 코드 60초 초과 · 재사용, code_verifier 불일치, redirect_uri 불일치, 이미 교체된 리프레시 토큰, 사용자의 연결 해제, 탈퇴, 계정 정지	인가 코드는 로그인부터 다시 진행합니다. 리프레시 토큰은 폐기하고 재로그인을 안내합니다
invalid_token	사용자 정보 401	액세스 토큰 만료 · 폐기	발급 후 10분 경과, 폐기된 토큰	토큰을 다시 발급받습니다
access_denied	콜백	사용자가 동의를 거부	동의 화면에서 취소 선택	정상 흐름입니다. 연동 서비스 화면으로 안내합니다
login_required · consent_required	콜백	prompt=none 요청에 로그인 · 동의가 필요("End-User authentication is required")	—	prompt=none 은 권장하지 않습니다. SSO 는 prompt 없이도 화면 없이 처리됩니다
session_not_found	오류 화면	로그인 화면 세션 만료(30분)	로그인 · 동의 화면을 장시간 방치	처음부터 다시 진행합니다. 버튼을 두 번 누른 경우에는 이 오류가 아닌 "이미 처리된 요청입니다" 안내 화면(200)이 표시됩니다

지원하지 않는 scope(profile 등)는 오류가 아니며 무시됩니다. 응답의 scope 에 포함되지 않았다면 요청이 무시된 것입니다.

사용자에게 표시되는 오류 화면

리다이렉트할 수 없는 오류는 통합회원 오류 화면에 다음과 같이 표시됩니다. 오류 코드가 함께 표시되므로, 사용자에게 전달받은 코드로 원인을 확인할 수 있습니다.

요청을 처리할 수 없습니다 사전 등록되지 않은 redirect_uri 입니다. 이용 중인 서비스의 고객센터에 아래 코드를 알려주세요. invalid_redirect_uri

로그인 화면의 제한

연동 코드와 무관하나 고객 문의 대응에 필요한 정보입니다.

상황	표시 문구	해제 시점
비밀번호 오류	이메일 또는 비밀번호가 올바르지 않습니다(계정 존재 여부는 표시하지 않습니다)	—
같은 IP 에서 1분에 5회 실패	잠시 후 다시 시도해 주세요 (N초)	60초. 1시간 안에 반복되면 2분, 4분, 8분으로 증가(최대 60분)
같은 계정 10회 연속 실패	로그인 시도가 너무 많아 잠시 잠겼습니다(안내 메일 발송)	15분
정지된 계정	이용이 정지된 계정입니다. 고객센터로 문의해 주세요	통합회원 운영자 해제
인증 메일 과다 요청(이메일당 15분 3회, IP 당 15분 10회)	인증 메일을 너무 자주 요청했습니다	15분
로그인 · 동의 버튼 중복 선택	이미 처리된 요청입니다(오류가 아닌 안내, HTTP 200). 첫 요청의 결과는 이미 연동 서비스로 전달되었습니다	—

자주 묻는 질문

sub 가 변경되는 경우가 있습니까? 없습니다. 이메일, 비밀번호, 로그인 수단을 변경해도 같습니다. 탈퇴 후 재가입한 경우에만 새 sub 가 발급됩니다.

리프레시 토큰이 발급되지 않습니다.offline_access 와 prompt=consent 를 함께 요청했는지 확인합니다. 응답의 scope 에 offline_access 가 없으면 요청이 무시된 것입니다.

두 번째 로그인에서 화면이 표시되지 않습니다. 정상 동작(SSO)입니다. 재인증이 필요하면 prompt=login 을 사용합니다.

같은 사용자가 웹과 앱에서 다른 sub 를 받습니다. 두 클라이언트가 다른 서비스로 등록되었을 수 있습니다. 담당자에게 확인을 요청합니다. 같은 서비스라면 반드시 같은 값이 발급됩니다.

Chrome 에서만 로그인이 되지 않습니다. 연동 서비스 페이지의 CSP form-action 이 통합회원 도메인이나 콜백 주소를 차단하는지 확인합니다. 브라우저 콘솔에 CSP 위반이 표시됩니다.

로컬(http://localhost)에서 개발할 수 있습니까? stage 클라이언트에 http://localhost:포트/경로 를 등록하면 사용할 수 있습니다. localhost 는 http 를 허용합니다.

로그인 흐름을 CI 에서 자동 테스트할 수 있습니까? 로그인 · 동의 화면(/interaction/…)은 브라우저 전용 내부 구현이며 예고 없이 변경될 수 있으므로, 화면을 스크립트로 제출하는 테스트에 의존하지 않아야 합니다. 자동 테스트는 인가 요청 URL 생성, 콜백 처리(state · 오류), 토큰 요청 · ID 토큰 검증(고정 키로 서명한 테스트 토큰)까지로 한정하고, 실제 화면은 stage 에서 브라우저로 확인합니다.

동의 화면이 표시되지 않습니다. 해당 계정이 이미 서비스에 연결되어 있으면 표시되지 않습니다(서비스 단위). 새 계정으로 가입하거나 prompt=consent 로 확인합니다.

잘못된 code_verifier 로 실패한 후 같은 인가 코드를 다시 사용할 수 있습니까? 사용할 수 있습니다. 실패한 요청은 인가 코드를 소모하지 않으므로 60초 안에 올바른 값으로 다시 요청할 수 있습니다.

테스트 계정을 받을 수 있습니까? 제공하지 않습니다. stage 로그인 화면에서 직접 가입하며, 인증 코드는 실제 메일로 발송됩니다.

동의 화면의 문구를 변경할 수 있습니까? 표시 이름과 로고만 변경할 수 있습니다. 항목, 목적, 보유 기간은 법적 문안으로 고정되어 있습니다.

prompt=create 를 보냈는데 전환 화면이 표시되지 않습니다.login_hint 를 함께 전달했는지 확인합니다. login_hint 가 없으면 가입 화면이 표시됩니다. 해당 브라우저에 통합회원 세션이 있으면 전환 화면 대신 계정 확인 화면이 표시됩니다(정상). 사용자가 "새로 가입"을 선택하면 전환 화면으로 이동하고, "이 계정으로 계속"을 선택하면 최초 연결이면 동의 화면이, 이미 연결되어 있으면 화면 없이 콜백이 전달됩니다. 연동 서비스의 처리는 어느 경우에도 같습니다. — 활용하기 › 기존 회원 연결

사용자가 연결을 해제했는지 어떻게 확인합니까? 사전에 확인할 수는 없습니다. 실시간 통지(백채널 로그아웃 · 웹훅)를 제공하지 않으므로, 토큰 갱신의 400 invalid_grant 또는 사용자 정보 조회의 401 invalid_token 응답으로 확인합니다.

시크릿이 맞는데 토큰 요청이 401 invalid_client 로 실패합니다.Authorization: Basic 헤더로 요청하고 있을 가능성이 높습니다. 통합회원은 요청 본문 방식(client_secret_post)만 지원합니다. 라이브러리의 클라이언트 인증 방식을 client_secret_post 로 설정합니다.

stage 점검 목록

prod 클라이언트 발급 전에 모든 항목을 확인해야 합니다.

• [ ] 디스커버리 요청이 200 으로 응답하고 issuer 가 설정값과 일치
• [ ] 로그인 시 sub 와 email 을 수신하고, sub 접두어가 서비스 접두어(rm_ / fm_ / mb_)와 일치
• [ ] 두 번째 로그인은 화면 없이 완료(SSO)
• [ ] state 불일치 시 콜백에서 거부
• [ ] ID 토큰의 aud · iss · exp · nonce · 서명 검증이 실제로 수행됨(라이브러리 로그 또는 테스트로 확인)
• [ ] 같은 인가 코드로 두 번째 토큰 요청 시 invalid_grant
• [ ] 잘못된 redirect_uri 로 요청 시 오류 화면 표시
• [ ] 최초 연결 사용자에게 동의 화면 표시(새 계정 또는 prompt=consent 로 확인)
• [ ] email_verified 가 false 인 ID 토큰으로는 이메일로 기존 회원을 조회하지 않음(미인증 이메일 테스트 계정으로 확인)
• [ ] sub 로 조회되지 않은 사용자를 이메일 · 가입 입력 정보로 조회한 경우, 기존 방식으로 로그인한 후에만 연결됨
• [ ] nonce · state 를 항상 전송하고, 콜백 · ID 토큰에서 검증
• [ ] 통합회원 토큰이 브라우저 · 앱 저장소에 저장되지 않음
• [ ] (앱) 시스템 브라우저, https 딥링크, 백엔드 토큰 요청 적용
• [ ] 기존 회원 전환(prompt=create&login_hint) 시 전환 화면이 표시되고, 콜백이 현재 로그인된 회원에 연결됨
• [ ] 통합회원에 로그인된 브라우저에서 전환 · 가입을 요청하면 계정 확인 화면이 표시되고, "다른 계정으로 로그인"으로 다른 계정을 연결할 수 있음
• [ ] (가입 버튼을 두는 경우) prompt=create 만 전송하면 통합회원 가입 화면이 표시되고, 가입 후 콜백에서 신규 회원 등록으로 진행됨
• [ ] 로그아웃 후 등록한 post_logout_redirect_uri 로 이동하고 state 가 그대로 전달됨
• [ ] 연결 해제 후 토큰 갱신 시 invalid_grant, 재로그인 시 동의 화면을 거쳐 같은 sub 수신
• [ ] 토큰 · 폐기 요청이 요청 본문 방식(client_secret_post)으로 전송됨
• [ ] 통합회원 로그아웃 후 보관 중이던 리프레시 토큰을 폐기(통합회원이 폐기하므로 갱신 시 invalid_grant)
• [ ] Chrome · Safari · 모바일 브라우저에서 로그인부터 콜백까지 정상 동작
• [ ] 개인정보 처리방침에 제공받는 자 항목 반영

운영

항목	내용
가용성 목표	99.9%. 통합회원 장애 시 신규 로그인은 불가하나, 연동 서비스의 기존 세션은 유지됩니다
정기 점검	등록된 담당자에게 사전 안내하며, 이용이 적은 시간대에 진행합니다
서명키 교체	JWKS 에 새 키 추가, 전환, 기존 키 제거 순으로 진행합니다. kid 기반 키 재조회가 동작하면 별도 작업이 필요하지 않습니다. 클라이언트 시크릿 재발급은 설정하기 › 클라이언트 시크릿을 참고하시기 바랍니다
시크릿 노출	즉시 담당자에게 알려야 합니다. 폐기 · 재발급과 노출 기간의 토큰 발급 이력을 확인합니다
변경 안내	변경 이력에 게시하며, 연동에 영향이 있는 변경은 최소 2주 전에 안내합니다

문의

항목	내용
담당	머니박스 개발실 유원영 · yoo.wonyoung@m-box.com
전달할 정보	환경(stage/prod), client_id, 발생 시각, 오류 코드와 error_description, state 값(있는 경우)
전달하지 않을 정보	client_secret, 토큰, 인가 코드