--- title: Runbook — AUTH_CLAIM_MAPPING_FAILED (클레임 매핑 실패) category: AUTH error_codes: [AUTH_CLAIM_MAPPING_FAILED] severity: P2 owner: oncall last_updated: 2026-11-13 status: 초안 --- # Runbook: AUTH_CLAIM_MAPPING_FAILED (`runbook://auth/claim-mapping-failed`) ## 증상 - HTTP 401, `error.code=AUTH_CLAIM_MAPPING_FAILED`, `WWW-Authenticate: Bearer error="invalid_token"`. - WARN 로그 줄 `security failure: code=AUTH_CLAIM_MAPPING_FAILED category=AUTH method=… path=…`(logger `AuthErrorResponseWriter`). - 서명·issuer·audience·만료 검증은 통과했지만 principal을 만들 수 없다: `sub` claim이 없거나 비었다, 또는 `tenant_id` claim이 있는데 tenant 문법(`TenantId.GRAMMAR`)에 맞지 않는다(`JwtToAuthenticatedPrincipalConverter`). - 역할 claim이 없는 것은 이 코드가 아니다. 역할 없는 사용자는 인증되고, 권한이 필요한 쓰기에서 403 `AUTHZ_INSUFFICIENT_PERMISSION`이 된다. ## 진단 - 토큰·`Authorization` 헤더·JWT payload는 로그에 남지 않고 남겨서도 안 된다. 클라이언트 쪽에서 token을 받아 `sub`와 `tenant_id`를 본다. - claim 이름은 코드에 고정돼 있다: `sub`, `tenant_id`, 역할은 `realm_access.roles`와 자기 client(`app.security.audience`)의 `resource_access..roles`. 따로 고칠 claim 대응 설정은 없다. ## 조치 - IdP token 템플릿이 `sub`를 넣는지, `tenant_id`를 넣는다면 문법에 맞는 값인지 고친다. - IdP가 tenant를 다른 claim에 둔다면 IdP 쪽 mapper로 `tenant_id`에 옮긴다. ## 에스컬레이션 - IdP가 claim 스키마를 바꿨으면 인증 플랫폼 팀에 넘긴다. > 이력: 2026-11-12 리뷰 전에는 `sub` 없는 token이 통과해 뒤에서 500이 됐고, 틀린 tenant claim은 > `AUTH_TOKEN_MALFORMED`였다. --- > **초안**: 서비스가 도메인을 채운 뒤 본문을 쓴다.