Membuat prinsipal layanan Azure dengan Microsoft Azure PowerShell

  • Artikel

Alat otomatis yang menggunakan layanan Azure harus selalu memiliki izin terbatas. Selain masuk aplikasi sebagai pengguna yang memiliki hak istimewa, Azure menawarkan prinsipal layanan.

Perwakilan layanan Azure adalah identitas yang dibuat untuk digunakan dengan aplikasi, layanan yang dihosting, dan alat otomatis untuk mengakses sumber daya Azure. Akses ini dibatasi oleh peran yang ditetapkan untuk perwakilan layanan, yang memberi Anda kontrol atas sumber daya mana yang dapat diakses dan pada tingkat mana. Untuk alasan keamanan, selalu disarankan untuk menggunakan perwakilan layanan dengan alat otomatis dibanding mengizinkan mereka masuk dengan identitas pengguna.

Artikel ini berisi langkah-langkah untuk membuat, mendapatkan informasi tentang, dan mengatur ulang perwakilan layanan dengan Azure PowerShell.

Perhatian

Saat Anda membuat perwakilan layanan menggunakan perintah New-AzADServicePrincipal, output akan menyertakan info masuk yang harus dilindungi. Sebagai alternatif, pertimbangkan untuk menggunakan identitas terkelola untuk mencegah penggunaan info masuk.

Prasyarat

Membuat perwakilan layanan

Buat perwakilan layanan dengan cmdlet New-AzADServicePrincipal. Saat membuat perwakilan layanan, pilih jenis autentikasi masuk yang digunakannya.

Penting

Dimulai dengan modul Az PowerShell versi 7.x, New-AzADServicePrincipal tidak lagi menetapkan peran Kontributor ke perwakilan layanan secara default. Untuk menetapkan peran tertentu ke perwakilan layanan, lihat Langkah untuk menambahkan penetapan peran.

Catatan

Jika akun Anda tidak memiliki izin untuk membuat perwakilan layanan, New-AzADServicePrincipal mengembalikan pesan kesalahan yang berisi "Hak istimewa yang tidak memadai untuk menyelesaikan operasi". Hubungi admin Microsoft Entra Anda untuk membuat perwakilan layanan.

Dalam direktori ID Microsoft Entra tempat pengaturan pengguna Pengguna dapat mendaftarkan aplikasi telah diatur ke Tidak, Anda harus menjadi anggota salah satu peran bawaan ID Microsoft Entra berikut (yang memiliki tindakan: microsoft.directory/applications/createAsOwner atau microsoft.directory/applications/create):

Untuk informasi selengkapnya tentang pengaturan pengguna di ID Microsoft Entra, lihat Membatasi siapa yang dapat membuat aplikasi.

Ada dua jenis autentikasi yang tersedia untuk perwakilan layanan: Autentikasi berbasis kata sandi dan autentikasi berbasis sertifikat.

Autentikasi berbasis kata sandi

Penting

Peran default untuk perwakilan layanan autentikasi berbasis kata sandi adalah Kontributor. Peran ini memiliki izin penuh untuk membaca dan menulis ke akun Azure. Untuk informasi tentang mengelola penetapan peran, lihat Mengelola peran perwakilan layanan.

Tanpa parameter autentikasi lainnya, autentikasi berbasis kata sandi digunakan dan kata sandi acak dibuat untuk Anda. Jika Anda menginginkan autentikasi berbasis kata sandi, metode ini disarankan.

$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName

Objek yang ditampilkan berisi properti PasswordCredentials.SecretText yang berisi kata sandi yang dibuat. Pastikan Anda menyimpan nilai ini di suatu tempat yang aman untuk diautentikasi dengan perwakilan layanan. Nilainya tidak akan ditampilkan di output konsol. Jika lupa kata sandi, atur ulang info masuk perwakilan layanan.

Kode berikut memungkinkan Anda mengekspor rahasia:

$sp.PasswordCredentials.SecretText

Objek yang dikembalikan dari New-AzADServicePrincipal berisi Id dan DisplayName anggota, yang keduanya dapat digunakan untuk masuk dengan perwakilan layanan.

Penting

Masuk dengan perwakilan layanan memerlukan ID penyewa tempat perwakilan layanan dibuat. Untuk mendapatkan penyewa aktif saat perwakilan layanan dibuat, jalankan perintah berikut segera setelah pembuatan perwakilan layanan:

(Get-AzContext).Tenant.Id

Autentikasi berbasis sertifikat

Penting

Tidak ada peran default yang ditetapkan saat membuat perwakilan layanan autentikasi berbasis sertifikat. Untuk informasi tentang mengelola penetapan peran, lihat Mengelola peran perwakilan layanan.

Perwakilan layanan yang menggunakan autentikasi berbasis sertifikat dibuat dengan parameter CertValue. Parameter ini mengambil string ASCII yang dikodekan base64 dari sertifikat publik. Ini diwakili oleh file PEM, atau CRT atau CER yang dikodekan teks. Pengodean biner dari sertifikat publik tidak didukung. Instruksi ini mengasumsikan bahwa Anda sudah memiliki sertifikat yang tersedia.

$cert = <public certificate as base64-encoded string>
$sp = New-AzADServicePrincipal -DisplayName ServicePrincipalName -CertValue $cert

Objek yang dikembalikan dari New-AzADServicePrincipal berisi properti Id dan DisplayName, yang keduanya dapat digunakan untuk masuk dengan perwakilan layanan. Klien yang masuk dengan perwakilan layanan juga memerlukan akses ke kunci privat sertifikat.

Penting

