Menggunakan Azure PowerShell untuk membuat perwakilan layanan dengan sertifikat

  • Artikel

Saat memiliki aplikasi atau skrip yang perlu mengakses sumber daya, Anda dapat menyiapkan identitas untuk aplikasi dan mengautentikasi aplikasi dengan kredensialnya sendiri. Identitas ini dikenal sebagai perwakilan layanan. Pendekatan ini memungkinkan Anda:

  • Menetapkan izin ke identitas aplikasi yang berbeda dari izin Anda sendiri. Biasanya, izin ini dibatasi untuk apa tepatnya yang perlu dilakukan aplikasi.
  • Menggunakan sertifikat untuk autentikasi ketika menjalankan skrip tanpa pengawasan.

Penting

Alih-alih membuat perwakilan layanan, pertimbangkan untuk menggunakan identitas terkelola untuk sumber daya Azure untuk identitas aplikasi Anda. Jika kode Anda berjalan pada layanan yang mendukung identitas terkelola dan mengakses sumber daya yang mendukung autentikasi Microsoft Entra, identitas terkelola adalah opsi yang lebih baik untuk Anda. Untuk mempelajari selengkapnya tentang identitas terkelola untuk sumber daya Azure, termasuk layanan mana yang saat ini mendukungnya, lihat Apa itu identitas terkelola untuk sumber daya Azure?.

Artikel ini memperlihatkan cara membuat perwakilan layanan yang mengautentikasi dengan sertifikat. Untuk menyiapkan perwakilan layanan dengan kata sandi, lihat Membuat perwakilan layanan Azure dengan Microsoft Azure PowerShell.

Anda harus memiliki PowerShell versi terbaru untuk artikel ini.

Catatan

Sebaiknya Anda menggunakan modul Azure Az PowerShell untuk berinteraksi dengan Azure. Lihat Menginstal Azure PowerShell untuk memulai. Untuk mempelajari cara bermigrasi ke modul Az PowerShell, lihat Memigrasikan Azure PowerShell dari AzureRM ke Az.

Memerlukan izin

Untuk menyelesaikan artikel ini, Anda harus memiliki izin yang memadai di ID Microsoft Entra dan langganan Azure Anda. Secara khusus, Anda harus dapat membuat aplikasi di ID Microsoft Entra, dan menetapkan perwakilan layanan ke peran.

Cara termudah untuk memeriksa apakah akun Anda memiliki izin yang memadai adalah melalui portal. Lihat Memeriksa izin yang diperlukan.

Menetapkan aplikasi ke peran

Untuk mengakses sumber daya di langganan Anda, Anda harus menetapkan aplikasi ke peran. Tentukan peran mana yang menawarkan izin yang tepat untuk aplikasi. Untuk mempelajari tentang peran yang tersedia, lihat Peran bawaan Azure.

Anda dapat menetapkan cakupan di tingkat langganan, grup sumber daya, atau sumber daya. Izin diturunkan ke tingkat cakupan yang lebih rendah. Misalnya, menambahkan aplikasi ke peran Pembaca untuk grup sumber daya berarti dapat membaca grup sumber daya dan sumber daya apa pun di dalamnya. Untuk mengizinkan aplikasi menjalankan tindakan seperti instans boot ulang, mulai, dan hentikan, pilih peran Kontributor.

Membuat perwakilan layanan dengan sertifikat yang ditandatangani sendiri

Contoh berikut mencakup skenario sederhana. Hal ini menggunakan New-​AzAD​Service​Principal untuk membuat perwakilan layanan dengan sertifikat yang ditandatangani sendiri, dan menggunakan New-AzRoleAssignment untuk menetapkan peran Pembaca kepada perwakilan pelayanan. Penetapan peran dicakup ke langganan Azure yang Anda pilih saat ini. Untuk memilih langganan lain, gunakan Set-AzContext.

Catatan

Cmdlet New-SelfSignedCertificate dan modul PKI saat ini tidak didukung di PowerShell Core.

$cert = New-SelfSignedCertificate -CertStoreLocation "cert:\CurrentUser\My" `
  -Subject "CN=exampleappScriptCert" `
  -KeySpec KeyExchange
