다음을 통해 공유

선택적 클레임 참조

  • 아티클

선택적 클레임을 사용하여 다음을 수행할 수 있습니다.

  • 애플리케이션의 토큰에 포함할 클레임을 선택합니다.
  • Microsoft ID 플랫폼이 토큰에서 반환하는 특정 클레임의 동작을 변경합니다.
  • 애플리케이션에 대한 사용자 지정 클레임을 추가하고 액세스합니다.

선택적 클레임은 v1.0 및 v2.0 형식 토큰과 SAML 토큰 모두에서 지원되지만 v1.0에서 v2.0으로 이동할 때 대부분의 값을 제공합니다. Microsoft ID 플랫폼에서는 클라이언트에서 최적의 성능을 보장하기 위해 더 작은 토큰 크기를 사용합니다. 따라서 이전에 액세스 및 ID 토큰에 포함된 여러 클레임이 v2.0 토큰에 더 이상 존재하지 않으며 애플리케이션별로 구체적으로 요청해야 합니다.

계정 유형 v1.0 토큰 v2.0 토큰
개인 Microsoft 계정 해당(N/A) 지원
Microsoft Entra 계정 지원 지원

v1.0 및 v2.0 선택적 클레임 집합

애플리케이션에서 기본적으로 사용할 수 있는 선택적 클레임 집합은 다음 표에 나와 있습니다. 확장 특성 및 디렉터리 확장에서 사용자 지정 데이터를 사용하여 애플리케이션에 대한 선택적 클레임을 추가할 수 있습니다. 액세스 토큰에 클레임을 추가할 때 클레임은 애플리케이션을 요청된 클레임이 아니라 애플리케이션(웹 API) 요청된 액세스 토큰에 적용됩니다. 클라이언트가 API에 액세스하는 방법에 관계없이 올바른 데이터는 API에 대해 인증하는 데 사용되는 액세스 토큰에 있습니다.

메모

이러한 클레임의 대부분은 v1.0 및 v2.0 토큰에 대한 JWT에 포함될 수 있지만 토큰 형식 열에 명시된 경우를 제외하고 SAML 토큰은 포함할 수 없습니다. 소비자 계정은 사용자 유형 열에 표시된 이러한 클레임의 하위 집합을 지원합니다. 나열된 대부분의 클레임은 소비자 사용자에게 적용되지 않습니다(테넌트가 없으므로 tenant_ctry 값이 없음).

다음 표에서는 v1.0 및 v2.0 선택적 클레임 집합을 나열합니다.

