선택적 클레임 구성

아티클
06/10/2024

Microsoft Entra가 반환하는 토큰은 이를 요청하는 클라이언트의 최적 성능을 보장하기 위해 더 작게 유지됩니다. 따라서, 일부 클레임이 토큰에 더 이상 기본적으로 존재하지 않으며, 애플리케이션 기준으로 특수하게 요청되어야 합니다.

Microsoft Entra 관리 센터의 애플리케이션 UI 또는 매니페스트를 통해 애플리케이션에 대한 선택적 클레임을 구성할 수 있습니다.

필수 조건

활성 구독이 있는 Azure 계정. 체험 계정을 만듭니다.
빠른 시작: 애플리케이션 등록 완료

애플리케이션에서 선택적 클레임 구성

최소한 클라우드 애플리케이션 관리자로 Microsoft Entra 관리 센터에 로그인합니다.
ID>애플리케이션>앱 등록으로 이동합니다.
시나리오 및 원하는 결과에 따라 선택적 클레임을 구성할 애플리케이션을 선택합니다.

앱 UI로 진행
매니페스트 진행

관리에서 토큰 구성을 선택합니다.
선택적 클레임 추가를 선택합니다.
액세스와 같이 구성하려는 토큰 형식을 선택합니다.
추가할 선택적 클레임을 선택합니다.
추가를 선택합니다.

관리에서 매니페스트를 선택합니다. 웹 기반 매니페스트 편집기가 열리면 매니페스트를 편집할 수 있습니다. 필요에 따라 다운로드를 선택하고 로컬로 매니페스트를 편집하고 업로드를 사용하여 애플리케이션에 다시 적용할 수 있습니다. 파일에 optionalClaims 속성이 없으면 추가할 수 있습니다.

다음 애플리케이션 매니페스트 항목은 ID, 액세스 및 SAML 토큰에 auth_time, ipaddr 및 upn 선택적 클레임을 추가합니다.
```
"optionalClaims": {
    "idToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "accessToken": [
        {
            "name": "ipaddr",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "upn",
            "essential": false
        },
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": false
        }
    ]
}
```
완료되면 저장을 선택합니다. 이제 지정된 선택적 클레임이 애플리케이션의 토큰에 포함됩니다.

개체 optionalClaims은(는) 애플리케이션에서 요청한 선택적 클레임을 선언합니다. 애플리케이션은 ID 토큰, 액세스 토큰 및 SAML 2 토큰에 반환되는 선택적 클레임을 구성할 수 있습니다. 애플리케이션은 다른 선택적 클레임 집합이 각 토큰 유형으로 반환되도록 구성할 수 있습니다.

이름	형식	설명
`idToken`	컬렉션	ID JWT 토큰에서 반환된 선택적 클레임입니다.
`accessToken`	컬렉션	JWT 액세스 토큰에서 반환된 선택적 클레임입니다.
`saml2Token`	컬렉션	SAML 토큰에서 반환된 선택적 클레임입니다.

특정 클레임에서 지원하는 경우 additionalProperties 필드를 사용하여 선택적 클레임의 동작을 수정할 수도 있습니다.

이름	형식	설명
`name`	Edm.String	선택적 클레임의 이름입니다.
`source`	Edm.String	클레임의 원본(디렉터리 개체)입니다. 확장 속성에서 가져온 미리 정의된 클레임 및 사용자 정의 클레임이 있습니다. 원본 값이 null이면 클레임은 미리 정의된 선택적 클레임입니다. 원본 값이 user이면 name 속성의 값은 user 개체의 확장 속성입니다.
`essential`	Edm.Boolean	이 값이 True이면 클라이언트가 지정한 클레임은 최종 사용자가 요청된 특정 태스크에 대한 원활한 권한 부여 환경을 보장하는 데 필요합니다. 기본값은 false입니다.
`additionalProperties`	컬렉션(Edm.String)	클레임의 다른 속성입니다. 속성이 이 컬렉션에 있으면 name 속성에 지정된 선택적 클레임의 동작을 수정합니다.

디렉터리 확장 선택적 클레임 구성

표준 선택적 클레임 세트 외에도 Microsoft Graph 확장을 포함하도록 토큰을 구성할 수도 있습니다. 자세한 내용은 확장을 사용하여 리소스에 사용자 지정 데이터 추가를 참조하세요.