$keyValue = [System.Convert]::ToBase64String($cert.GetRawCertData())

$sp = New-AzADServicePrincipal -DisplayName exampleapp `
  -CertValue $keyValue `
  -EndDate $cert.NotAfter `
  -StartDate $cert.NotBefore
Sleep 20
New-AzRoleAssignment -RoleDefinitionName Reader -ServicePrincipalName $sp.AppId

Contoh tidur selama 20 detik untuk memungkinkan beberapa waktu bagi perwakilan layanan baru untuk menyebar ke seluruh ID Microsoft Entra. Jika skrip Anda tidak menunggu cukup lama, Anda akan melihat kesalahan yang menyatakan: "Utama {ID} tidak ada di direktori {DIR-ID}." Untuk mengatasi kesalahan ini, tunggu sebentar lalu jalankan perintah New-AzRoleAssignment lagi.

Anda dapat menjangkau penetapan peran ke grup sumber daya tertentu menggunakan parameter ResourceGroupName. Anda dapat menjangkau ke sumber daya tertentu juga dengan menggunakan parameter ResourceType dan ResourceName.

Jika Anda tidak memiliki Windows 10 atau Windows Server 2016, unduh cmdlet New-SelfSignedCertificateEx dari Solusi PKI. Ekstrak isinya dan impor cmdlet yang Anda butuhkan.

# Only run if you could not use New-SelfSignedCertificate
Import-Module -Name c:\ExtractedModule\New-SelfSignedCertificateEx.ps1

Dalam skrip, ganti dua baris berikut untuk membuat sertifikat.

New-SelfSignedCertificateEx -StoreLocation CurrentUser `
  -Subject "CN=exampleapp" `
  -KeySpec "Exchange" `
  -FriendlyName "exampleapp"
$cert = Get-ChildItem -path Cert:\CurrentUser\my | where {$PSitem.Subject -eq 'CN=exampleapp' }

Menyediakan sertifikat melalui skrip PowerShell otomatis

Tiap kali Anda masuk sebagai perwakilan layanan, berikan ID penyewa direktori untuk aplikasi AD Anda. Penyewa adalah instans ID Microsoft Entra.

$TenantId = (Get-AzSubscription -SubscriptionName "Contoso Default").TenantId
$ApplicationId = (Get-AzADApplication -DisplayNameStartWith exampleapp).AppId