이름 묘사 토큰 유형 사용자 유형 노트
acct 테넌트에서 사용자 계정 상태 JWT, SAML 사용자가 테넌트 멤버인 경우 값은 0. 게스트인 경우 값은 1.
acrs 인증 컨텍스트 ID JWT Microsoft Entra ID 전달자가 수행할 수 있는 작업의 인증 컨텍스트 ID를 나타냅니다. 인증 컨텍스트 ID를 사용하여 애플리케이션 및 서비스 내에서 단계별 인증에 대한 수요를 트리거할 수 있습니다. xms_cc 클레임과 함께 자주 사용됩니다.
auth_time 사용자가 마지막으로 인증한 시간입니다. JWT
ctry 사용자의 국가/지역 JWT 이 클레임은 해당 클레임이 있고 필드 값이 FR, JP, SZ 등과 같은 표준 두 글자 국가/지역 코드인 경우 반환됩니다.
email 이 사용자의 보고된 전자 메일 주소 JWT, SAML MSA, Microsoft Entra ID 이 값은 사용자가 테넌트에서 게스트인 경우 기본적으로 포함됩니다. 관리되는 사용자(테넌트 내의 사용자)의 경우 이 선택적 클레임 또는 v2.0에서만 OpenID 범위를 사용하여 요청해야 합니다. 이 값은 올바르지 않으며 시간이 지남에 따라 변경 가능합니다. 권한 부여에 사용하거나 사용자에 대한 데이터를 저장하지 마세요. 자세한 내용은 사용자에게 이 데이터액세스할 수 있는 권한이 있는지 참조하세요. 권한 부여를 위해 이메일 클레임을 사용하는 경우 마이그레이션을 수행하는 더 안전한 클레임이동하는 것이 좋습니다. 앱에서 주소 지정 가능한 전자 메일 주소가 필요한 경우 이 클레임을 제안으로 사용하거나 UX에서 미리 채우기로 사용하여 사용자에게 직접 이 데이터를 요청합니다.
fwd IP 주소 JWT 요청 클라이언트의 원래 주소를 추가합니다(VNET 내에 있는 경우).
groups 그룹 클레임에 대한 선택적 서식 지정 JWT, SAML groups 클레임은 설정해야 하는 애플리케이션 매니페스트GroupMembershipClaims 설정과 함께 사용됩니다.
idtyp 토큰 유형 JWT 액세스 토큰 특수: 앱 전용 액세스 토큰에서만 토큰이 앱 전용 토큰인 경우 값이 app. 이 클레임은 API가 토큰이 앱 토큰인지 앱+사용자 토큰인지 확인하는 가장 정확한 방법입니다.
login_hint 로그인 힌트 JWT MSA, Microsoft Entra ID base 64로 인코딩된 불투명하고 신뢰할 수 있는 로그인 힌트 클레임입니다. 이 값을 수정하지 마세요. 이 클레임은 SSO를 가져오기 위해 모든 흐름에서 login_hint OAuth 매개 변수에 사용할 수 있는 가장 좋은 값입니다. 애플리케이션 간에 전달하여 자동으로 SSO를 지원합니다. 애플리케이션 A는 사용자를 로그인하고, login_hint 클레임을 읽은 다음, 사용자가 애플리케이션 B로 연결되는 링크에서 선택할 때 쿼리 문자열 또는 조각에서 애플리케이션 B에 클레임 및 현재 테넌트 컨텍스트를 보낼 수 있습니다. 경합 상태 및 안정성 문제를 방지하기 위해 login_hint 클레임 사용자의 현재 테넌트가 포함되지 않으며, 사용되는 경우 사용자의 홈 테넌트가 기본값으로 설정됩니다. 사용자가 다른 테넌트출신인 게스트 시나리오에서는 로그인 요청에 테넌트 식별자를 제공해야 합니다. 파트너로 사용하는 앱에 동일한 항목을 전달합니다. 이 클레임은 SDK의 기존 login_hint 기능과 함께 사용할 수 있지만 노출됩니다.
tenant_ctry 리소스 테넌트의 국가/지역 JWT 관리자가 테넌트 수준에서 설정하는 경우를 제외하고 ctry 동일합니다. 표준 2자 값이어야 합니다.
tenant_region_scope 리소스 테넌트 지역 JWT
upn UserPrincipalName JWT, SAML username_hint 매개 변수와 함께 사용할 수 있는 사용자의 식별자입니다. 사용자에 대한 지속성 식별자가 아니고 권한 부여 또는 사용자 정보를 고유하게 ID로 지정하는 데 사용하면 안 됩니다(예: 데이터베이스 키). 대신 사용자 개체 ID(oid)를 데이터베이스 키로 사용합니다. 자세한 내용은 클레임유효성을 검사하여 보안 애플리케이션 및 API를 참조하세요. 대체 로그인 ID로 로그인하는 UPN(사용자 계정 이름)이 표시되지 않아야 합니다. 대신 사용자에게 로그인 상태를 표시하기 위해 다음 ID 토큰 클레임을 사용합니다. v1 토큰의 경우 preferred_username 또는 unique_name, v2 토큰의 경우 preferred_username. 이 클레임은 자동으로 포함되지만 게스트 사용자 사례에서 해당 동작을 수정하기 위해 다른 속성을 연결하는 선택적 클레임으로 지정할 수 있습니다. login_hint 사용을 위해 login_hint 클레임을 사용해야 합니다. UPN과 같은 사람이 읽을 수 있는 식별자는 신뢰할 수 없습니다.
verified_primary_email 사용자의 PrimaryAuthoritativeEmail에서 원본 JWT
verified_secondary_email 사용자의 SecondaryAuthoritativeEmail에서 원본 JWT
vnet VNET 지정자 정보입니다. JWT
xms_cc 클라이언트 기능 JWT Microsoft Entra ID 토큰을 획득한 클라이언트 애플리케이션이 클레임 챌린지를 처리할 수 있는지 여부를 나타냅니다. 클레임 acrs함께 자주 사용됩니다. 이 클레임은 조건부 액세스 및 지속적인 액세스 평가 시나리오에서 일반적으로 사용됩니다. 토큰이 발급된 리소스 서버 또는 서비스 애플리케이션은 토큰에 이 클레임이 있는지 제어합니다. 액세스 토큰에서 cp1 값은 클라이언트 애플리케이션이 클레임 챌린지를 처리할 수 있는지를 식별하는 신뢰할 수 있는 방법입니다. 자세한 내용은 클레임 챌린지, 클레임 요청 및 클라이언트 기능참조하세요.
xms_edov 사용자의 전자 메일 도메인 소유자가 확인되었는지 여부를 나타내는 부울 값입니다. JWT 전자 메일은 사용자 계정이 있고 테넌트 관리자가 도메인 확인을 수행한 테넌트에 속하는지 확인되는 도메인으로 간주됩니다. 또한 전자 메일은 MSA(Microsoft 계정), Google 계정 또는 OTP(일회성 암호) 흐름을 사용하는 인증에 사용해야 합니다. Facebook 및 SAML/WS-Fed 계정은 도메인을 확인하지 않습니다. 이 클레임이 토큰에 반환되려면 email 클레임이 있어야 합니다.
xms_pdl 기본 설정 데이터 위치 JWT 다중 지역 테넌트의 경우 기본 설정 데이터 위치는 사용자가 있는 지리적 지역을 보여 주는 세 글자 코드입니다. 자세한 내용은 기본 데이터 위치대한 Microsoft Entra Connect 설명서를 참조하세요.
xms_pl 사용자 기본 설정 언어 JWT 설정된 경우 사용자의 기본 설정 언어입니다. 게스트 액세스 시나리오에서 홈 테넌트에서 원본으로 제공됩니다. 서식이 지정된 LL-CC("en-us").
xms_tpl 테넌트 기본 설정 언어 JWT 리소스 테넌트의 기본 설정 언어(설정된 경우)입니다. 형식이 지정된 LL("en")입니다.
ztdid 제로 터치 배포 ID JWT Windows AutoPilot데 사용되는 디바이스 ID입니다.

