역할 클레임 구성

아티클
06/27/2024

애플리케이션이 승인된 후 수신된 액세스 토큰에서 역할 청구를 사용자 정의할 수 있습니다. 애플리케이션은 토큰에 사용자 지정 역할이 필요한 경우 이 기능을 사용합니다. 역할을 필요한 만큼 추가할 수 있습니다.

필수 조건

구성된 테넌트가 있는 Microsoft Entra 구독입니다. 자세한 내용은 빠른 시작: 테넌트 설정을 참조하세요.
테넌트에 추가된 엔터프라이즈 애플리케이션. 자세한 내용은 빠른 시작: 엔터프라이즈 애플리케이션 추가를 참조하세요.
애플리케이션에 대해 구성된 SSO(Single Sign-On). 자세한 내용은 엔터프라이즈 애플리케이션에 Single Sign-On 사용을 참조하세요.
역할에 할당된 사용자 계정입니다. 자세한 내용은 빠른 시작: 사용자 계정 만들기 및 할당을 참조하세요.

참고 항목

이 문서에서는 API를 사용하여 서비스 주체에 대한 애플리케이션 역할을 만들거나, 업데이트하거나, 삭제하는 방법을 설명합니다. 앱 역할에 새 사용자 인터페이스를 사용하려면 애플리케이션에 앱 역할을 추가하고 토큰으로 받기를 참조하세요.

엔터프라이즈 애플리케이션 찾기

팁

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

다음 단계에 따라 엔터프라이즈 애플리케이션을 찾습니다.

최소한 클라우드 애플리케이션 관리자로 Microsoft Entra 관리 센터에 로그인합니다.
ID>애플리케이션>엔터프라이즈 애플리케이션>모든 애플리케이션으로 이동합니다.
검색 상자에서 기존 애플리케이션 이름을 입력한 다음, 검색 결과에서 애플리케이션을 선택합니다.
애플리케이션이 선택된 후 개요 창에서 개체 ID를 복사합니다.

역할 추가

Microsoft Graph Explorer를 사용하여 엔터프라이즈 애플리케이션에 역할을 추가합니다.

다른 창에서 Microsoft Graph Explorer를 열고 테넌트에 대한 관리자 자격 증명을 사용하여 로그인합니다.

참고 항목

클라우드 애플리케이션 관리자 및 애플리케이션 관리자 역할은 이 시나리오에서 작동하지 않습니다. 권한 있는 역할 관리자를 사용합니다.
권한 수정을 선택하고 목록의 Application.ReadWrite.All 및 Directory.ReadWrite.All 권한에 대한 동의를 선택합니다.
다음 요청에서 <objectID>를 이전에 기록된 개체 ID로 바꾼 다음, 쿼리를 실행합니다.

https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>

엔터프라이즈 애플리케이션을 서비스 주체라고도 합니다. 반환된 서비스 주체 개체에서 appRoles 속성을 기록합니다. 다음 예제에서는 일반적인 appRoles 속성을 보여 줍니다.

{
  "appRoles": [
    {
      "allowedMemberTypes": [
        "User"
      ],
      "description": "msiam_access",
      "displayName": "msiam_access",
      "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "isEnabled": true,
      "origin": "Application",
      "value": null
    }
  ]
}

Graph Explorer에서 메서드를 GET에서 PATCH로 변경합니다.
이전에 Graph Explorer의 요청 본문 창에 기록된 appRoles 속성을 복사하고, 새 역할 정의를 추가한 다음, 쿼리 실행을 선택하여 패치 작업을 실행합니다. 성공 메시지가 나타나 역할 생성을 확인합니다. 다음 예제에서는 관리자 역할 추가를 보여 줍니다.
```
{
  "appRoles": [
    {
      "allowedMemberTypes": [
        "User"
      ],
      "description": "msiam_access",
      "displayName": "msiam_access",
      "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
      "isEnabled": true,
      "origin": "Application",
      "value": null
    },
    {
      "allowedMemberTypes": [
        "User"
      ],
      "description": "Administrators Only",
      "displayName": "Admin",
      "id": "11bb11bb-cc22-dd33-ee44-55ff55ff55ff",
      "isEnabled": true,
      "origin": "ServicePrincipal",
      "value": "Administrator"
    }
  ]
}
```
요청 본문에 새 역할 외에도 msiam_access 역할 개체를 포함해야 합니다. 요청 본문에 기존 역할을 포함하지 않으면 appRoles 개체에서 제거됩니다. 또한 조직 요구에 따라 원하는 만큼의 역할을 추가할 수 있습니다. 이러한 역할의 값은 SAML 응답의 클레임 값으로 전송됩니다. 새 역할의 ID에 대한 GUID 값을 생성하려면 온라인 GUID/UUID 생성기와 같은 웹 도구를 사용합니다. 응답의 appRoles 속성에는 쿼리의 요청 본문에 있던 항목이 포함됩니다.