$Thumbprint = (Get-ChildItem cert:\CurrentUser\My\ | Where-Object {$_.Subject -eq "CN=exampleappScriptCert" }).Thumbprint
Connect-AzAccount -ServicePrincipal `
  -CertificateThumbprint $Thumbprint `
  -ApplicationId $ApplicationId `
  -TenantId $TenantId

Membuat perwakilan layanan dengan sertifikat dari Otoritas Sertifikat

Contoh berikut menggunakan sertifikat yang dikeluarkan dari Otoritas Sertifikat untuk membuat perwakilan layanan. Penugasan dicakup ke langganan Azure yang ditentukan. Ini menambahkan perwakilan layanan ke peran Pembaca. Jika terjadi kesalahan selama penetapan peran, ini akan mencoba kembali tugas tersebut.

Param (
 [Parameter(Mandatory=$true)]
 [String] $ApplicationDisplayName,

 [Parameter(Mandatory=$true)]
 [String] $SubscriptionId,

 [Parameter(Mandatory=$true)]
 [String] $CertPath,

 [Parameter(Mandatory=$true)]
 [String] $CertPlainPassword
 )

 Connect-AzAccount
 Import-Module Az.Resources
 Set-AzContext -Subscription $SubscriptionId

 $CertPassword = ConvertTo-SecureString $CertPlainPassword -AsPlainText -Force

 $PFXCert = New-Object -TypeName System.Security.Cryptography.X509Certificates.X509Certificate2 -ArgumentList @($CertPath, $CertPassword)
 $KeyValue = [System.Convert]::ToBase64String($PFXCert.GetRawCertData())

 $ServicePrincipal = New-AzADServicePrincipal -DisplayName $ApplicationDisplayName
 New-AzADSpCredential -ObjectId $ServicePrincipal.Id -CertValue $KeyValue -StartDate $PFXCert.NotBefore -EndDate $PFXCert.NotAfter
 Get-AzADServicePrincipal -ObjectId $ServicePrincipal.Id 

 $NewRole = $null
 $Retries = 0;
 While ($NewRole -eq $null -and $Retries -le 6)
 {
    # Sleep here for a few seconds to allow the service principal application to become active (should only take a couple of seconds normally)
    Sleep 15
    New-AzRoleAssignment -RoleDefinitionName Reader -ServicePrincipalName $ServicePrincipal.AppId | Write-Verbose -ErrorAction SilentlyContinue
    $NewRole = Get-AzRoleAssignment -ObjectId $ServicePrincipal.Id -ErrorAction SilentlyContinue
    $Retries++;
 }

 $NewRole

Menyediakan sertifikat melalui skrip PowerShell otomatis

Tiap kali Anda masuk sebagai perwakilan layanan, berikan ID penyewa direktori untuk aplikasi AD Anda. Penyewa adalah instans ID Microsoft Entra.

Param (

 [Parameter(Mandatory=$true)]
 [String] $CertPath,

 [Parameter(Mandatory=$true)]
 [String] $CertPlainPassword,

 [Parameter(Mandatory=$true)]
 [String] $ApplicationId,

 [Parameter(Mandatory=$true)]
 [String] $TenantId
 )

 $CertPassword = ConvertTo-SecureString $CertPlainPassword -AsPlainText -Force
 $PFXCert = New-Object `
  -TypeName System.Security.Cryptography.X509Certificates.X509Certificate2 `
  -ArgumentList @($CertPath, $CertPassword)
 $Thumbprint = $PFXCert.Thumbprint

 Connect-AzAccount -ServicePrincipal `
  -CertificateThumbprint $Thumbprint `
  -ApplicationId $ApplicationId `
  -TenantId $TenantId

ID aplikasi dan ID penyewa tidak sensitif, sehingga Anda dapat menyematkannya langsung di skrip Anda. Jika Anda perlu mengambil ID penyewa, gunakan:

(Get-AzSubscription -SubscriptionName "Contoso Default").TenantId

Jika Anda perlu mengambil ID aplikasi, gunakan:

(Get-AzADApplication -DisplayNameStartWith {display-name}).AppId

Mengubah kredensial

Untuk mengubah kredensial aplikasi AD, baik karena kompromi keamanan maupun masa berakhir kredensial, gunakan cmdlet Remove-AzADAppCredential dan New-AzADAppCredential.

Untuk menghapus semua kredensial aplikasi, gunakan:

Get-AzADApplication -DisplayName exampleapp | Remove-AzADAppCredential

Untuk menambahkan nilai sertifikat, buat sertifikat yang ditandatangani sendiri seperti yang diperlihatkan dalam artikel ini. Selanjutnya, gunakan:

Get-AzADApplication -DisplayName exampleapp | New-AzADAppCredential `
  -CertValue $keyValue `
  -EndDate $cert.NotAfter `
  -StartDate $cert.NotBefore

Debug

Anda mungkin mendapatkan kesalahan berikut saat membuat perwakilan layanan:

  • "Authentication_Unauthorized" atau "Tidak ada langganan yang ditemukan dalam konteks." - Anda melihat kesalahan ini saat akun Anda tidak memiliki izin yang diperlukan pada ID Microsoft Entra untuk mendaftarkan aplikasi. Biasanya, Anda melihat kesalahan ini saat hanya pengguna admin di ID Microsoft Entra yang dapat mendaftarkan aplikasi, dan akun Anda bukan admin. Minta administrator Anda untuk menetapkan Anda ke peran administrator, atau untuk memungkinkan pengguna mendaftarkan aplikasi.

  • Akun Anda "tidak memiliki otorisasi untuk melakukan tindakan 'Microsoft.Authorization/roleAssignments/write' melalui cakupan '/subscriptions/{guid}'." - Anda melihat kesalahan ini ketika akun Anda tidak memiliki izin yang memadai untuk menetapkan peran ke identitas. Minta administrator langganan Anda untuk menambahkan Anda ke peran Administrator Akses Pengguna.

Langkah berikutnya