경고

email 또는 upn 클레임 값을 사용하여 액세스 토큰의 사용자가 데이터에 액세스할 수 있는지 여부를 저장하거나 결정하지 마세요. 이와 같은 변경 가능한 클레임 값은 시간이 지남에 따라 변경될 수 있으므로 권한 부여가 안전하지 않고 불안정할 수 있습니다.

v2.0 특정 선택적 클레임 집합

이러한 클레임은 항상 v1.0 토큰에 포함되지만 요청되지 않는 한 v2.0 토큰에는 포함되지 않습니다. 이러한 클레임은 JWT(ID 토큰 및 액세스 토큰)에만 적용됩니다.

JWT 클레임 이름 묘사 노트
ipaddr IP 주소 클라이언트가 로그인한 IP 주소입니다.
onprem_sid 온-프레미스 보안 식별자
pwd_exp 암호 만료 시간 암호가 만료되는 iat 클레임 시간 이후의 시간(초)입니다. 이 클레임은 암호가 곧 만료되는 경우에만 포함됩니다(암호 정책의 "알림 일"로 정의됨).
pwd_url 암호 URL 변경 사용자가 암호를 변경하기 위해 방문할 수 있는 URL입니다. 이 클레임은 암호가 곧 만료되는 경우에만 포함됩니다(암호 정책의 "알림 일"로 정의됨).
in_corp 회사 네트워크 내부 클라이언트가 회사 네트워크에서 로그인 중인지를 알 수 있습니다. 그렇지 않으면 클레임이 포함되지 않습니다. MFA에서 신뢰할 수 있는 IP 설정을 기반으로 합니다.
family_name 성 사용자 개체에 정의된 대로 사용자의 성, 성 또는 패밀리 이름을 제공합니다. 예를 들어 "family_name":"Miller". MSA 및 Microsoft Entra ID에서 지원됩니다. profile 범위가 필요합니다.
given_name 이름 사용자 개체에 설정된 대로 사용자의 첫 번째 또는 "지정된" 이름을 제공합니다. 예를 들어 "given_name": "Frank". MSA 및 Microsoft Entra ID에서 지원됩니다. profile 범위가 필요합니다.
upn 사용자 계정 이름 username_hint 매개 변수와 함께 사용할 수 있는 사용자의 식별자입니다. 사용자에 대한 지속성 식별자가 아니고 권한 부여 또는 사용자 정보를 고유하게 ID로 지정하는 데 사용하면 안 됩니다(예: 데이터베이스 키). 자세한 내용은 클레임유효성을 검사하여 보안 애플리케이션 및 API를 참조하세요. 대신 사용자 개체 ID(oid)를 데이터베이스 키로 사용합니다. 대체 로그인 ID로 로그인하는 UPN(사용자 계정 이름)이 표시되지 않아야 합니다. 대신 사용자에게 로그인 상태를 표시하기 위해 다음 preferred_username 클레임을 사용합니다. profile 범위가 필요합니다.

v1.0 특정 선택적 클레임 집합

v2 토큰 형식의 향상된 기능 중 일부는 v1 토큰 형식을 사용하는 앱이 보안 및 안정성을 향상시키는 데 도움이 되므로 사용할 수 있습니다. 이러한 개선 사항은 SAML 토큰이 아닌 JWT에만 적용됩니다.