Important

액세스 토큰은 항상 클라이언트가 아닌 리소스의 매니페스트를 사용하여 생성됩니다. 요청 ...scope=https://graph.microsoft.com/user.read...에서 리소스는 Microsoft Graph API입니다. 액세스 토큰은 클라이언트의 매니페스트가 아닌 Microsoft Graph API 매니페스트를 사용하여 생성됩니다. 애플리케이션에 대한 매니페스트를 변경해도 Microsoft Graph API에 대한 토큰이 다르게 보이지 않습니다. accessToken 변경 내용이 적용되는지 확인하기 위해 다른 앱이 아닌 애플리케이션에 대한 토큰을 요청합니다.

선택적 클레임은 확장 특성 및 디렉터리 확장을 지원합니다. 이 기능은 앱에서 사용할 수 있는 추가 사용자 정보를 첨부하는 데 유용합니다. 예를 들어 사용자가 설정한 다른 식별자 또는 중요한 구성 옵션입니다. 애플리케이션 매니페스트에서 사용자 지정 확장을 요청하고 MSA 사용자가 앱에 로그인하는 경우 이러한 확장은 반환되지 않습니다.

디렉터리 확장 서식 지정

애플리케이션 매니페스트를 사용하여 디렉터리 확장 선택적 클레임을 구성하는 경우 확장의 전체 이름(extension_<appid>_<attributename> 형식)을 사용합니다. <appid>은(는) 클레임을 요청하는 애플리케이션의 appId(또는 클라이언트 ID)가 제거된 버전입니다.

JWT 내에서 이러한 클레임은 extn.<attributename> 이름 형식을 사용하여 내보내집니다. SAML 토큰 내에서 이러한 클레임은 http://schemas.microsoft.com/identity/claims/extn.<attributename> URI 형식을 사용하여 내보내집니다.

그룹 선택적 클레임 구성

팁

이 문서의 단계는 시작하는 포털에 따라 약간 다를 수도 있습니다.

이 섹션에서는 그룹 클레임에서 사용되는 그룹 특성을 기본 그룹 objectID에서 온-프레미스 Windows Active Directory로 동기화되는 특성으로 변경하기 위한 선택적 클레임의 구성 옵션에 대해 설명합니다. Azure Portal 또는 애플리케이션 매니페스트를 통해 애플리케이션에 대한 그룹 선택적 클레임을 구성할 수 있습니다. 그룹 선택적 클레임은 사용자 보안 주체에 대한 JWT에서만 내보내집니다. 서비스 주체는 JWT에서 내보낸 그룹 선택적 클레임에 포함되지 않습니다.

Important

중첩된 그룹을 포함하여 토큰에서 내보내는 그룹의 수는 SAML 어설션의 경우 150개, JWT의 경우 200개로 제한됩니다. 온-프레미스 속성의 그룹 클레임에 대한 그룹 제한 및 중요한 주의 사항에 대한 자세한 내용은 애플리케이션에 대한 그룹 클레임 구성을 참조하세요.

다음 단계를 완료하여 Azure Portal을 사용하여 그룹 선택적 클레임을 구성합니다.

선택적 클레임을 구성할 애플리케이션을 선택합니다.
관리에서 토큰 구성을 선택합니다.
그룹 클레임 추가를 선택합니다.
반환할 그룹 유형(보안 그룹 또는 디렉터리 역할, 모든 그룹 및/또는 애플리케이션에 할당된 그룹)을 선택합니다.
- 애플리케이션에 할당된 그룹 옵션에는 애플리케이션에 할당된 그룹만 포함됩니다. 토큰의 그룹 수 제한으로 인해 대규모 조직에 애플리케이션에 할당된 그룹 옵션을 사용하는 것이 좋습니다. 애플리케이션에 할당된 그룹을 변경하려면 엔터프라이즈 애플리케이션 목록에서 애플리케이션을 선택합니다. 사용자 및 그룹을 선택한 다음, 사용자/그룹 추가를 선택합니다. 사용자 및 그룹에서 애플리케이션에 추가할 그룹을 선택합니다.
- 모든 그룹 옵션은 SecurityGroup, DirectoryRole 및 DistributionList를 포함하지만 애플리케이션에 할당된 그룹은 포함하지 않습니다.
선택 사항: 특정 토큰 유형 속성을 선택하여 온-프레미스 그룹 특성을 포함하도록 그룹 클레임 값을 수정하거나 클레임 유형을 역할로 변경합니다.
저장을 선택합니다.

