액세스 토큰 클레임 참조
액세스 토큰은 JWT(JSON 웹 토큰)입니다. JWT에는 다음 부분이 포함됩니다.
- 헤더 - 토큰 유형과 서명 방법에 대한 정보를 포함하여 토큰의 유효성 검사 방법에 대한 정보를 제공합니다.
- 페이로드 - 서비스를 호출하려고 하는 사용자 또는 애플리케이션에 대한 모든 중요한 데이터를 포함합니다.
- 서명 - 토큰의 유효성을 검사하는 데 사용되는 원시 자료입니다.
각 조각은 마침표(.)로 구분되며 별도로 Base 64로 인코딩됩니다.
클레임은 채울 값이 존재하는 경우에만 제공됩니다. 애플리케이션은 존재하는 클레임에 대해 종속성이 없어야 합니다. 예를 들어 pwd_exp(모든 테넌트에서 암호가 만료될 필요가 없음) 및 family_name(클라이언트 자격 증명 흐름이 이름 없는 애플리케이션을 대신함)이 있습니다. 액세스 토큰에는 항상 액세스 평가를 위한 충분한 클레임이 포함됩니다.
Microsoft ID 플랫폼은 재사용을 위해 토큰을 보호하는 데 도움이 되는 일부 클레임을 사용합니다. Opaque의 설명은 이러한 클레임을 공용 소비용이 아닌 것으로 표시합니다. 이러한 클레임은 토큰에 표시되거나 표시되지 않을 수 있으며, 통지 없이 새로 추가될 수도 있습니다.
헤더 클레임
| 클레임 | 서식 | 설명 |
|---|---|---|
typ |
문자열 - 항상 JWT |
토큰이 JWT임을 나타냅니다. |
alg |
문자열 | 토큰에 서명하는 데 사용된 알고리즘을 나타냅니다(예: RS256). |
kid |
문자열 | 이 토큰의 서명 유효성을 검사하는 데 사용할 수 있는 공개 키의 지문을 지정합니다. v1.0 및 v2.0 액세스 토큰으로 내보냅니다. |
x5t |
문자열 | 사용 및 값에서 kid와 동일하게 작동합니다. x5t는 호환성을 위해 v1.0 액세스 토큰으로만 내보내는 레거시 클레임입니다. |
페이로드 클레임
| 클레임 | 서식 | 설명 | 권한 부여 고려 사항 |
|---|---|---|---|
acrs |
문자열의 JSON 배열 | 전달자가 수행할 수 있는 작업의 인증 컨텍스트 ID를 나타냅니다. 인증 컨텍스트 ID는 애플리케이션 및 서비스 내에서 단계별 인증에 대한 요구를 트리거하는 데 사용될 수 있습니다. 종종 xms_cc 클레임과 함께 사용됩니다. |
|
aud |
문자열, 애플리케이션 ID URI 또는 GUID | 토큰의 의도된 대상 그룹을 식별합니다. v2.0 토큰에서 이 값은 항상 API의 클라이언트 ID입니다. v1.0 토큰에서는 요청에 사용된 클라이언트 ID 또는 리소스 URI일 수 있습니다. 값은 클라이언트가 토큰을 요청한 방법에 따라 달라질 수 있습니다. | 이 값의 유효성을 검사하고, 값이 의도한 대상과 일치하지 않는 경우 토큰을 거부합니다. |
iss |
문자열, STS(보안 토큰 서비스) URI | 토큰을 생성하고 반환하는 STS 및 인증된 사용자의 Microsoft Entra 테넌트를 식별합니다. 발급된 토큰이 v2.0 토큰인 경우(ver 클레임 참조), URI는 /v2.0으로 끝납니다. 사용자가 Microsoft 계정의 소비자 사용자임을 나타내는 GUID는 9188040d-6c67-4c5b-b112-36a304b66dad입니다. |
애플리케이션은 클레임의 GUID 부분을 사용하여 애플리케이션에 로그인할 수 있는 테넌트 세트를 제한할 수 있습니다(해당되는 경우). |
idp |
문자열, 대개 STS URI입니다. | 토큰의 주체를 인증한 ID 공급자를 기록합니다. 이 값은 사용자 계정이 발급자와 동일한 테넌트(예: 게스트)가 아닌 경우 발급자 클레임의 값과 동일합니다. 클레임이 없는 경우 iss의 값을 사용합니다. 조직 컨텍스트(예: Microsoft Entra 테넌트에 초대된 개인 계정)에서 사용되는 개인 계정의 경우, idp 클레임은 ‘live.com’ 또는 Microsoft 계정 테넌트 9188040d-6c67-4c5b-b112-36a304b66dad가 포함된 STS URI일 수 있습니다. |
|
iat |
int, UNIX 타임스탬프 | 이 토큰에 대한 인증이 발생한 시기를 지정합니다. | |
nbf |
int, UNIX 타임스탬프 | JWT를 처리할 수 있는 시간을 지정합니다. | |
exp |
int, UNIX 타임스탬프 | 그 전에는 처리를 위해 JWT를 수락할 수 있는 만료 시간을 지정합니다. 리소스는 이 시간 이전에도 토큰을 거부할 수 있습니다. 인증의 필수 변경을 위해 또는 토큰이 해지될 때 거부가 발생할 수 있습니다. | |
aio |
불투명 문자열 | Microsoft Entra ID에서 토큰을 다시 사용하기 위해 데이터를 기록하는 데 사용하는 내부 클레임입니다. 리소스에서는 이 클레임을 사용하지 않아야 합니다. | |
acr |
문자열, 0 또는 1, v1.0 토큰에만 있음 |
"인증 컨텍스트 클래스" 클레임에 대한 값 0은 최종 사용자 인증이 ISO/IEC 29115의 요구 사항을 충족하지 못했음을 나타냅니다. |
|
amr |
JSON 문자열 배열, v1.0 토큰에만 있음 | 토큰의 주체에 대한 인증 방법을 식별합니다. | |
appid |
문자열, GUID, v1.0 토큰에만 있음 | 토큰을 사용하는 클라이언트의 애플리케이션 ID입니다. 애플리케이션은 자체적으로 작동할 수도 있고 사용자를 대신하여 작동할 수도 있습니다. 애플리케이션 ID는 일반적으로 애플리케이션 개체를 나타내지만 Microsoft Entra ID의 서비스 사용자 개체를 나타낼 수도 있습니다. | appid는 권한 부여 결정에 사용할 수 있습니다. |
azp |
문자열, GUID, v2.0 토큰에만 있음 | appid에 대한 대체 항목입니다. 토큰을 사용하는 클라이언트의 애플리케이션 ID입니다. 애플리케이션은 자체적으로 작동할 수도 있고 사용자를 대신하여 작동할 수도 있습니다. 애플리케이션 ID는 일반적으로 애플리케이션 개체를 나타내지만 Microsoft Entra ID의 서비스 사용자 개체를 나타낼 수도 있습니다. |
azp는 권한 부여 결정에 사용할 수 있습니다. |
appidacr |
문자열, 0, 1 또는 2, v1.0 토큰에만 있음 |
클라이언트의 인증 방법을 나타냅니다. 퍼블릭 클라이언트의 경우 값은 0입니다. 클라이언트 ID 및 클라이언트 암호를 사용하는 경우 값은 1입니다. 클라이언트 인증서를 인증에 사용한 경우 값은 2입니다. |
|
azpacr |
문자열, 0, 1 또는 2, v2.0 토큰에만 있음 |
appidacr에 대한 대체 항목입니다. 클라이언트의 인증 방법을 나타냅니다. 퍼블릭 클라이언트의 경우 값은 0입니다. 클라이언트 ID 및 클라이언트 암호를 사용하는 경우 값은 1입니다. 클라이언트 인증서를 인증에 사용한 경우 값은 2입니다. |
|
preferred_username |
문자열, v2.0 토큰에만 있음 | 사용자를 나타내는 기본 사용자 이름입니다. 값은 이메일 주소, 전화 번호 또는 지정된 형식이 없는 일반 사용자 이름일 수 있습니다. 이 값을 사용자 이름 힌트 및 사람이 읽을 수 있는 UI에서 사용자 이름으로 사용합니다. 이 클레임을 받으려면 profile 범위를 사용합니다. |
이 값은 변경 가능하므로 권한 부여 결정을 내리는 데 사용하지 마세요. |
name |
문자열 | 사람이 인식할 수 있으며 토큰의 주체를 식별하는 값을 제공합니다. 값은 다를 수 있고, 변경 가능하며, 표시용으로만 사용됩니다. 이 클레임을 받으려면 profile 범위를 사용합니다. |
권한 부여 결정을 내리는 데는 이 값을 사용하지 마세요. |
scp |
문자열, 공백으로 구분된 범위 목록 | 클라이언트 애플리케이션이 동의를 요청(및 수신)한 애플리케이션에 의해 노출된 범위 세트입니다. 사용자 토큰에 대해서만 포함됩니다. | 애플리케이션은 이러한 범위가 애플리케이션에 의해 노출된 유효한 범위인지 확인하고 이러한 범위의 값을 기반으로 권한 부여 결정을 해야 합니다. |
roles |
문자열 배열, 권한 목록 | 요청 애플리케이션 또는 사용자가 호출할 수 있는 권한을 받은 사용자 애플리케이션에 의해 노출된 권한 세트입니다. 클라이언트 자격 증명 흐름은 애플리케이션 토큰에 대한 사용자 범위 대신 이 권한 집합을 사용합니다. 사용자 토큰의 경우 이 값 집합은 대상 애플리케이션에서 사용자의 할당된 역할을 포함합니다. | 이러한 값은 리소스에 액세스하도록 권한 부여를 적용하는 등 액세스를 관리하는 데 사용할 수 있습니다. |
wids |
RoleTemplateID GUID의 배열 | Microsoft Entra 기본 제공 역할에 있는 역할 섹션에서 이 사용자에게 할당된 테넌트 전체 역할을 나타냅니다. 애플리케이션 매니페스트의 groupMembershipClaims 속성은 애플리케이션별로 이 클레임을 구성합니다. 클레임을 All 또는 DirectoryRole로 설정합니다. |
이러한 값은 리소스에 액세스하도록 권한 부여를 적용하는 등 액세스를 관리하는 데 사용할 수 있습니다. |
groups |
GUID의 JSON 배열 | 주체의 그룹 멤버 자격을 나타내는 개체 ID를 제공합니다. 애플리케이션 매니페스트의 groupMembershipClaims 속성은 애플리케이션별로 그룹 클레임을 구성합니다. null 값은 모든 그룹을 제외하고 SecurityGroup 값은 디렉터리 역할 및 Active Directory 보안 그룹 구성원만 포함하며 All 값은 보안 그룹과 Microsoft 365 배포 목록을 모두 포함합니다. 다른 흐름의 경우 사용자가 속한 그룹 수가 SAML의 경우 150개, JWT의 경우 200개를 초과하면 Microsoft Entra ID는 클레임 원본에 초과분 클레임을 추가합니다. 클레임 원본은 사용자에 대한 그룹 목록이 포함된 Microsoft Graph 엔드포인트를 가리킵니다. |
이러한 값은 리소스에 액세스하도록 권한 부여를 적용하는 등 액세스를 관리하는 데 사용할 수 있습니다. |
hasgroups |
부울 | 있는 경우 항상 true로, 사용자가 하나 이상의 그룹에 있는지 여부를 나타냅니다. 클라이언트가 Microsoft Graph API를 사용하여 사용자 그룹(https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects)을 결정해야 함을 표시합니다. |
|
groups:src1 |
JSON 개체 | 토큰 요청이 토큰에 비해 너무 큰 경우 사용자의 전체 그룹 목록에 대한 링크를 포함합니다. 분산된 클레임으로서의 JWT인 경우 SAML이 groups 클레임 대신에 새 클레임이 됩니다. JWT 값 예제: "groups":"src1" "_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" } |
|
sub |
문자열 | 토큰과 연결된 보안 주체 예: 애플리케이션의 사용자 이 값은 변경할 수 없으며 다시 할당하거나 다시 사용하지 마세요. 주체는 쌍으로 된 식별자이며 특정 애플리케이션 ID에 고유합니다. 단일 사용자가 두 개의 다른 클라이언트 ID를 사용하여 두 개의 다른 애플리케이션에 로그인하는 경우 해당 애플리케이션은 주체 클레임에 두 개의 다른 값을 받게 됩니다. 두 가지 다른 값을 사용하는 것은 아키텍처 및 개인 정보 요구 사항에 따라 달라집니다. 테넌트 내의 여러 애플리케이션에서 동일하게 유지되는 oid 클레임도 참조하세요. |
예를 들어, 리소스 액세스에 토큰을 사용할 때 이 값을 사용하면 인증 검사를 수행하고 데이터베이스 테이블에서 키로 사용할 수 있습니다. |
oid |
문자열, GUID | 사용자 또는 서비스 주체의 확인된 ID인 요청자에 대한 변경할 수 없는 식별자. 이 ID는 애플리케이션 전체에서 요청자를 고유하게 식별합니다. 동일한 사용자가 로그인한 두 개의 다른 애플리케이션은 oid 클레임에서 동일한 값을 받습니다. Microsoft Graph와 같은 Microsoft 온라인 서비스에 대한 쿼리를 수행할 때 oid를 사용할 수 있습니다. Microsoft Graph는 이 ID를 지정된 사용자 계정에 대한 id 속성으로 반환합니다. oid를 사용하면 여러 애플리케이션에서 보안 주체의 상관 관계를 지정할 수 있으므로 사용자에 대해 이 클레임을 수신하기 위해 profile 범위를 사용합니다. 단일 사용자가 여러 테넌트에 있는 경우 사용자는 각 테넌트에 서로 다른 개체 ID를 포함합니다. 사용자가 동일한 자격 증명을 사용하여 각 계정에 로그인하더라도 계정은 다릅니다. |
예를 들어, 리소스 액세스에 토큰을 사용할 때 이 값을 사용하면 인증 검사를 수행하고 데이터베이스 테이블에서 키로 사용할 수 있습니다. |
tid |
문자열, GUID | 사용자가 로그인하는 테넌트를 나타냅니다. 회사 및 학교 계정의 경우 GUID는 사용자가 로그인하는 조직의 테넌트 ID로, 변경할 수 없습니다. 개인 Microsoft 계정 테넌트(Xbox, Teams for Life 또는 Outlook 같은 서비스)에 로그인하는 경우 값은 9188040d-6c67-4c5b-b112-36a304b66dad입니다. 이 클레임을 받으려면 애플리케이션에서 profile 범위를 요청해야 합니다. |
이 값은 권한 부여 결정의 다른 클레임과 함께 고려해야 합니다. |
unique_name |
문자열, v1.0 토큰에만 있음 | 토큰의 주체를 식별하는, 사람이 인식할 수 있는 값을 제공합니다. | 이 값은 테넌트 내에서 다를 수 있으며 표시 목적으로만 사용할 수 있습니다. |
uti |
문자열 | JWT 사양의 jti에 해당하는 토큰 식별자 클레임입니다. 대/소문자를 구분하는 고유한 토큰당 식별자입니다. |
|
rh |
불투명 문자열 | Azure에서 토큰의 유효성을 다시 검사하기 위해 사용하는 내부 클레임입니다. 리소스에서는 이 클레임을 사용하지 않아야 합니다. | |
ver |
문자열, 1.0 또는 2.0 |
액세스 토큰의 버전을 나타냅니다. | |
xms_cc |
문자열의 JSON 배열 | 토큰을 획득한 클라이언트 애플리케이션이 클레임 문제를 처리할 수 있는지 여부를 나타냅니다. 이는 acrs 클레임과 함께 자주 사용됩니다. 이 클레임은 조건부 액세스 및 지속적인 액세스 권한 평가 시나리오에서 일반적으로 사용됩니다. 토큰이 발급된 리소스 서버 또는 서비스 애플리케이션은 토큰에서 이 클레임의 존재를 제어합니다. 액세스 토큰의 cp1 값은 클라이언트 애플리케이션이 클레임 문제를 처리할 수 있는지 식별하는 신뢰할 수 있는 방법입니다. 자세한 내용은 클레임 문제, 클레임 요청 및 클라이언트 기능을 참조하세요. |
참고 항목
roles, groups, scp 및 wids 클레임은 리소스가 사용자 또는 애플리케이션에 권한을 부여하는 방법의 전체 목록이 아니며 호출자에게 부여된 사용 권한의 전체 목록도 아닙니다. 대상 리소스는 다른 방법을 사용하여 보호된 리소스에 대한 액세스 권한을 부여할 수 있습니다.
그룹 초과분 클레임
Microsoft Entra ID는 HTTP 헤더의 크기 제한 내에서 유지하기 위해 그룹 클레임에 포함된 개체 ID 수를 제한합니다. 사용자가 초과분 제한(SAML 토큰의 경우 150, JWT 토큰의 경우 200)보다 많은 그룹의 구성원인 경우 Microsoft Entra ID는 토큰의 그룹 클레임을 내보내지 않습니다. 대신 애플리케이션에 Microsoft Graph API를 쿼리하여 사용자의 그룹 멤버 자격을 검색하도록 가리키는 토큰의 초과분 클레임이 포함됩니다.
{
...
"_claim_names": {
"groups": "src1"
},
"_claim_sources": {
"src1": {
"endpoint": "[Url to get this user's group membership from]"
}
}
...
}
앱 생성 스크립트 폴더에 제공되는 BulkCreateGroups.ps1을 사용하여 초과분 시나리오를 테스트할 수 있습니다.
참고 항목
반환되는 URL은 Azure AD Graph URL(즉, graph.windows.net)입니다. 서비스는 이 URL을 사용하는 대신, idtyp 선택적 클레임(토큰이 앱인지 앱+사용자 토큰인지 식별)을 사용하여 그룹 전체 목록을 쿼리하기 위한 Microsoft Graph URL을 생성해야 합니다.
v1.0 기본 클레임
v1.0 토큰에는 해당하는 경우 다음 클레임이 포함되지만 기본적으로 v2.0 토큰은 포함되지 않습니다. v2.0에 대해 이러한 클레임을 사용하기 위해 애플리케이션은 선택적 클레임을 사용하여 클레임을 요청합니다.
| 클레임 | 서식 | 설명 |
|---|---|---|
ipaddr |
문자열 | 사용자가 인증된 IP 주소입니다. |
onprem_sid |
문자열, SID 형식 | 사용자에게 온-프레미스 인증이 있는 경우 이 클레임이 해당 SID를 제공합니다. 레거시 애플리케이션에서 권한 부여에 이 클레임을 사용할 수 있습니다. |
pwd_exp |
int, UNIX 타임스탬프 | 사용자의 암호가 만료되는 시기를 나타냅니다. |
pwd_url |
문자열 | 사용자가 암호를 재설정할 수 있는 URL |
in_corp |
부울 값 | 클라이언트가 회사 네트워크에서 로그인하고 있는지 여부를 나타냅니다. |
nickname |
문자열 | 이름 및 성과는 별개인 사용자의 다른 이름입니다. |
family_name |
문자열 | 사용자 개체에 정의된 대로 사용자의 성을 제공합니다. |
given_name |
문자열 | 사용자 개체에 설정된 대로 사용자의 이름을 제공합니다. |
upn |
문자열 | 사용자의 사용자 이름입니다. 전화 번호, 이메일 주소 또는 형식이 지정되지 않은 문자열일 수 있습니다. 표시 목적 및 재인증 시나리오에서 사용자 이름 힌트를 제공하기 위해서만 사용해야 합니다. |
amr 클레임
ID는 다양한 방법으로 인증할 수 있으며 애플리케이션과 관련될 수 있습니다. amr 클레임은 암호 및 Authenticator 앱을 모두 사용하는 인증을 위해 여러 항목(예: ["mfa", "rsa", "pwd"])을 포함할 수 있는 배열입니다.
| 값 | 설명 |
|---|---|
pwd |
암호 인증으로, 사용자의 Microsoft 암호 또는 애플리케이션의 클라이언트 암호 중 하나입니다. |
rsa |
인증은 Microsoft Authenticator 앱 등을 사용하여 RSA 키 증명을 기반으로 수행되었습니다. 또한 이 값은 인증 시 서비스 소유 X509 인증서와 함께 자체 서명된 JWT를 사용함을 나타냅니다. |
otp |
이메일 또는 문자 메시지를 사용하는 OTP(일회성 암호)입니다. |
fed |
페더레이션 인증 어설션(예: JWT 또는 SAML)의 사용을 나타냅니다. |
wia |
Windows 통합 인증 |
mfa |
다단계 인증의 사용을 나타냅니다. 이 클레임이 있는 경우 다른 인증 방법을 포함합니다. |
ngcmfa |
mfa와 동일하며 특정 고급 자격 증명 유형의 프로비전에 사용됩니다. |
wiaormfa |
사용자가 Windows 또는 MFA 자격 증명을 사용하여 인증했습니다. |
none |
완료된 인증이 없음을 나타냅니다. |
다음 단계
- Microsoft Entra ID에 사용되는 액세스 토큰에 대해 자세히 알아봅니다.