다음을 통해 공유

선택적 클레임 참조

  • 아티클

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

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

선택적 클레임은 v1.0 및 v2.0 형식 토큰과 SAML 토큰 모두에서 지원되지만, v1.0에서 v2.0으로 전환할 때 대부분의 값을 제공합니다. Microsoft ID 플랫폼에서는 클라이언트의 최적 성능을 보장하기 위해 더 작은 토큰 크기가 사용됩니다. 따라서, 이전에 액세스 및 ID 토큰에 포함되어 있던 일부 클레임이 v 2.0 토큰에는 더 이상 존재하지 않으며, 애플리케이션 기준으로 특수하게 요청되어야 합니다.

계정 유형 v1.0 토큰 v2.0 토큰
개인 Microsoft 계정 해당 없음 지원됨
Microsoft Entra 계정 지원됨 지원됨

v1.0 및 v2.0 선택적 클레임 세트

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

참고 항목

이러한 클레임 대부분은 토큰 유형 열에 명시된 경우를 제외하고 SAML 토큰이 아닌 v1.0 및 v2.0 토큰에 대한 JWT에 포함될 수 있습니다. 소비자 계정은 사용자 유형 열에 표시된 이러한 클레임의 일부를 지원합니다. 나열된 많은 클레임은 소비자 사용자에게 적용되지 않습니다(테넌트가 없으므로 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 기능과 함께 사용해야 합니다.
sid 세션 단위 사용자 로그아웃에 사용되는 세션 ID JWT 개인 및 Microsoft Entra 계정
tenant_ctry 리소스 테넌트의 국가/지역 JWT 관리자가 테넌트 수준에서 설정하는 것을 제외하고는 ctry와 같습니다. 또한, 표준 두 글자 값이어야 합니다.
tenant_region_scope 리소스 테넌트의 지역입니다. JWT
upn UserPrincipalName JWT, SAML username_hint 매개 변수와 함께 사용할 수 있는 사용자의 식별자입니다. 사용자에 대한 지속형 식별자가 아니며 권한을 부여하거나 사용자 정보를 고유하게(예: 데이터베이스 키로) 식별하는 데 사용할 수 없습니다. 대신 사용자 개체 ID(oid)를 데이터베이스 키로 사용합니다. 자세한 내용은 클레임 유효성 검사를 통한 애플리케이션 및 API 보안을 참조하세요. 대체 로그인 ID를 사용하여 로그인하는 사용자에게 UPN(사용자 계정 이름)이 표시되면 안 됩니다. 대신 preferred_username 또는 unique_name(v1 토큰의 경우)이나 preferred_username(v2 토큰의 경우) ID 토큰 클레임을 사용하여 로그인 상태를 사용자에게 표시합니다. 이 클레임은 자동으로 포함되지만, 다른 속성을 연결하여 게스트 사용자 사례에서 해당 동작을 수정하기 위해 선택적 클레임으로 지정할 수 있습니다. 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입니다.

Warning

저장할 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 매개 변수와 함께 사용할 수 있는 사용자의 식별자입니다. 사용자에 대한 지속형 식별자가 아니며 권한을 부여하거나 사용자 정보를 고유하게(예: 데이터베이스 키로) 식별하는 데 사용할 수 없습니다. 자세한 내용은 클레임 유효성 검사를 통한 애플리케이션 및 API 보안을 참조하세요. 대신 사용자 개체 ID(oid)를 데이터베이스 키로 사용합니다. 대체 로그인 ID를 사용하여 로그인하는 사용자에게 UPN(사용자 계정 이름)이 표시되면 안 됩니다. 대신 사용자에게 로그인 상태를 표시하는 데 preferred_username 클레임을 사용합니다. profile 범위가 필요합니다.

v1.0 관련 선택적 클레임 세트

v2 토큰 형식의 향상된 기능 중 일부는 보안 및 안정성 향상을 위해 v1 토큰 형식을 사용하는 앱에서 사용할 수 있습니다. 이러한 향상된 기능은 SAML 토큰이 아닌 JWT에만 적용됩니다.

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

선택적 클레임 중 additionalProperties개

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

Property name 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 런타임에 종속되는 것이 아니라 항상 GUID 형식으로 리소스(API)의 클라이언트 ID를 aud 클레임으로 내보냅니다. 예를 들어, 리소스에서 이 플래그를 설정하고 클라이언트 ID가 00001111-aaaa-2222-bbbb-3333cccc4444인 경우 해당 리소스에 대한 액세스 토큰을 요청하는 모든 앱은 aud: 00001111-aaaa-2222-bbbb-3333cccc4444과 함께 액세스 토큰을 받습니다. 이 클레임 집합을 사용하지 않으면 API에서 aud 클레임이 api://MyApi.com, api://MyApi.com/, api://myapi.com/AdditionalRegisteredField인 토큰 또는 해당 API에 대한 앱 ID URI로 설정된 다른 값과 리소스의 클라이언트 ID가 있는 토큰을 가져올 수 있습니다.
idtyp 이 클레임은 토큰 유형(앱, 사용자, 디바이스)을 가져오는 데 사용됩니다. 기본적으로 앱 전용 토큰에 대해서만 내보냅니다. 액세스 토큰에 영향을 주는 모든 선택적 클레임처럼 요청된 리소스는 액세스 토큰을 소유하므로 이 선택적 클레임을 설정해야 합니다.
include_user_token 사용자 토큰에 대한 idtyp 클레임을 내보냅니다. idtyp 클레임 집합에 대한 이 선택적 추가 속성이 없으면 API는 앱 토큰에 대한 클레임만 가져옵니다.

additionalProperties 예제

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

이 optionalClaims 개체는 클라이언트에 반환된 ID 토큰이 다른 홈 테넌트 및 리소스 테넌트 정보와 함께 upn 클레임을 포함하도록 합니다. 사용자가 인증에 대해 다른 IDP를 사용하는 테넌트의 게스트인 경우 토큰에서 upn 클레임만 변경됩니다.

참고 항목

다음 단계