Masuk dengan perwakilan layanan memerlukan ID penyewa tempat perwakilan layanan dibuat. Untuk mendapatkan penyewa aktif saat perwakilan layanan dibuat, jalankan perintah berikut segera setelah pembuatan perwakilan layanan:

(Get-AzContext).Tenant.Id

Mendapatkan perwakilan layanan yang ada

Daftar perwakilan layanan untuk penyewa aktif dapat diambil dengan Get-AzADServicePrincipal. Secara default perintah ini mengembalikan semua perwakilan layanan di penyewa. Untuk organisasi besar, mungkin perlu waktu lama untuk mengembalikan hasil. Sebagai gantinya, menggunakan salah satu argumen pemfilteran sisi server opsional disarankan:

  • DisplayNameBeginsWith meminta perwakilan layanan yang memiliki awalan yang sesuai dengan nama yang disediakan. Nama tampilan perwakilan layanan adalah nilai yang ditetapkan dengan parameter DisplayName selama pembuatan.
  • DisplayName meminta kecocokan yang tepat dari nama perwakilan layanan.

Kelola peran perwakilan layanan

Azure PowerShell memiliki cmdlet berikut untuk mengelola penetapan peran:

Untuk informasi selengkapnya tentang Kontrol Akses Berbasis Peran (RBAC) dan peran, lihat RBAC: Peran bawaan.

Contoh berikut menambahkan peran Pembaca dan menghapus peran Kontributor:

New-AzRoleAssignment -ApplicationId <service principal application ID> -RoleDefinitionName 'Reader'
Remove-AzRoleAssignment -ObjectId <service principal object ID> -RoleDefinitionName 'Contributor'

Penting

Cmdlet penetapan peran tidak mengambil ID objek perwakilan layanan. Cmdlet mengambil ID aplikasi terkait, yang dibuat pada waktu pembuatan. Untuk mendapatkan ID aplikasi untuk perwakilan layanan, gunakan Get-AzADServicePrincipal.

Catatan

Jika akun Anda tidak memiliki izin untuk menetapkan peran, Anda akan melihat pesan kesalahan bahwa akun Anda "tidak memiliki otorisasi untuk melakukan tindakan 'Microsoft.Authorization/roleAssignments/write'". Hubungi admin Microsoft Entra Anda untuk mengelola peran.

Penambahan peran tidak membatasi izin yang ditetapkan sebelumnya. Jika izin perwakilan layanan dibatasi, peran Kontributor akan dihapus.

Perubahan ini dapat diverifikasi dengan mencantumkan peran yang ditetapkan:

Get-AzRoleAssignment -ServicePrincipalName ServicePrincipalName

Masuk menggunakan perwakilan layanan

Uji info masuk dan izin perwakilan layanan baru dengan masuk. Untuk masuk dengan perwakilan layanan, Anda memerlukan nilai yang applicationId terkait dengannya, dan penyewa tempatnya dibuat.

Untuk masuk dengan perwakilan layanan menggunakan kata sandi:

# Use the application ID as the username, and the secret as password
$credentials = Get-Credential
Connect-AzAccount -ServicePrincipal -Credential $credentials -Tenant <tenant ID>

Autentikasi berbasis sertifikat mengharuskan Azure PowerShell dapat mengambil informasi dari penyimpanan sertifikat lokal berdasarkan thumbprint sertifikat.

Connect-AzAccount -ServicePrincipal -Tenant <TenantId> -CertificateThumbprint <Thumbprint> -ApplicationId <ApplicationId>

Untuk instruksi tentang mengimpor sertifikat ke penyimpanan kredensial yang dapat diakses oleh PowerShell, lihat Autentikasi berbasis sertifikat

Mengatur ulang info masuk

Jika Anda lupa info masuk untuk perwakilan layanan, gunakan New-AzADSpCredential untuk menambahkan info masuk baru dengan kata sandi acak. Cmdlet ini tidak mendukung kredensial yang ditentukan pengguna saat mengatur ulang kata sandi.

Penting

Sebelum menetapkan info masuk baru, Anda mungkin ingin menghapus info masuk yang ada untuk mencegah masuk dengannya. Untuk melakukannya, gunakan cmdlet Remove-AzADSpCredential:

Remove-AzADSpCredential -DisplayName ServicePrincipalName

$newCredential = New-AzADSpCredential -ServicePrincipalName ServicePrincipalName

Pemecahan Masalah

Jika Anda menerima kesalahan: "New-AzADServicePrincipal: Objek lain dengan nilai yang sama untuk properti identifierUris sudah ada.", verifikasikan apakah perwakilan layanan dengan nama yang sama belum ada.

Get-AzAdServicePrincipal -DisplayName ServicePrincipalName

Jika perwakilan layanan yang ada tidak lagi diperlukan, Anda dapat menghapusnya menggunakan contoh berikut.

Remove-AzAdServicePrincipal -DisplayName ServicePrincipalName

Kesalahan ini juga dapat terjadi saat Anda sebelumnya telah membuat perwakilan layanan untuk aplikasi Azure Active Directory. Jika Anda menghapus perwakilan layanan, aplikasi masih tersedia. Aplikasi ini mencegah Anda membuat perwakilan layanan lain dengan nama yang sama.

Anda dapat menggunakan contoh berikut untuk memverifikasi bahwa aplikasi Microsoft Entra dengan nama yang sama tidak ada:

Get-AzADApplication -DisplayName ServicePrincipalName

Jika aplikasi dengan nama yang sama memang ada dan tidak diperlukan lagi, aplikasi tersebut dapat dihapus menggunakan contoh berikut.

Remove-AzADApplication -DisplayName ServicePrincipalName

Jika tidak, pilih nama alternatif untuk perwakilan layanan baru yang ingin dibuat.