앱에 선택적 클레임 제공 - Microsoft Entra (2023)

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

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

표준 클레임 목록은 다음을 참조하세요.액세스 토큰그리고id_token청구 문서.

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

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

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

다음 표에는 v1.0 및 v2.0 선택적 클레임 집합이 나열되어 있습니다.

v2.0 전용 선택적 클레임 세트

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

v1.0 전용 선택적 클레임 세트

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

추가 속성선택적 클레임

일부 선택적 클레임은 클레임이 반환되는 방식을 변경하도록 구성할 수 있습니다. 이것들추가 속성데이터 기대치가 다른 온프레미스 애플리케이션의 마이그레이션을 지원하는 데 주로 사용됩니다. 예를 들어,include_externally_authenticated_upn_without_hash해시 마크를 처리할 수 없는 고객에게 도움이 됩니다(#) UPN에서.

추가 속성예

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

이것optionalClaims객체로 인해 클라이언트에 반환된 ID 토큰은 다음을 포함합니다.업다른 주택 임차인 및 리소스 임차인 정보로 청구합니다. 그만큼업클레임은 사용자가 테넌트의 게스트인 경우에만 토큰에서 변경됩니다(인증에 다른 IDP 사용).

선택적 클레임 구성

Azure Portal 또는 애플리케이션 매니페스트를 통해 애플리케이션에 대한 선택적 클레임을 구성할 수 있습니다.

1. 로 이동Azure 포털.
2. 검색 및 선택Azure 액티브 디렉터리.
3. 아래에관리하다, 선택하다앱 등록.
4. 시나리오 및 원하는 결과에 따라 선택적 클레임을 구성할 애플리케이션을 선택합니다.
5. 아래에관리하다, 선택하다토큰 구성.
   • UI 옵션토큰 구성애플리케이션 매니페스트를 수정하여 구성할 수 있는 Azure AD B2C 테넌트에 등록된 앱에는 블레이드를 사용할 수 없습니다. 자세한 내용은 다음을 참조하십시오.Azure Active Directory B2C에서 사용자 지정 정책을 사용하여 클레임을 추가하고 사용자 입력을 사용자 지정합니다.

매니페스트를 사용하여 클레임을 구성합니다.

1. 선택하다선택적 클레임 추가.

2. 구성하려는 토큰 유형을 선택합니다.

3. 추가할 선택적 클레임을 선택합니다.

4. 선택하다추가하다.

5. 아래에관리하다, 선택하다명백한. 웹 기반 매니페스트 편집기가 열리고 매니페스트를 편집할 수 있습니다. 선택적으로 다음을 선택할 수 있습니다.다운로드로컬에서 매니페스트를 편집한 다음업로드응용 프로그램에 다시 적용합니다.

   다음 애플리케이션 매니페스트 항목은auth_time,아이패드, 그리고업ID, 액세스 및 SAML 토큰에 대한 선택적 클레임.

   (Video) Microsoft ID 플랫폼을 사용한 토큰 사용자 지정

   "optionalClaims": { "idToken": [ { "name": "auth_time", "essential": false } ], "accessToken": [ { "name": "ipaddr", "essential": false } ], " saml2Token": [ { "이름": "upn", "필수": 거짓 }, { "이름": "extension_ab603c56068041afb2f6832e2a17e237_skypeId", "소스": "사용자", "필수": 거짓 } ]}

6. 완료되면 선택구하다. 이제 지정된 선택적 클레임이 애플리케이션의 토큰에 포함됩니다.

그만큼optionalClaims개체는 응용 프로그램에서 요청한 선택적 클레임을 선언합니다. 애플리케이션은 ID 토큰, 액세스 토큰 및 SAML 2 토큰에서 반환되는 선택적 클레임을 구성할 수 있습니다. 애플리케이션은 각 토큰 유형에서 반환될 다양한 선택적 클레임 집합을 구성할 수 있습니다.

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

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

표준 선택적 클레임 집합 외에도 Microsoft Graph 확장을 포함하도록 토큰을 구성할 수도 있습니다. 자세한 내용은 다음을 참조하십시오.확장 프로그램을 사용하여 리소스에 사용자 지정 데이터 추가.

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

디렉토리 확장 형식

애플리케이션 매니페스트를 사용하여 디렉터리 확장 선택적 클레임을 구성할 때 확장의 전체 이름(형식:extension__<속성 이름>). 그만큼<신청>클레임을 요청하는 애플리케이션의 appId(또는 클라이언트 ID)의 제거된 버전입니다.

JWT 내에서 이러한 클레임은 다음 이름 형식으로 내보냅니다.extn.<속성 이름>. SAML 토큰 내에서 이러한 클레임은 다음 URI 형식으로 내보내집니다.http://schemas.microsoft.com/identity/claims/extn.<속성 이름>

그룹 선택적 클레임 구성

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

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

1. 에 로그인Azure 포털.
2. 인증한 후 페이지의 오른쪽 상단 모서리에서 선택하여 테넌트를 선택합니다.
3. 검색 및 선택Azure 액티브 디렉터리.
4. 아래에관리하다, 선택하다앱 등록.
5. 목록에서 선택적 클레임을 구성하려는 애플리케이션을 선택합니다.
6. 아래에관리하다, 선택하다토큰 구성.
7. 선택하다그룹 클레임 추가.
8. 반환할 그룹 유형을 선택합니다(보안 그룹, 또는디렉터리 역할,모든 그룹, 및/또는애플리케이션에 할당된 그룹):
   • 그만큼애플리케이션에 할당된 그룹옵션에는 애플리케이션에 할당된 그룹만 포함됩니다. 그만큼애플리케이션에 할당된 그룹옵션은 토큰의 그룹 수 제한으로 인해 대규모 조직에 권장됩니다. 애플리케이션에 할당된 그룹을 변경하려면 목록에서 애플리케이션을 선택합니다.엔터프라이즈 애플리케이션목록. 선택하다사용자 및 그룹그런 다음사용자/그룹 추가. 애플리케이션에 추가할 그룹을 선택하십시오.사용자 및 그룹.
   • 그만큼모든 그룹옵션 포함보안 그룹,디렉토리역할, 그리고배포 목록, 하지만애플리케이션에 할당된 그룹.
9. 선택 사항: 특정 토큰 유형 속성을 선택하여 온프레미스 그룹 속성을 포함하도록 그룹 클레임 값을 수정하거나 클레임 유형을 역할로 변경합니다.
10. 선택하다구하다.

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

1. 에 로그인Azure 포털.

   (Video) Microsoft Store 앱 문제를 해결하는 방법 | 마이크로소프트

2. 인증한 후 페이지의 오른쪽 위 모서리에서 선택하여 Azure AD 테넌트를 선택합니다.

3. 검색 및 선택Azure 액티브 디렉터리.

4. 목록에서 선택적 클레임을 구성하려는 애플리케이션을 선택합니다.

5. 아래에관리하다, 선택하다명백한.

6. 매니페스트 편집기를 사용하여 다음 항목을 추가합니다.

   유효한 값은 다음과 같습니다.

   • "모두"(이 옵션에는 SecurityGroup, DirectoryRole 및 DistributionList가 포함됨)
   • "보안그룹"
   • "디렉토리 역할"
   • "ApplicationGroup"(이 옵션에는 애플리케이션에 할당된 그룹만 포함됨)

   예를 들어:

   "groupMembershipClaims": "보안 그룹"

   기본적으로 그룹 개체 ID는 그룹 클레임 값에서 내보냅니다. 온프레미스 그룹 속성을 포함하도록 클레임 값을 수정하거나 클레임 유형을 역할로 변경하려면optionalClaims다음과 같은 구성:

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

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

   여러 토큰 유형을 나열할 수 있습니다.

   • OIDC ID 토큰용 idToken
   • OAuth 액세스 토큰에 대한 accessToken
   • SAML 토큰용 Saml2Token.

   Saml2Token 유형은 SAML1.1 및 SAML2.0 형식 토큰 모두에 적용됩니다.

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

   { "이름": "그룹", "소스": null, "필수": 거짓, "추가 속성": []}

   선택적 클레임 스키마	값
   이름	반드시여러 떼
   원천	사용되지 않습니다. null을 생략하거나 지정합니다.
   필수적인	사용되지 않습니다. false를 생략하거나 지정하십시오.
   추가 속성	다른 속성 목록입니다. 유효한 옵션은 다음과 같습니다.sam_account_name,dns_domain_and_sam_account_name,netbios_domain_and_sam_account_name,emit_as_roles그리고cloud_displayname.

   ~ 안에추가 속성중 하나만sam_account_name,dns_domain_and_sam_account_name,netbios_domain_and_sam_account_name필요합니다. 둘 이상이 있는 경우 첫 번째 항목이 사용되고 다른 항목은 무시됩니다. 당신은 또한 추가할 수 있습니다cloud_displayname클라우드 그룹의 표시 이름을 내보냅니다. 이 옵션은 다음과 같은 경우에만 작동합니다.그룹 멤버십 클레임로 설정애플리케이션 그룹.

   (Video) Teams 모바일 앱으로 Microsoft Teams 모임에 참여하는 방법 | 마이크로소프트

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

   만약에emit_as_roles가 사용되면 사용자에게 할당되도록 구성된 모든 애플리케이션 역할이 역할 클레임에 포함되지 않습니다.

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

OAuth 액세스 토큰에서 그룹 이름으로 그룹 내보내기dns도메인 이름\sAM계정 이름체재.

"optionalClaims": { "accessToken": [ { "이름": "그룹", "additionalProperties": [ "dns_domain_and_sam_account_name" ] } ]}

반환할 그룹 이름을 내보냅니다.netbios도메인\sAM계정 이름SAML 및 OIDC ID 토큰의 역할 클레임 형식입니다.

"optionalClaims": { "saml2Token": [ { "name": "groups", "additionalProperties": [ "netbios_domain_and_sam_account_name", "emit_as_roles" ] } ], "idToken": [ { "name": "groups", " 추가 속성": [ "netbios_domain_and_sam_account_name", "emit_as_roles" ] } ]}

형식으로 그룹 이름을 내보냅니다.sam_account_name온프레미스 동기화 그룹 및cloud_displaySAML의 클라우드 그룹 이름 및 애플리케이션에 할당된 그룹의 OIDC ID 토큰.

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

선택적 클레임 예

선택적 클레임을 활성화하고 구성하기 위해 애플리케이션 ID 구성의 속성을 업데이트하는 데 사용할 수 있는 여러 옵션이 있습니다.

• Azure Portal을 사용할 수 있습니다.
• 매니페스트를 사용할 수 있습니다.
• 를 사용하는 애플리케이션을 작성하는 것도 가능합니다.마이크로소프트 그래프 API애플리케이션을 업데이트합니다. 그만큼선택적 클레임Microsoft Graph API 참조 가이드에 입력하면 선택적 클레임 구성에 도움이 됩니다.

다음 예제에서는 Azure Portal 및 매니페스트를 사용하여 애플리케이션용 액세스, ID 및 SAML 토큰에 선택적 클레임을 추가합니다. 애플리케이션이 받을 수 있는 각 유형의 토큰에 서로 다른 선택적 클레임이 추가됩니다.

• ID 토큰에는 전체 형식(_<홈도메인>#EXT#@<리소스도메인>).
• 다른 클라이언트가 이 애플리케이션에 대해 요청하는 액세스 토큰에는 다음이 포함됩니다.auth_time주장하다.
• SAML 토큰에는스카이프 아이디디렉터리 스키마 확장(이 예에서 이 앱의 앱 ID는ab603c56068041afb2f6832e2a17e237). SAML 토큰은 Skype ID를 다음과 같이 노출합니다.extension_ab603c56068041afb2f6832e2a17e237_skypeId.

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

1. 에 로그인Azure 포털.
2. 인증한 후 페이지의 오른쪽 상단 모서리에서 선택하여 테넌트를 선택합니다.
3. 검색 및 선택Azure 액티브 디렉터리.
4. 아래에관리하다, 선택하다앱 등록.
5. 목록에서 선택적 클레임을 구성하려는 애플리케이션을 찾아 선택합니다.
6. 아래에관리하다, 선택하다토큰 구성.
7. 선택하다선택적 클레임 추가, 선택ID토큰 유형, 선택업클레임 목록에서 다음을 선택합니다.추가하다.
8. 선택하다선택적 클레임 추가, 선택입장토큰 유형, 선택auth_time클레임 목록에서 다음을 선택합니다.추가하다.
9. 토큰 구성 개요 화면에서 옆에 있는 연필 아이콘을 선택합니다.업, 선택외부 인증전환한 다음 선택구하다.
10. 선택하다선택적 클레임 추가, 선택SAML토큰 유형, 선택extn.스카이프 ID클레임 목록에서(skypeID라는 Azure AD 사용자 개체를 만든 경우에만 해당) 다음을 선택합니다.추가하다.

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

1. 에 로그인Azure 포털.

2. 인증한 후 페이지의 오른쪽 상단 모서리에서 선택하여 테넌트를 선택합니다.

3. 검색 및 선택Azure 액티브 디렉터리.

4. 목록에서 선택적 클레임을 구성하려는 애플리케이션을 찾아 선택합니다.

   (Video) Microsoft 365 Admin 모바일 앱을 얻는 방법

5. 아래에관리하다, 선택하다명백한인라인 매니페스트 편집기를 엽니다.

6. 이 편집기를 사용하여 매니페스트를 직접 편집할 수 있습니다. 매니페스트는 다음에 대한 스키마를 따릅니다.애플리케이션 엔터티, 저장되면 매니페스트를 자동으로 포맷합니다. 에 새로운 요소가 추가됩니다.optionalClaims재산.

   "optionalClaims": { "idToken": [ { "name": "upn", "essential": false, "additionalProperties": [ "include_externally_authenticated_upn" ] } ], "accessToken": [ { "name": "auth_time" , "필수": 거짓 } ], "saml2Token": [ { "이름": "extension_ab603c56068041afb2f6832e2a17e237_skypeId", "소스": "사용자", "필수": 참 } ]}

7. 매니페스트 업데이트를 마치면 다음을 선택합니다.구하다매니페스트를 저장합니다.

또한보십시오

• 애플리케이션 매니페스트
• ID 토큰
• 액세스 토큰

다음 단계

• 자세히 알아보기토큰 및 클레임Microsoft ID 플랫폼에서.