Menetapkan peran Azure menggunakan templat Azure Resource Manager

  • Artikel

Kontrol akses berbasis peran Azure (Azure RBAC) adalah sistem otorisasi yang Anda gunakan untuk mengelola akses ke sumber daya Azure. Untuk memberikan akses, Anda menetapkan peran kepada pengguna, grup, perwakilan layanan, atau identitas terkelola pada cakupan tertentu. Selain menggunakan Azure PowerShell atau Azure CLI, Anda dapat menetapkan peran menggunakan templat Azure Resource Manager. Templat dapat membantu jika Anda ingin menerapkan sumber daya secara konsisten dan berulang kali. Artikel ini menjelaskan cara menetapkan peran menggunakan templat.

Catatan

Bicep adalah bahasa baru untuk menentukan sumber daya Azure Anda. Ini memiliki pengalaman penulisan yang lebih sederhana daripada JSON, bersama dengan fitur lain yang membantu meningkatkan kualitas infrastruktur Anda sebagai kode. Kami menyarankan agar siapa pun yang baru menggunakan infrastruktur sebagai kode di Azure menggunakan Bicep, bukan JSON.

Untuk mempelajari tentang cara menentukan penetapan peran dengan menggunakan Bicep, lihat Membuat sumber daya Azure RBAC dengan menggunakan Bicep. Untuk contoh mulai cepat, lihat Mulai Cepat: Menetapkan peran Azure menggunakan Bicep.

Prasyarat

Untuk menetapkan peran Azure, Anda harus memiliki:

Anda harus menggunakan versi berikut:

  • 2018-09-01-preview atau yang lebih baru untuk menetapkan peran Azure ke perwakilan layanan baru
  • 2020-04-01-preview atau yang lebih baru untuk menetapkan peran Azure di cakupan sumber daya
  • 2022-04-01 adalah versi stabil pertama

Untuk informasi selengkapnya, lihat API versi REST API Azure RBAC.

Dapatkan ID objek

Untuk menetapkan peran, Anda perlu menentukan ID pengguna, grup, atau aplikasi mana yang ingin Anda tetapkan perannya. ID memiliki format: 11111111-1111-1111-1111-111111111111. Anda bisa mendapatkan ID menggunakan portal Microsoft Azure, Azure PowerShell, atau Azure CLI.

User

Untuk mendapatkan ID pengguna, Anda dapat menggunakan perintah Get-AzADUser atau tampilkan pengguna az ad.

$objectid = (Get-AzADUser -DisplayName "{name}").id

objectid=$(az ad user show --id "{email}" --query id --output tsv)

Grupkan

Untuk mendapatkan ID grup, Anda dapat menggunakan perintah Get-AzADGroup atau tampilkan grup az ad.

$objectid = (Get-AzADGroup -DisplayName "{name}").id

objectid=$(az ad group show --group "{name}" --query id --output tsv)

Identitas Terkelola

Untuk mendapatkan ID identitas terkelola, Anda dapat menggunakan perintah Get-AzAdServiceprincipal atau az ad sp.

$objectid = (Get-AzADServicePrincipal -DisplayName <Azure resource name>).id

objectid=$(az ad sp list --display-name <Azure resource name> --query [].id --output tsv)

Aplikasi

Untuk mendapatkan ID perwakilan layanan (identitas yang digunakan oleh aplikasi), Anda dapat menggunakan perintah Get-AzADServicePrincipal atau daftar az ad sp. Untuk perwakilan layanan, gunakan ID objek dan bukan ID aplikasi.

$objectid = (Get-AzADServicePrincipal -DisplayName "{name}").id

objectid=$(az ad sp list --display-name "{name}" --query [].id --output tsv)

Menetapkan peran Azure

Di Azure RBAC, untuk memberikan akses, Anda harus menetapkan peran.

Lingkup grup sumber daya (tanpa parameter)

Templat berikut ini memperlihatkan cara dasar untuk menetapkan peran. Beberapa nilai sudah ditentukan dalam templat. Templat berikut ini menunjukkan:

  • Cara menetapkan peran Pembaca ke pengguna, grup, atau aplikasi di lingkup grup sumber daya

Untuk menggunakan templat, Anda harus melakukan hal berikut:

  • Buat file JSON baru dan salin templatnya
  • Ganti <your-principal-id> dengan ID pengguna, grup, identitas terkelola, atau aplikasi untuk menetapkan peran
{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "resources": [
        {
            "type": "Microsoft.Authorization/roleAssignments",
            "apiVersion": "2022-04-01",
            "name": "[guid(resourceGroup().id)]",
            "properties": {
                "roleDefinitionId": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')]",
                "principalId": "<your-principal-id>"
            }
        }
    ]
}

Berikut adalah contoh perintah New-AzResourceGroupDeployment dan membuat grup penerapan az tentang cara memulai penerapan dalam grup sumber daya bernama ExampleGroup.