애플리케이션 매니페스트를 통해 그룹 선택적 클레임을 구성하려면 다음 단계를 완료합니다.

선택적 클레임을 구성할 애플리케이션을 선택합니다.
관리에서 매니페스트를 선택합니다.
매니페스트 편집기를 사용하여 다음 항목을 추가합니다.

유효한 값은
- "All"(includes SecurityGroup, DirectoryRole 및 DistributionList 포함)
- "SecurityGroup"
- "DirectoryRole"
- "ApplicationGroup"(이 옵션은 애플리케이션에 할당된 그룹만 포함)
예시:
```
"groupMembershipClaims": "SecurityGroup"
```
기본적으로 그룹 ObjectID는 그룹 클레임 값으로 내보내집니다. 온-프레미스 그룹 특성을 포함하도록 클레임 값을 수정하거나 클레임 유형을 역할로 변경하려면 다음과 같이 optionalClaims 구성을 사용합니다.

그룹 이름 구성 선택적 클레임을 설정합니다.

토큰의 그룹이 선택적 클레임 섹션에서 온-프레미스 그룹 특성을 포함하도록 하려면 어떤 토큰 유형 선택적 클레임을 적용할지 지정합니다. 또한 요청된 선택적 클레임의 이름과 원하는 다른 속성을 지정합니다.

여러 토큰 유형이 나열될 수 있습니다.

OIDC ID 토큰의 경우 idToken
OAuth 액세스 토큰의 경우 accessToken
SAML 토큰의 경우 Saml2Token

Saml2Token 유형은 SAML 1.1 및 SAML 2.0 형식 모두의 토큰에 적용됩니다.

각 관련 토큰 유형에 대해 매니페스트의 optionalClaims 섹션을 사용하도록 그룹 클레임을 수정합니다. optionalClaims 스키마는 다음과 같습니다.

{
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
}

선택적 클레임 스키마	값
`name`	`groups`이어야 합니다.
`source`	사용되지 않습니다. 생략하거나 Null을 지정합니다.
`essential`	사용되지 않습니다. 생략하거나 false를 지정합니다.
`additionalProperties`	다른 속성 목록입니다. 유효한 옵션은 `sam_account_name`, `dns_domain_and_sam_account_name`, `netbios_domain_and_sam_account_name`, `emit_as_roles` 및 `cloud_displayname`입니다.

additionalProperties에서는 sam_account_name, dns_domain_and_sam_account_name 또는 netbios_domain_and_sam_account_name 중 하나만 필요합니다. 두 가지 이상의 속성이 있으면 첫 번째 속성이 사용되고 나머지는 무시됩니다. cloud_displayname을(를) 추가하여 클라우드 그룹의 표시 이름을 나타낼 수도 있습니다. 이 옵션은 groupMembershipClaims(이)가 ApplicationGroup(으)로 설정된 경우에만 실행됩니다.

일부 애플리케이션에는 역할 클레임에 사용자에 대한 그룹 정보가 필요합니다. 클레임 유형을 그룹 클레임에서 역할 클레임으로 변경하려면 additionalProperties에 emit_as_roles을(를) 추가합니다. 그룹 값은 역할 클레임에 내보내집니다.

사용되는 경우 emit_as_roles 사용자(또는 리소스 애플리케이션)가 할당된 모든 애플리케이션 역할이 역할 클레임에 없습니다.

다음 예제에서는 그룹 클레임에 대한 매니페스트 구성을 보여 줍니다.

그룹을 dnsDomainName\sAMAccountName 형식의 OAuth 액세스 토큰에서 그룹 이름으로 내보냅니다.

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

SAML 및 OIDC ID 토큰의 역할 할당으로 반환될 그룹 이름을 netbiosDomain\sAMAccountName 형식으로 내보냅니다.

"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ]
}

