REST API를 사용하여 Azure 사용자 지정 역할을 만들거나 업데이트하기

아티클
02/23/2024

Azure 기본 제공 역할이 조직의 특정 요구 사항을 충족하지 않는 경우 사용자 지정 역할을 만들면 됩니다. 이 문서에서는 REST API를 사용하여 사용자 지정 역할을 나열하고, 만들고, 업데이트하고, 삭제하는 방법을 설명합니다.

필수 조건

다음 버전을 사용해야 합니다.

2015-07-01 이상

자세한 내용은 Azure RBAC REST API의 API 버전을 참조하세요.

모든 사용자 지정 역할 정의 나열

테넌트의 모든 사용자 지정 역할 정의를 나열하려면 역할 정의 - 목록 REST API를 사용합니다.

다음 예제에서는 테넌트의 모든 사용자 지정 역할 정의를 나열합니다.

Request

GET https://management.azure.com/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01

Response

{
    "value": [
        {
            "properties": {
                "roleName": "Billing Reader Plus",
                "type": "CustomRole",
                "description": "Read billing data and download invoices",
                "assignableScopes": [
                    "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
                ],
                "permissions": [
                    {
                        "actions": [
                            "Microsoft.Authorization/*/read",
                            "Microsoft.Billing/*/read",
                            "Microsoft.Commerce/*/read",
                            "Microsoft.Consumption/*/read",
                            "Microsoft.Management/managementGroups/read",
                            "Microsoft.CostManagement/*/read",
                            "Microsoft.Billing/invoices/download/action",
                            "Microsoft.CostManagement/exports/*"
                        ],
                        "notActions": [
                            "Microsoft.CostManagement/exports/delete"
                        ],
                        "dataActions": [],
                        "notDataActions": []
                    }
                ],
                "createdOn": "2021-05-22T21:57:23.5764138Z",
                "updatedOn": "2021-05-22T21:57:23.5764138Z",
                "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
                "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
            },
            "id": "/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
            "type": "Microsoft.Authorization/roleDefinitions",
            "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
        }
    ]
}

범위에서 모든 사용자 지정 역할 정의 나열

범위에서 사용자 지정 역할 정의를 나열하려면 역할 정의 - 목록 REST API를 사용합니다.

다음 요청으로 시작합니다.

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01

URI 내에서 {scope}를 나열하려는 역할에 대한 범위로 바꿉니다.

범위	Type
`subscriptions/{subscriptionId1}`	구독
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	리소스
`providers/Microsoft.Management/managementGroups/{groupId1}`	관리 그룹

{Filter}를 역할 유형으로 바꿉니다.

필터	설명
`$filter=type+eq+'CustomRole'`	CustomRole 유형을 기반으로 필터링하기

다음 예제에서는 구독의 모든 사용자 지정 역할 정의를 나열합니다.

Request

GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions?$filter=type+eq+'CustomRole'&api-version=2022-04-01

Response

{
    "value": [
        {
            "properties": {
                "roleName": "Billing Reader Plus",
                "type": "CustomRole",
                "description": "Read billing data and download invoices",
                "assignableScopes": [
                    "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
                ],
                "permissions": [
                    {
                        "actions": [
                            "Microsoft.Authorization/*/read",
                            "Microsoft.Billing/*/read",
                            "Microsoft.Commerce/*/read",
                            "Microsoft.Consumption/*/read",
                            "Microsoft.Management/managementGroups/read",
                            "Microsoft.CostManagement/*/read",
                            "Microsoft.Billing/invoices/download/action",
                            "Microsoft.CostManagement/exports/*"
                        ],
                        "notActions": [
                            "Microsoft.CostManagement/exports/delete"
                        ],
                        "dataActions": [],
                        "notDataActions": []
                    }
                ],
                "createdOn": "2021-05-22T21:57:23.5764138Z",
                "updatedOn": "2021-05-22T21:57:23.5764138Z",
                "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
                "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
            },
            "id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
            "type": "Microsoft.Authorization/roleDefinitions",
            "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
        }
    ]
}

이름별로 사용자 지정 역할 정의 나열하기

표시 이름별로 사용자 지정 역할 정의에 대한 정보를 가져오려면 역할 정의 - 가져오기 REST API를 사용합니다.