New-AzResourceGroupDeployment -ResourceGroupName ExampleGroup -TemplateFile rbac-test.json

az deployment group create --resource-group ExampleGroup --template-file rbac-test.json

Berikut ini memperlihatkan contoh penetapan peran Pembaca kepada pengguna untuk grup sumber daya setelah menerapkan templat.

Role assignment at resource group scope

Cakupan grup sumber daya atau langganan

Templat sebelumnya tidak terlalu fleksibel. Templat berikut menggunakan parameter dan dapat digunakan pada cakupan yang berbeda. Templat berikut ini menunjukkan:

  • Cara menetapkan peran untuk pengguna, grup, atau aplikasi di lingkup grup sumber daya atau langganan
  • Cara menentukan peran Pemilik, Kontributor, dan Pembaca sebagai parameter

Untuk menggunakan templat, Anda harus menentukan input berikut:

  • ID pengguna, grup, identitas terkelola, atau aplikasi untuk menetapkan peran
  • ID unik yang akan digunakan untuk penetapan peran, atau Anda dapat menggunakan ID default
{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "principalId": {
            "type": "string",
            "metadata": {
                "description": "The principal to assign the role to"
            }
        },
        "builtInRoleType": {
            "type": "string",
            "allowedValues": [
                "Owner",
                "Contributor",
                "Reader"
            ],
            "metadata": {
                "description": "Built-in role to assign"
            }
        },
        "roleNameGuid": {
            "type": "string",
            "defaultValue": "[newGuid()]",
            "metadata": {
                "description": "A new GUID used to identify the role assignment"
            }
        }
    },
    "variables": {
        "Owner": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')]",
        "Contributor": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]",
        "Reader": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')]"
    },
    "resources": [
        {
            "type": "Microsoft.Authorization/roleAssignments",
            "apiVersion": "2022-04-01",
            "name": "[parameters('roleNameGuid')]",
            "properties": {
                "roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
                "principalId": "[parameters('principalId')]"
            }
        }
    ]
}

Catatan

Templat ini tidak demoten kecuali nilai roleNameGuid yang sama disediakan sebagai parameter untuk setiap penerapan templat. Jika roleNameGuid tidak disediakan, secara default GUID baru dihasilkan pada setiap penerapan dan penerapan berikutnya akan gagal dengan kesalahan Conflict: RoleAssignmentExists.

Lingkup penetapan peran ditentukan dari tingkat penerapan. Berikut adalah contoh perintah New-AzResourceGroupDeployment dan membuat grup penerapan az tentang cara memulai penerapan dalam grup sumber daya.

New-AzResourceGroupDeployment -ResourceGroupName ExampleGroup -TemplateFile rbac-test.json -principalId $objectid -builtInRoleType Reader

az deployment group create --resource-group ExampleGroup --template-file rbac-test.json --parameters principalId=$objectid builtInRoleType=Reader

Berikut adalah contoh perintah New-AzDeployment dan sub pembuatan penerapan az tentang cara memulai penerapan di lingkup langganan dan menentukan lokasi.

New-AzDeployment -Location centralus -TemplateFile rbac-test.json -principalId $objectid -builtInRoleType Reader

az deployment sub create --location centralus --template-file rbac-test.json --parameters principalId=$objectid builtInRoleType=Reader

Cakupan sumber daya

Jika Anda perlu menetapkan peran di tingkat sumber daya, atur properti scope pada penetapan peran menjadi nama sumber daya.

Templat berikut ini menunjukkan:

  • Cara membuat akun penyimpanan baru
  • Cara menetapkan peran untuk pengguna, grup, atau aplikasi di lingkup akun penyimpanan
  • Cara menentukan peran Pemilik, Kontributor, dan Pembaca sebagai parameter

Untuk menggunakan templat, Anda harus menentukan input berikut:

  • ID pengguna, grup, identitas terkelola, atau aplikasi untuk menetapkan peran
{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "principalId": {
            "type": "string",
            "metadata": {
                "description": "The principal to assign the role to"
            }
        },
        "builtInRoleType": {
            "type": "string",
            "allowedValues": [
                "Owner",
                "Contributor",
                "Reader"
            ],
            "metadata": {
                "description": "Built-in role to assign"
            }
        },
        "roleNameGuid": {
            "type": "string",
            "defaultValue": "[newGuid()]",
            "metadata": {
                "description": "A new GUID used to identify the role assignment"
            }
        },
        "location": {
            "type": "string",
            "defaultValue": "[resourceGroup().location]"
        }
    },
    "variables": {
        "Owner": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', '8e3af657-a8ff-443c-a75c-2fe8c4bcb635')]",
        "Contributor": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]",
        "Reader": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'acdd72a7-3385-48ef-bd42-f606fba81ae7')]",
        "storageName": "[concat('storage', uniqueString(resourceGroup().id))]"
    },
    "resources": [
        {
            "apiVersion": "2019-04-01",
            "type": "Microsoft.Storage/storageAccounts",
            "name": "[variables('storageName')]",
            "location": "[parameters('location')]",
            "sku": {
                "name": "Standard_LRS"
            },
            "kind": "Storage",
            "properties": {}
        },
        {
            "type": "Microsoft.Authorization/roleAssignments",
            "apiVersion": "2022-04-01",
            "name": "[parameters('roleNameGuid')]",
            "scope": "[concat('Microsoft.Storage/storageAccounts', '/', variables('storageName'))]",
            "dependsOn": [
                "[variables('storageName')]"
            ],
            "properties": {
                "roleDefinitionId": "[variables(parameters('builtInRoleType'))]",
                "principalId": "[parameters('principalId')]"
            }
        }
    ]
}

