표준 클레임
표준 클레임 (Standard Claims)
사용자 이름, 이메일, 프로필 사진 같은 정보를 앱마다 제각각 다른 키 이름으로 내려주면 받는 쪽이 매번 파싱 로직을 새로 짜야 해요. OpenID Connect는 이런 혼란을 막기 위해 **표준 클레임(Standard Claims)**이라는 공통 키 이름들을 정의해요. 이 클레임들은 UserInfo 응답이나 ID 토큰 어느 쪽으로든 요청해 받을 수 있어요. 이 글에서는 표준 클레임이 어떤 것들이 있고 각각 무엇을 뜻하는지 살펴볼게요.
본문
표준 클레임은 스펙이 정의해 두고, 필요하면 UserInfo 응답이나 ID 토큰에서 돌려받도록 요청할 수 있어요. 아래는 등록된 주요 표준 클레임들이에요.
신원·이름 관련
| 클레임 | 타입 | 설명 |
|---|---|---|
sub |
string | 발급자에서의 최종 사용자 주체 식별자(Subject Identifier). |
name |
string | 전체 이름을 표시 가능한 형태로. 제목·접미사 포함이 가능하고 사용자 로케일·선호도 순서를 따르는 이름이에요. |
given_name |
string | 사용자의 이름(given name) 부분. 문화에 따라 여럿일 수 있고 공백으로 구분해 모두 포함할 수 있어요. |
family_name |
string | 사용자의 성(family name) 부분. 여럿이거나 없을 수도 있어요. |
middle_name |
string | 사용자의 중간 이름(들). 문화에 따라 안 쓸 수도 있어요. |
nickname |
string | 캐주얼한 이름. given_name이 Michael일 때 Mike처럼 다를 수 있어요. |
preferred_username |
string | RP에서 사용자를 부르고 싶어하는 축약 이름(예: janedoe, j.doe). 유일함을 보장하진 않아요. |
birthdate |
string | 생년월일. ISO 8601 YYYY-MM-DD 형식이고, 연도만 YYYY로도 쓸 수 있어요. |
프로필·연락처 관련
| 클레임 | 타입 | 설명 |
|---|---|---|
profile |
string | 사용자 프로필 페이지 URL. |
picture |
string | 프로필 사진 URL. PNG·JPEG·GIF 같은 이미지 파일이어야 하고, 페이지가 아니라 이미지여야 해요. |
website |
string | 사용자의 웹 페이지나 블로그 URL. |
email |
string | 선호 이메일 주소. RFC 5322 addr-spec 문법을 따라야 하고 유일성을 보장하진 않아요. |
email_verified |
boolean | 이메일 주소가 검증되었으면 true, 아니면 false. true란 OP가 해당 이메일을 사용자가 통제한다는 걸 확인하는 절차를 밟았다는 뜻이에요. |
phone_number |
string | 선호 전화번호. E.164 형식을 권장해요(예: +1 (425) 555-1212). |
phone_number_verified |
boolean | 전화번호 검증 여부. true면 phone_number는 반드시 E.164 형식이어야 해요. |
gender |
string | 성별. 스펙에서 정의한 값은 female과 male이고, 해당 없으면 다른 값을 쓸 수 있어요. |
locale |
string | 사용자 로케일. BCP47 언어 태그(예: en-US, fr-CA)예요. |
zoneinfo |
string | IANA 타임존 데이터베이스의 타임존 문자열(예: Europe/Paris). |
address |
JSON object | 선호 우편 주소. Core 스펙 5.1.1절(Address Claim)의 일부 또는 전체 멤버를 담을 수 있어요. |
updated_at |
number | 사용자 정보가 마지막으로 갱신된 시각(UTC 기준 초 단위). |
사용 시 주의할 점
preferred_username과 email처럼 값이 유일하지 않을 수 있는 클레임은 RP가 그걸 사용자 식별의 근거로 삼으면 안 돼요. 그리고 클레임이 돌아오는 경로(Id Token이든 UserInfo든)에 따라 일부 규칙이 달라질 수 있어요.
더 알아보기
- 주소가 어떤 하위 멤버들로 이루어지는지는 Core 스펙의 5.1.1절 Address Claim을 참고해요.
- 클레임을 스코프 값으로 요청하는 방법은 Core 스펙의 5.4절을 참고해요.
- ID 토큰에 항상 들어가는 공통 클레임(
iss,sub,aud,exp등)은 ID 토큰 (ID Token) 문서를 참고해요.