애플리케이션에 할당된 그룹에 대해 온-프레미스 동기화 그룹의 경우 sam_account_name 형식의 그룹 이름을, 클라우드 그룹의 경우 cloud_display 형식의 그룹 이름을 SAML 및 OIDC ID 토큰으로 전송합니다.

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

선택적 클레임 예제

애플리케이션 ID 구성에서 속성을 업데이트하여 선택적 클레임을 사용하도록 설정하고 구성하는 데 여러 옵션을 사용할 수 있습니다.

Azure Portal 사용 가능
매니페스트를 사용할 수 있습니다.
또한 Microsoft Graph API를 사용하는 애플리케이션을 작성하여 애플리케이션을 업데이트할 수 있습니다. Microsoft Graph API 참조 가이드의 OptionalClaims 형식은 선택적 클레임을 구성하는 데 유용할 수 있습니다.

다음 예제에서는 Azure 포털 및 매니페스트를 사용하여 애플리케이션을 위한 액세스, ID 및 SAML 토큰에 선택적 클레임을 추가합니다. 애플리케이션에서 수신할 수 있는 각 토큰 유형에 서로 다른 선택적 클레임이 추가되었습니다.

이제 ID 토큰에는 페더레이션 사용자의 UPN이 전체 형식으로 포함됩니다(<upn>_<homedomain>#EXT#@<resourcedomain>).
다른 클라이언트가 이 애플리케이션용으로 요청하는 액세스 토큰에는 이제 auth_time 클레임이 포함됩니다.
SAML 토큰은 skypeId 디렉터리 스키마 확장을 포함합니다(이 예제에서 이 앱의 앱 ID는 ab603c56068041afb2f6832e2a17e237임). SAML 토큰은 Skype ID를 extension_ab603c56068041afb2f6832e2a17e237_skypeId(으)로 노출합니다.

Azure Portal 클레임을 구성합니다.

선택적 클레임을 구성할 애플리케이션을 선택합니다.
관리에서 토큰 구성을 선택합니다.
선택적 클레임 추가를 선택하고 ID 토큰 유형을 선택한 다음, 클레임 목록에서 upn을 선택하고 추가를 선택합니다.
선택적 클레임 추가를 선택하고 액세스 토큰 유형을 선택한 다음, 클레임 목록에서 auth_time을 선택하고 추가를 선택합니다.
토큰 구성 개요 화면에서 upn 옆에 있는 연필 아이콘을 선택하고, 외부적으로 인증됨 토글을 선택한 후 저장을 선택합니다.
선택적 클레임 추가를 선택하고, SAML 토큰 유형을 선택한 후 클레임 목록에서 extn.skypeID를 선택하고(skypeID라는 Microsoft Entra 사용자 개체를 만든 경우에만 해당) 추가를 선택합니다.

매니페스트에서 클레임을 구성합니다.

선택적 클레임을 구성할 애플리케이션을 선택합니다.
관리에서 매니페스트를 선택하여 인라인 매니페스트 편집기를 엽니다.

이 편집기를 사용하여 매니페스트를 직접 편집할 수 있습니다. 매니페스트는 애플리케이션 엔터티의 스키마를 따르며, 저장된 매니페스트의 서식을 자동으로 지정합니다. 새 요소가 optionalClaims 속성에 추가됩니다.

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ],
    "accessToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": true
        }
    ]
}

매니페스트 업데이트가 끝나면 저장을 선택하여 매니페스트를 저장합니다.

제한 사항

애플리케이션은 선택적 클레임으로 최대 10명의 확장 특성을 발급할 수 있습니다.

다음을 통해 공유

선택적 클레임 구성

필수 조건

애플리케이션에서 선택적 클레임 구성

디렉터리 확장 선택적 클레임 구성

디렉터리 확장 서식 지정

그룹 선택적 클레임 구성

선택적 클레임 예제

제한 사항

피드백

추가 리소스

다음을 통해 공유

선택적 클레임 구성

필수 조건

애플리케이션에서 선택적 클레임 구성

디렉터리 확장 선택적 클레임 구성

디렉터리 확장 서식 지정

그룹 선택적 클레임 구성

선택적 클레임 예제

제한 사항

관련 콘텐츠

피드백

추가 리소스