다음 요청으로 시작합니다.

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions?$filter={filter}&api-version=2022-04-01

URI 내에서 {scope}를 나열하려는 역할에 대한 범위로 바꿉니다.

범위	Type
`subscriptions/{subscriptionId1}`	구독
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	리소스
`providers/Microsoft.Management/managementGroups/{groupId1}`	관리 그룹

{Filter}를 역할의 표시 이름으로 바꿉니다.

필터	설명
`$filter=roleName+eq+'{roleDisplayName}'`	역할의 정확한 표시 이름에 대한 URL 인코딩 형식을 사용합니다. 예를 들어, `$filter=roleName+eq+'Virtual%20Machine%20Contributor'`

다음 예제에서는 구독에서 Billing Reader Plus라는 사용자 지정 역할 정의를 나열합니다.

Request

GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions?$filter=roleName+eq+'Billing Reader Plus'&api-version=2022-04-01

Response

{
    "value": [
        {
            "properties": {
                "roleName": "Billing Reader Plus",
                "type": "CustomRole",
                "description": "Read billing data and download invoices",
                "assignableScopes": [
                    "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
                ],
                "permissions": [
                    {
                        "actions": [
                            "Microsoft.Authorization/*/read",
                            "Microsoft.Billing/*/read",
                            "Microsoft.Commerce/*/read",
                            "Microsoft.Consumption/*/read",
                            "Microsoft.Management/managementGroups/read",
                            "Microsoft.CostManagement/*/read",
                            "Microsoft.Billing/invoices/download/action",
                            "Microsoft.CostManagement/exports/*"
                        ],
                        "notActions": [
                            "Microsoft.CostManagement/exports/delete"
                        ],
                        "dataActions": [],
                        "notDataActions": []
                    }
                ],
                "createdOn": "2021-05-22T21:57:23.5764138Z",
                "updatedOn": "2021-05-22T21:57:23.5764138Z",
                "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
                "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
            },
            "id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
            "type": "Microsoft.Authorization/roleDefinitions",
            "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
        }
    ]
}

ID 별로 사용자 지정 역할 정의 나열하기

고유 식별자별로 사용자 지정 역할 정의에 대한 정보를 가져오려면 역할 정의 - 가져오기 REST API를 사용합니다.

역할 정의 - 나열 REST API를 사용하여 역할에 대한 GUID 식별자를 가져옵니다.

다음 요청으로 시작합니다.

GET https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

URI 내에서 {scope}를 나열하려는 역할에 대한 범위로 바꿉니다.