JWT 클레임 이름 묘사 노트
aud 관객 항상 JWT에 있지만 v1 액세스 토큰에서는 후행 슬래시와 리소스의 클라이언트 ID를 사용하거나 사용하지 않고 모든 appID URI와 같은 다양한 방법으로 내보낼 수 있습니다. 이 임의화는 토큰 유효성 검사를 수행할 때 코딩하기 어려울 수 있습니다. 이 클레임에 additionalProperties 사용하여 항상 v1 액세스 토큰에서 리소스의 클라이언트 ID로 설정되었는지 확인합니다. v1 JWT 액세스 토큰만
preferred_username 기본 설정 사용자 이름 v1 토큰 내에서 기본 설정 사용자 이름 클레임을 제공합니다. 이 클레임을 사용하면 앱이 토큰 유형에 관계없이 사용자 이름 힌트를 제공하고 사람이 읽을 수 있는 표시 이름을 쉽게 표시할 수 있습니다. 사용, upn 또는 unique_name대신 이 선택적 클레임을 사용하는 것이 좋습니다. v1 ID 토큰 및 액세스 토큰

선택적 클레임의 additionalProperties

일부 선택적 클레임은 클레임이 반환되는 방식을 변경하도록 구성할 수 있습니다. 이러한 additionalProperties 데이터 기대치가 다른 온-프레미스 애플리케이션을 마이그레이션하는 데 주로 사용됩니다. 예를 들어 include_externally_authenticated_upn_without_hash UPN에서 해시 표시(#)를 처리할 수 없는 클라이언트에 도움이 됩니다.

속성 이름 additionalProperty 이름 묘사
upn SAML 및 JWT 응답과 v1.0 및 v2.0 토큰 모두에 사용할 수 있습니다.
include_externally_authenticated_upn 리소스 테넌트에 저장된 게스트 UPN을 포함합니다. 예를 들어 foo_hometenant.com#EXT#@resourcetenant.com.
include_externally_authenticated_upn_without_hash 해시 표시(#)가 밑줄(_)로 대체된다는 점을 제외하면 앞에서 나열한 것과 같습니다(예: foo_hometenant.com_EXT_@resourcetenant.com).
aud v1 액세스 토큰에서 이 클레임은 aud 클레임의 형식을 변경하는 데 사용됩니다. 이 클레임은 v2 토큰 또는 버전 ID 토큰에 영향을 주지 않습니다. 여기서 aud 클레임은 항상 클라이언트 ID입니다. 이 구성을 사용하여 API가 대상 그룹 유효성 검사를 보다 쉽게 수행할 수 있는지 확인합니다. 액세스 토큰에 영향을 주는 모든 선택적 클레임과 마찬가지로 리소스가 액세스 토큰을 소유하므로 요청의 리소스는 이 선택적 클레임을 설정해야 합니다.
use_guid 리소스(API)의 클라이언트 ID를 런타임 종속이 아닌 항상 aud 클레임으로 GUID 형식으로 내보냅니다. 예를 들어 리소스가 이 플래그를 설정하고 해당 클라이언트 ID가 00001111-aaaa-2222-bbbb-3333cccc4444경우 해당 리소스에 대한 액세스 토큰을 요청하는 앱은 aud00001111-aaaa-2222-bbbb-3333cccc4444있는 액세스 토큰을 받습니다. 이 클레임 집합이 없으면 API는 api://MyApi.com, api://MyApi.com/, api://myapi.com/AdditionalRegisteredField 또는 해당 API에 대한 앱 ID URI로 설정된 다른 값 및 리소스의 클라이언트 ID의 aud 클레임이 있는 토큰을 가져올 수 있습니다.
idtyp 이 클레임은 토큰 유형(앱, 사용자, 디바이스)을 가져오는 데 사용됩니다. 기본적으로 앱 전용 토큰에 대해서만 내보냅니다. 액세스 토큰에 영향을 주는 모든 선택적 클레임과 마찬가지로 리소스가 액세스 토큰을 소유하므로 요청의 리소스는 이 선택적 클레임을 설정해야 합니다.
include_user_token 사용자 토큰에 대한 idtyp 클레임을 내보낸다. idtyp 클레임 집합에 대한 이 선택적 추가 속성이 없으면 API는 앱 토큰에 대한 클레임만 가져옵니다.

additionalProperties 예제

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ]
}

이 optionalClaims 개체를 사용하면 클라이언트에 반환된 ID 토큰에 다른 홈 테넌트 및 리소스 테넌트 정보가 포함된 upn 클레임이 포함됩니다. upn 클레임은 사용자가 테넌트에서 게스트인 경우에만 토큰에서 변경됩니다(인증에 다른 IDP를 사용).

참고 항목

다음 단계

  • 선택적 클레임구성하는 대해 자세히 알아봅니다.