특성 편집

토큰에 포함된 역할 클레임을 정의하도록 특성을 업데이트합니다.

Microsoft Entra 관리 센터에서 애플리케이션을 찾은 다음 왼쪽 메뉴에서 Single Sign-On을 선택합니다.
특성 및 클레임 섹션에서 편집을 선택합니다.
새 클레임 추가를 선택합니다.
이름 상자에 특성 이름을 입력합니다. 이 예에서는 클레임 이름으로 역할 이름을 사용합니다.
네임스페이스 상자를 비워 둡니다.
원본 특성 목록에서 user.assignedroles를 선택합니다.
저장을 선택합니다. 이제 새 역할 이름 특성이 특성 및 클레임 섹션에 표시됩니다. 이제 애플리케이션에 로그인할 때 클레임이 액세스 토큰에 포함되어야 합니다.

역할 할당

서비스 사용자에 더 많은 역할이 패치되면 각 역할에 사용자를 할당할 수 있습니다.

Microsoft Entra 관리 센터에서 역할이 추가된 애플리케이션을 찾습니다.
왼쪽 메뉴에서 사용자 및 그룹을 선택한 다음, 새 역할을 할당하려는 사용자를 선택합니다.
창 위쪽에서 할당 편집을 선택하여 역할을 변경합니다.
선택된 항목 없음을 선택하고, 목록에서 역할을 선택한 다음, 선택을 선택합니다.
할당을 선택하여 사용자에게 역할을 할당합니다.

역할 업데이트

기존 역할을 업데이트하려면 다음 단계를 수행합니다.

Microsoft Graph Explorer를 엽니다.
Graph Explorer 사이트에 권한 있는 역할 관리자로 로그인합니다.
개요 창에서 애플리케이션의 개체 ID를 사용하여 다음 요청의 <objectID>를 해당 개체 ID로 바꾼 다음, 쿼리를 실행합니다.

https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>
반환된 서비스 주체 개체에서 appRoles 속성을 기록합니다.
Graph Explorer에서 메서드를 GET에서 PATCH로 변경합니다.
이전에 Graph Explorer의 요청 본문 창에 기록된 appRoles 속성을 복사하고, 역할 정의를 추가/업데이트한 다음, 쿼리 실행을 선택하여 패치 작업을 실행합니다.

역할 삭제

기존 역할을 삭제하려면 다음 단계를 수행합니다.

Microsoft Graph Explorer를 엽니다.
Graph Explorer 사이트에 권한 있는 역할 관리자로 로그인합니다.
Azure Portal의 개요 창에서 애플리케이션의 개체 ID를 사용하여 다음 요청의 <objectID>를 해당 개체 ID로 바꾼 다음, 쿼리를 실행합니다.

https://graph.microsoft.com/v1.0/servicePrincipals/<objectID>
반환된 서비스 주체 개체에서 appRoles 속성을 기록합니다.
Graph Explorer에서 메서드를 GET에서 PATCH로 변경합니다.
이전에 Graph Explorer의 요청 본문 창에 기록된 appRoles 속성을 복사하고, 삭제하려는 역할에 대해 IsEnabled 값을 false로 설정한 다음, 쿼리 실행을 선택하여 패치 작업을 실행합니다. 삭제하려면 먼저 역할을 사용하지 않도록 설정해야 합니다.
역할이 비활성화되면 appRoles 섹션에서 해당 역할 블록을 삭제합니다. 메서드를 PATCH로 유지하고 쿼리 실행을 다시 선택합니다.

다음 단계

클레임 사용자 지정에 대한 자세한 내용은 엔터프라이즈 애플리케이션에 대한 SAML 토큰에서 발급된 클레임 사용자 지정을 참조하세요.

다음을 통해 공유