범위	Type
`subscriptions/{subscriptionId1}`	구독
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}/providers/Microsoft.Web/sites/{site1}`	리소스
`providers/Microsoft.Management/managementGroups/{groupId1}`	관리 그룹

{roleDefinitionId}를 역할 정의의 GUID 식별자로 바꿉니다.

다음 예제에서는 구독에서 식별자가 17adabda-4bf1-4f4e-8c97-1f0cab6dea1c인 사용자 지정 역할 정의를 나열합니다.

Request

GET https://management.azure.com/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c?api-version=2022-04-01

Response

{
    "properties": {
        "roleName": "Billing Reader Plus",
        "type": "CustomRole",
        "description": "Read billing data and download invoices",
        "assignableScopes": [
            "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Authorization/*/read",
                    "Microsoft.Billing/*/read",
                    "Microsoft.Commerce/*/read",
                    "Microsoft.Consumption/*/read",
                    "Microsoft.Management/managementGroups/read",
                    "Microsoft.CostManagement/*/read",
                    "Microsoft.Billing/invoices/download/action",
                    "Microsoft.CostManagement/exports/*"
                ],
                "notActions": [
                    "Microsoft.CostManagement/exports/delete"
                ],
                "dataActions": [],
                "notDataActions": []
            }
        ],
        "createdOn": "2021-05-22T21:57:23.5764138Z",
        "updatedOn": "2021-05-22T21:57:23.5764138Z",
        "createdBy": "68f66d4c-c0eb-4009-819b-e5315d677d70",
        "updatedBy": "68f66d4c-c0eb-4009-819b-e5315d677d70"
    },
    "id": "/subscriptions/473a4f86-11e3-48cb-9358-e13c220a2f15/providers/Microsoft.Authorization/roleDefinitions/17adabda-4bf1-4f4e-8c97-1f0cab6dea1c",
    "type": "Microsoft.Authorization/roleDefinitions",
    "name": "17adabda-4bf1-4f4e-8c97-1f0cab6dea1c"
}

사용자 지정 역할 만들기

사용자 지정 역할을 만들려면 역할 정의 - 만들기 또는 업데이트 REST API를 사용합니다. 해당 API를 호출하려면 모든 assignableScopes에 대한 Microsoft.Authorization/roleDefinitions/write권한이 있는 역할이 할당된 사용자로 로그인해야 합니다. 기본 제공 역할의 경우 Owner 및 User Access Administrator만 해당 권한을 가집니다.

사용자 지정 역할에 대한 권한을 만드는 데 사용할 수 있는 리소스 공급자 작업 목록을 검토합니다.
GUID 도구를 사용하여 사용자 지정 역할 식별자에 사용할 고유 식별자를 생성합니다. 식별자의 형식은 00000000-0000-0000-0000-000000000000입니다.

다음 요청 및 본문으로 시작합니다.

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

{
  "name": "{roleDefinitionId}",
  "properties": {
    "roleName": "",
    "description": "",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [

        ],
        "notActions": [

        ]
      }
    ],
    "assignableScopes": [
      "/subscriptions/{subscriptionId1}",
      "/subscriptions/{subscriptionId2}",
      "/subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}",
      "/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroup2}",
      "/providers/Microsoft.Management/managementGroups/{groupId1}"
    ]
  }
}

URI 내에서 {scope}를 사용자 지정 역할의 첫 번째 assignableScopes로 바꿉니다.

범위	Type
`subscriptions/{subscriptionId1}`	구독
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`providers/Microsoft.Management/managementGroups/{groupId1}`	관리 그룹

{roleDefinitionId}를 사용자 지정 역할의 GUID 식별자로 바꿉니다.
요청 본문 내에서 {roleDefinitionId}를 GUID 식별자로 바꿉니다.
assignableScopes이 구독 또는 리소스 그룹인 경우 {subscriptionId} 또는 {resourceGroup} 인스턴스를 사용자의 식별자로 바꿉니다.
assignableScopes이 관리 그룹인 경우 {groupId} 인스턴스를 관리 그룹 식별자로 바꿉니다.
actions 속성에서 역할에서 수행할 수 있는 작업을 추가합니다.
notActions 속성에서 허용된 actions로부터 제외되는 작업을 추가합니다.

roleName 및 description 속성에서 고유한 역할 이름 및 설명을 지정합니다. 속성에 대한 자세한 내용은 Azure 사용자 지정 역할을 참조하세요.

요청 본문의 예제는 다음과 같습니다.

{
  "name": "88888888-8888-8888-8888-888888888888",
  "properties": {
    "roleName": "Virtual Machine Operator",
    "description": "Can monitor and restart virtual machines.",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [
          "Microsoft.Storage/*/read",
          "Microsoft.Network/*/read",
          "Microsoft.Compute/*/read",
          "Microsoft.Compute/virtualMachines/start/action",
          "Microsoft.Compute/virtualMachines/restart/action",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Support/*"
        ],
        "notActions": []
      }
    ],
    "assignableScopes": [
      "/subscriptions/00000000-0000-0000-0000-000000000000",
      "/providers/Microsoft.Management/managementGroups/marketing-group"
    ]
  }
}

사용자 지정 역할 업데이트

사용자 지정 역할을 업데이트하려면 역할 정의 - 만들기 또는 업데이트 REST API를 사용합니다. 이 API를 호출하려면 사용자 액세스 관리자와 같이 모든 assignableScopes에 대해 Microsoft.Authorization/roleDefinitions/write 권한이 있는 역할이 할당된 사용자로 로그인해야 합니다.

역할 정의 - 나열 또는 역할 정의 - 가져오기 REST API를 사용하여 사용자 지정 역할에 대한 정보를 가져옵니다. 자세한 내용은 앞에서 설명한 모든 사용자 지정 역할 정의 나열 섹션을 참조하세요.

다음 요청으로 시작합니다.

PUT https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

URI 내에서 {scope}를 사용자 지정 역할의 첫 번째 assignableScopes로 바꿉니다.

범위	Type
`subscriptions/{subscriptionId1}`	구독
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`providers/Microsoft.Management/managementGroups/{groupId1}`	관리 그룹

{roleDefinitionId}를 사용자 지정 역할의 GUID 식별자로 바꿉니다.

사용자 지정 역할에 대한 정보에 따라 다음 형식의 요청 본문을 만듭니다.

{
  "name": "{roleDefinitionId}",
  "properties": {
    "roleName": "",
    "description": "",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [

        ],
        "notActions": [

        ]
      }
    ],
    "assignableScopes": [
      "/subscriptions/{subscriptionId1}",
      "/subscriptions/{subscriptionId2}",
      "/subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}",
      "/subscriptions/{subscriptionId2}/resourceGroups/{resourceGroup2}",
      "/providers/Microsoft.Management/managementGroups/{groupId1}"
    ]
  }
}

요청 본문을 사용자 지정 역할에 적용하려는 변경 내용으로 업데이트합니다.

새 진단 설정 작업이 추가된 요청 본문의 예제는 다음과 같습니다.

{
  "name": "88888888-8888-8888-8888-888888888888",
  "properties": {
    "roleName": "Virtual Machine Operator",
    "description": "Can monitor and restart virtual machines.",
    "type": "CustomRole",
    "permissions": [
      {
        "actions": [
          "Microsoft.Storage/*/read",
          "Microsoft.Network/*/read",
          "Microsoft.Compute/*/read",
          "Microsoft.Compute/virtualMachines/start/action",
          "Microsoft.Compute/virtualMachines/restart/action",
          "Microsoft.Authorization/*/read",
          "Microsoft.ResourceHealth/availabilityStatuses/read",
          "Microsoft.Resources/subscriptions/resourceGroups/read",
          "Microsoft.Insights/alertRules/*",
          "Microsoft.Insights/diagnosticSettings/*",
          "Microsoft.Support/*"
        ],
        "notActions": []
      }
    ],
    "assignableScopes": [
      "/subscriptions/00000000-0000-0000-0000-000000000000",
      "/providers/Microsoft.Management/managementGroups/marketing-group"
    ]
  }
}

사용자 지정 역할 삭제

사용자 지정 역할을 삭제하려면 역할 정의 - 삭제 REST API를 사용합니다. 해당 API를 호출하려면 모든 assignableScopes에 대한 Microsoft.Authorization/roleDefinitions/delete권한이 있는 역할이 할당된 사용자로 로그인해야 합니다. 기본 제공 역할의 경우 Owner 및 User Access Administrator만 해당 권한을 가집니다.

사용자 지정 역할을 사용하는 역할 할당을 제거합니다. 자세한 내용은 사용자 지정 역할을 삭제할 역할 할당 찾기를 참조하세요.
역할 정의 - 나열 또는 역할 정의 - 가져오기 REST API를 사용하여 사용자 지정 역할의 GUID 식별자를 가져옵니다. 자세한 내용은 앞에서 설명한 모든 사용자 지정 역할 정의 나열 섹션을 참조하세요.

다음 요청으로 시작합니다.

DELETE https://management.azure.com/{scope}/providers/Microsoft.Authorization/roleDefinitions/{roleDefinitionId}?api-version=2022-04-01

URI 내에서 {scope}를 삭제하려는 사용자 지정 역할에 대한 범위로 바꿉니다.

범위	Type
`subscriptions/{subscriptionId1}`	구독
`subscriptions/{subscriptionId1}/resourceGroups/{resourceGroup1}`	Resource group
`providers/Microsoft.Management/managementGroups/{groupId1}`	관리 그룹

{roleDefinitionId}를 사용자 지정 역할의 GUID 식별자로 바꿉니다.

REST API를 사용하여 Azure 사용자 지정 역할을 만들거나 업데이트하기

필수 조건

모든 사용자 지정 역할 정의 나열

범위에서 모든 사용자 지정 역할 정의 나열

이름별로 사용자 지정 역할 정의 나열하기

ID 별로 사용자 지정 역할 정의 나열하기

사용자 지정 역할 만들기

사용자 지정 역할 업데이트

사용자 지정 역할 삭제

다음 단계

추가 리소스