ID 토큰 클레임 참조
ID 토큰은 JWT(JSON 웹 토큰)입니다. V1.0 및 v2.0 ID 토큰은 전달되는 정보의 양에 차이가 있습니다. 이 버전은 요청된 위치의 엔드포인트를 기준으로 합니다. 기존 애플리케이션에서 Azure AD v1.0을 사용하는 경우 새 애플리케이션은 v2.0 엔드포인트를 사용해야 합니다.
- v1.0:
https://login.microsoftonline.com/common/oauth2/authorize - v2.0:
https://login.microsoftonline.com/common/oauth2/v2.0/authorize
다음 섹션에서 나열된 모든 JWT 클레임은 달리 명시되지 않는 한 v1.0 및 v2.0 토큰 모두에 표시됩니다. ID 토큰은 헤더, 페이로드, 서명으로 구성됩니다. 헤더와 서명을 사용하여 토큰의 신뢰성을 확인할 수 있으며, 페이로드에는 클라이언트가 요청한 사용자에 관한 정보가 포함됩니다.
헤더 클레임
다음 표에서는 ID 토큰에 있는 헤더 클레임을 보여 줍니다.
| 클레임 | 서식 | 설명 |
|---|---|---|
typ |
문자열 - 항상 "JWT" | 토큰이 JWT 토큰임을 나타냅니다. |
alg |
문자열 | 토큰을 서명하는 데 사용된 알고리즘을 나타냅니다. 예: "RS256" |
kid |
문자열 | 토큰의 서명 유효성을 검사하는 데 사용할 수 있는 공개 키의 지문을 지정합니다. v1.0 및 v2.0 ID 토큰으로 내보냅니다. |
x5t |
문자열 | 사용 및 값에서 kid와 동일하게 작동합니다. x5t는 호환성을 위해 v1.0 ID 토큰으로만 내보내는 레거시 클레임입니다. |
페이로드 클레임
다음 표에는 기본값으로 대부분의 ID 토큰에 있는 클레임이 표시됩니다(명시된 경우 제외). 그러나 사용자의 앱은 선택적 클레임을 사용하여 ID 토큰의 추가 클레임을 요청할 수 있습니다. 선택적 클레임은 groups 클레임부터 사용자의 이름에 대한 정보까지 다양할 수 있습니다.
| 클레임 | 서식 | 설명 |
|---|---|---|
aud |
문자열, 앱 ID GUID | 토큰의 의도한 수신자를 식별합니다. id_tokens에서 액세스 토큰에서 대상은 Azure Portal에서 앱에 할당된 앱의 애플리케이션 ID입니다. 이 값의 유효성을 검사해야 합니다. 앱의 애플리케이션 ID와 일치하지 않는 경우 토큰을 거부해야 합니다. |
iss |
문자열, 발급자 URI | 토큰을 생성하고 반환하는 발급자 또는 “권한 부여 서버”를 식별합니다. 또한 사용자가 인증된 테넌트도 식별합니다. v2.0 엔드포인트에서 토큰을 발급한 경우 URI는 /v2.0에서 종료됩니다. 사용자가 Microsoft 계정의 소비자 사용자임을 나타내는 GUID는 9188040d-6c67-4c5b-b112-36a304b66dad입니다. 앱은 클레임의 GUID 부분을 사용하여 앱에 로그인할 수 있는 테넌트 집합을 제한할 수 있습니다(해당되는 경우). |
iat |
int, UNIX 타임스탬프 | 이 토큰의 인증이 발생한 시기를 식별합니다. |
idp |
문자열, 대개 STS URI입니다. | 토큰의 주체를 인증한 ID 공급자를 기록합니다. 이 값은 사용자 계정이 발행자(예: 게스트)와 동일한 테넌트에 속하지 않는 경우 발행자 클레임의 값과 동일합니다. 클레임이 없는 경우 iss 값을 대신 사용할 수 있음을 의미합니다. 조직 컨텍스트(예: 테넌트에 초대된 개인 계정)에서 사용되는 개인 계정의 경우, idp 클레임은 ‘live.com’ 또는 Microsoft 계정 테넌트 9188040d-6c67-4c5b-b112-36a304b66dad가 포함된 STS URI일 수 있습니다. |
nbf |
int, UNIX 타임스탬프 | 그 전에는 처리를 위해 JWT를 수락할 수 없는 시간을 식별합니다. |
exp |
int, UNIX 타임스탬프 | 만료 시간을 식별합니다. 이 시간 또는 이후에는 처리를 위해 JWT 토큰을 수락할 수 없습니다. 특정 상황에서는 리소스가 이 시간 전에 토큰을 거부할 수 있습니다. 예를 들어 인증 변경이 필요하거나 토큰 해지를 탐지한 경우입니다. |
c_hash |
문자열 | 코드 해시는 OAuth 2.0 권한 부여 코드와 함께 ID 토큰이 발급된 경우에만 ID 토큰에 포함됩니다. 이 코드 해시는 인증 코드의 신뢰성이 유효한지 검사하는 데 사용할 수 있습니다. 이 유효성 검사를 수행하는 방법을 이해하려면 OpenID Connect 사양을 참조하세요. 이 클레임은 /token 엔드포인트의 ID 토큰에 대해 반환되지 않습니다. |
at_hash |
문자열 | 액세스 토큰 해시는 OAuth 2.0 액세스 토큰을 사용하여 /authorize 엔드포인트에서 ID 토큰이 발급된 경우에만 ID 토큰에 포함됩니다. 액세스 토큰의 신뢰성이 유효한지 검사하는 데 사용할 수 있습니다. 이 유효성 검사를 수행하는 방법을 이해하려면 OpenID Connect 사양을 참조하세요. 이 클레임은 /token 엔드포인트의 ID 토큰에 대해 반환되지 않습니다. |
aio |
불투명 문자열 | 토큰을 다시 사용하기 위해 데이터를 기록하는 데 사용하는 내부 클레임입니다. 무시됩니다. |
preferred_username |
문자열 | 사용자를 나타내는 기본 사용자 이름입니다. 메일 주소, 전화 번호 또는 지정된 형식이 없는 일반 사용자 이름일 수 있습니다. 해당 값은 변경 가능하며 시간이 지남에 따라 변경될 수 있습니다. 이 값은 변경 가능하므로 권한 부여 결정을 내리는 데 사용할 수 없습니다. 사용자 이름 힌트 및 사람이 읽을 수 있는 UI에서 사용자 이름으로 사용할 수 있습니다. profile 범위는 이 클레임을 받기 위해 필요합니다. v2.0 토큰에만 표시됩니다. |
email |
문자열 | 이메일 주소가 있는 게스트 계정에 대해 기본적으로 제공됩니다. 사용자 앱은 email선택적 클레임을 사용하여 관리되는 사용자(리소스와 동일한 테넌트의 사용자)에 대한 이메일 클레임을 요청할 수 있습니다. 이 값은 정확하지 않을 수 있으며 시간이 지남에 따라 변경될 수 있습니다. 권한 부여나 사용자의 데이터 저장에 절대 사용하지 마세요. 앱에 주소 지정 가능한 이메일 주소가 필요한 경우 이 클레임을 제안으로 사용하거나 UX에 미리 입력하여 사용자에게 이 데이터를 직접 요청하세요. v2.0 엔드포인트에서 사용자 앱은 email OpenID Connect 범위를 요청할 수도 있지만, 클레임을 가져오기 위해 선택적 클레임 및 범위를 모두 요청할 필요는 없습니다. |
name |
문자열 | name 클레임은 토큰의 주체를 식별하는, 사람이 읽을 수 있는 값을 제공합니다. 이 값은 고유하지 않을 수 있으며 변경 가능하고 표시 목적으로만 사용해야 합니다. profile 범위는 이 클레임을 받기 위해 필요합니다. |
nonce |
문자열 | Nonce는 원본에 포함된 매개 변수와 일치하며 IDP에 대한 요청을 인증합니다. 일치하지 않는 경우 애플리케이션이 토큰을 거부해야 합니다. |
oid |
문자열, GUID | 이 경우에 개체의 변경할 수 없는 식별자는 사용자 계정입니다. 이 ID는 애플리케이션에서 사용자를 고유하게 식별합니다. 동일한 사용자가 로그인한 두 개의 다른 애플리케이션은 oid 클레임에서 동일한 값을 받습니다. Microsoft Graph는 이 ID를 사용자 계정의 id 속성으로 반환합니다. oid를 사용하면 여러 앱에서 사용자의 상관 관계를 지정하기 때문에 이 클레임을 수신하기 위해 profile 범위가 필요합니다. 단일 사용자가 여러 테넌트에 있는 경우 사용자는 각 테넌트에서 다른 개체 ID를 포함하게 됩니다. 사용자가 동일한 자격 증명을 사용하여 각 계정에 로그인하는 경우에도 서로 다른 계정으로 간주됩니다. oid 클레임은 GUID이며 다시 사용할 수 없습니다. |
roles |
문자열 배열 | 로그인하는 사용자에게 할당된 역할의 집합입니다. |
rh |
불투명 문자열 | 토큰의 유효성을 다시 검사하기 위해 사용하는 내부 클레임입니다. 무시됩니다. |
sub |
문자열 | 토큰에 있는 정보의 주체입니다. 예를 들어 앱의 사용자입니다. 이 값은 변경할 수 없으며 재할당 또는 재사용할 수 없습니다. 주체는 쌍으로 된 식별자이며 애플리케이션 ID에 고유합니다. 단일 사용자가 두 개의 다른 클라이언트 ID를 사용하여 두 개의 다른 앱에 로그인하는 경우 해당 앱은 주체 클레임에 두 개의 다른 값을 받게 됩니다. 아키텍처 및 개인 정보 요구 사항에 따라 두 개의 값이 필요하거나 필요하지 않을 수 있습니다. |
tid |
문자열, GUID | 사용자가 로그인하는 테넌트를 나타냅니다. 회사 및 학교 계정의 경우 GUID는 사용자가 로그인하는 조직의 테넌트 ID로, 변경할 수 없습니다. 개인 Microsoft 계정 테넌트(Xbox, Teams for Life 또는 Outlook 같은 서비스)에 로그인하는 경우 값은 9188040d-6c67-4c5b-b112-36a304b66dad입니다. |
unique_name |
문자열 | v1.0 토큰에만 제공됩니다. 토큰의 주체를 식별하는, 사람이 인식할 수 있는 값을 제공합니다. 이 값은 테넌트 내에서 반드시 고유한 것은 아니며 표시 용도로만 사용해야 합니다. |
uti |
문자열 | JWT 사양의 jti에 해당하는 토큰 식별자 클레임입니다. 대/소문자를 구분하는 고유한 토큰당 식별자입니다. |
ver |
문자열, 1.0 또는 2.0 | ID 토큰의 버전을 나타냅니다. |
hasgroups |
부울 | 있는 경우 항상 true로, 사용자 하나 이상의 그룹에 있음을 나타냅니다. 클라이언트가 Microsoft Graph API를 사용하여 사용자 그룹(https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects)을 결정해야 함을 표시합니다. |
groups:src1 |
JSON 개체 | 길이는 제한되지 않으나(hasgroups 참조) 토큰에 비해 너무 큰 토큰 요청의 경우 사용자의 전체 그룹 목록에 대한 링크가 포함됩니다. 분산된 클레임으로서의 JWT인 경우 SAML이 groups 클레임 대신에 새 클레임이 됩니다. JWT 값 예제: "groups":"src1" "_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" }자세한 내용은 Groups 초과분 클레임을 참조하세요. |
클레임을 사용하여 사용자를 안정적으로 식별
사용자를 식별할 때 시간이 지나도 일정하고 고유하게 유지되는 정보를 사용하는 것이 중요합니다. 레거시 애플리케이션은 이메일 주소, 전화 번호 또는 UPN과 같은 필드를 사용하는 경우도 있습니다. 이러한 모든 필드는 시간 경과에 따라 모두 변경될 수 있으며 다시 사용될 수도 있습니다. 예를 들어 직원이 개명하거나 현재 직원에게 이제 더 이상 재직 중이 아닌 이전 직원의 이메일 주소를 주는 경우가 이에 포함됩니다. 애플리케이션이 사용자를 식별하기 위해 사람이 읽을 수 있는 데이터를 사용해서는 안됩니다. 사람이 읽을 수 있다는 것은 일반적으로 누군가가 읽을 수 있고 변경할 수 있다는 것을 의미하기 때문입니다. 대신 OIDC 표준에서 제공하는 클레임 또는 Microsoft에서 제공하는 확장 클레임(sub 및 oid 클레임)을 사용합니다.
사용자별 정보를 올바로 저장하려면 sub 또는 oid를 독립적으로 사용하거나(이 경우 GUID는 고유함) 필요한 경우 라우팅 또는 분할에 사용되는 tid를 사용합니다. 서비스 간에 데이터를 공유해야 하는 경우 모든 앱이 테넌트에서 작업하는 사용자의 동일한 oid 및 tid 클레임을 얻게 되므로 oid 및 tid가 가장 좋습니다. sub 클레임은 고유한 쌍으로 이루어진 값입니다. 이 값은 토큰 수신자, 테넌트, 사용자의 조합을 기반으로 합니다. 사용자에 대한 ID 토큰을 요청하는 두 개의 앱은 서로 다른 sub 클레임을 받지만, 해당 사용자에 대해서는 oid 클레임으로 동일합니다.
참고 항목
사용자에 대한 정보를 저장하여 테넌트 간의 상관 관계를 지정하기 위해 idp 클레임을 사용하지 마세요. 이는 애플리케이션이 테넌트 전체에서 사용자를 추적할 수 없도록 하기 위해 설계되어 테넌트 전체에서 사용자 변경에 대한 oid 및 sub 클레임이 있기 때문에 작동하지 않습니다.
사용자가 한 테넌트에 위치하고 있지만 다른 테넌트에서 인증하는 게스트 시나리오는 사용자가 서비스에 대한 새 사용자인 것처럼 사용자를 처리해야 합니다. 한 테넌트의 문서 및 권한은 다른 테넌트에서 적용되지 않아야 합니다. 이 제한은 테넌트 간에 실수로 데이터가 유출되고 데이터 수명 주기가 적용되는 것을 방지하는 데 중요합니다. 테넌트에서 게스트를 제거하면 해당 테넌트에서 게스트가 만든 데이터에 대한 액세스 권한도 제거됩니다.
그룹 초과분 클레임
토큰 크기가 HTTP 헤더 크기 제한을 초과하지 않도록 하기 위해 groups 클레임에 포함되는 개체 ID 수를 제한합니다. 사용자가 초과분 제한(SAML 토큰의 경우 150개, JWT 토큰의 경우 200개)보다 많은 그룹의 구성원인 경우 그룹 클레임은 토큰에 포함되지 않습니다. 대신 애플리케이션에 Microsoft Graph API를 쿼리하여 사용자의 그룹 멤버 자격을 검색하도록 가리키는 토큰의 초과분 클레임이 포함됩니다.
{
...
"_claim_names": {
"groups": "src1"
},
{
"_claim_sources": {
"src1": {
"endpoint":"[Url to get this user's group membership from]"
}
}
}
...
}
다음 단계
- Microsoft Entra ID에 사용되는 ID 토큰에 대해 자세히 알아봅니다.