Untuk menggunakan templat sebelumnya, Anda harus menggunakan perintah grup sumber daya. Berikut adalah contoh perintah New-AzResourceGroupDeployment dan membuat grup penerapan az tentang cara memulai penerapan dalam grup sumber daya.

New-AzResourceGroupDeployment -ResourceGroupName ExampleGroup -TemplateFile rbac-test.json -principalId $objectid -builtInRoleType Contributor

az deployment group create --resource-group ExampleGroup --template-file rbac-test.json --parameters principalId=$objectid builtInRoleType=Contributor

Contoh berikut ini memperlihatkan tentang penetapan peran Kontributor untuk akun penyimpanan setelah menerapkan templat.

Role assignment at resource scope

Perwakilan layanan baru

Jika Anda membuat perwakilan layanan baru dan ingin segera mencoba menetapkan peran untuk perwakilan layanan tersebut, penetapan peran tersebut dapat gagal pada beberapa kasus. Misalnya, jika Anda membuat identitas terkelola baru lalu mencoba menetapkan peran ke perwakilan layanan tersebut dalam templat Azure Resource Manager yang sama, penetapan peran mungkin gagal. Penyebab kegagalan ini kemungkinan adalah penundaan replikasi. Perwakilan layanan dibuat di satu wilayah; namun, penetapan peran mungkin dilakukan di wilayah lain yang belum mereplikasi perwakilan layanan.

Untuk mengatasi skenario ini, Anda harus mengatur properti principalType ke ServicePrincipal saat membuat penetapan peran. Anda juga harus mengatur apiVersion dari penetapan peran ke 2018-09-01-preview atau setelahnya. 2022-04-01 adalah versi stabil pertama.

Templat berikut ini menunjukkan:

  • Cara membuat perwakilan layanan identitas terkelola baru
  • Cara menentukan principalType
  • Cara menetapkan peran Kontributor ke perwakilan layanan tersebut di lingkup grup sumber daya

Untuk menggunakan templat, Anda harus menentukan input berikut:

  • Nama dasar identitas terkelola, atau Anda bisa menggunakan string default
{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "baseName": {
            "type": "string",
            "defaultValue": "msi-test"
        }
    },
    "variables": {
        "identityName": "[concat(parameters('baseName'), '-bootstrap')]",
        "bootstrapRoleAssignmentId": "[guid(concat(resourceGroup().id, 'contributor'))]",
        "contributorRoleDefinitionId": "[concat('/subscriptions/', subscription().subscriptionId, '/providers/Microsoft.Authorization/roleDefinitions/', 'b24988ac-6180-42a0-ab88-20f7382dd24c')]"
    },
    "resources": [
        {
            "type": "Microsoft.ManagedIdentity/userAssignedIdentities",
            "name": "[variables('identityName')]",
            "apiVersion": "2018-11-30",
            "location": "[resourceGroup().location]"
        },
        {
            "type": "Microsoft.Authorization/roleAssignments",
            "apiVersion": "2022-04-01",
            "name": "[variables('bootstrapRoleAssignmentId')]",
            "dependsOn": [
                "[resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName'))]"
            ],
            "properties": {
                "roleDefinitionId": "[variables('contributorRoleDefinitionId')]",
                "principalId": "[reference(resourceId('Microsoft.ManagedIdentity/userAssignedIdentities', variables('identityName')), '2018-11-30').principalId]",
                "principalType": "ServicePrincipal"
            }
        }
    ]
}

Berikut adalah contoh perintah New-AzResourceGroupDeployment dan membuat grup penerapan az tentang cara memulai penerapan dalam grup sumber daya.

New-AzResourceGroupDeployment -ResourceGroupName ExampleGroup2 -TemplateFile rbac-test.json

az deployment group create --resource-group ExampleGroup2 --template-file rbac-test.json

Contoh berikut ini memperlihatkan tentang penetapan peran Kontributor ke perwakilan layanan identitas terkelola baru setelah menerapkan templat.

Role assignment for a new managed identity service principal

Langkah berikutnya