Bagikan melalui

Membuat prinsipal layanan Azure dengan Azure PowerShell

Alat otomatis yang menggunakan layanan Azure harus selalu memiliki izin terbatas. Daripada membiarkan aplikasi masuk sebagai pengguna dengan hak penuh, Azure menawarkan prinsipal layanan.

Prinsipal layanan Azure adalah identitas yang dibuat untuk digunakan oleh aplikasi, layanan terhosting, dan alat otomatisasi 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 memperlihatkan kepada Anda langkah-langkah untuk membuat, mendapatkan informasi tentang, dan mengatur ulang perwakilan layanan dengan Azure PowerShell.

Perhatian

Saat Anda membuat prinsipal layanan menggunakan perintah New-AzADServicePrincipal, output akan menyertakan kredensial yang harus dilindungi. Sebagai alternatif, pertimbangkan untuk menggunakan identitas terkelola untuk menghindari kebutuhan menggunakan kredensial.

Prasyarat

Membuat "Service Principal"

Buat prinsipal layanan dengan cmdlet New-AzADServicePrincipal. Saat membuat prinsipal layanan, Anda memilih jenis autentikasi masuk yang akan digunakan.

Penting

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

Nota

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 prinsipal layanan.

Dalam direktori ID Microsoft Entra di mana pengaturan 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 bawaan untuk entitas 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 prinsipal 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 dikembalikan berisi properti PasswordCredentials.SecretText yang berisi kata sandi yang dihasilkan. Pastikan Anda menyimpan nilai ini di tempat yang aman untuk diautentikasi dengan perwakilan layanan. Nilainya tidak akan ditampilkan dalam output konsol. Jika lupa sandi, atur ulang kredensial prinsipal layanan.

Kode berikut memungkinkan Anda mengekspor rahasia:

$sp.PasswordCredentials.SecretText

Objek yang dikembalikan dari New-AzADServicePrincipal berisi anggota Id dan DisplayName, di mana salah satunya dapat digunakan untuk autentikasi oleh perwakilan layanan.

Penting

Masuk dengan prinsipal layanan memerlukan ID penyewa di mana prinsipal layanan tersebut dibuat. Untuk mendapatkan tenant aktif saat prinsipal layanan dibuat, jalankan perintah berikut segera setelah pembuatan prinsipal layanan:

(Get-AzContext).Tenant.Id

Otentikasi berbasis sertifikat

Penting

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

Prinsipal 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 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 salah satunya dapat digunakan untuk masuk dengan perwakilan layanan. Klien yang masuk dengan perwakilan layanan juga memerlukan akses ke kunci privat sertifikat.

Penting

Masuk dengan prinsipal layanan memerlukan ID penyewa di mana prinsipal layanan tersebut dibuat. Untuk mendapatkan tenant aktif saat prinsipal layanan dibuat, jalankan perintah berikut segera setelah pembuatan prinsipal layanan:

(Get-AzContext).Tenant.Id

Mendapatkan prinsipal layanan yang ada

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

  • DisplayNameBeginsWith meminta perwakilan layanan yang memiliki awalan dan yang cocok dengan nilai yang disediakan. Nama tampilan perwakilan layanan adalah nilai yang ditetapkan menggunakan DisplayName selama pembuatan.
  • DisplayName meminta kesesuaian persis dari nama prinsipal layanan.

Kelola peran entitas 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 untuk penetapan peran tidak menerima ID objek principal layanan. Mereka mengambil ID aplikasi terkait, yang dihasilkan pada saat pembuatan. Untuk mendapatkan ID aplikasi untuk perwakilan layanan, gunakan Get-AzADServicePrincipal.

Nota

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'". Untuk mengelola peran, hubungi admin Microsoft Entra Anda.

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

Perubahan dapat diverifikasi dengan mencantumkan peran yang ditetapkan:

Get-AzRoleAssignment -ServicePrincipalName ServicePrincipalName

Masuk menggunakan perwakilan layanan

Uji kredensial dan izin prinsipal layanan baru dengan masuk ke dalam akun. Untuk masuk dengan prinsipal layanan, Anda memerlukan nilai applicationId yang terkait dengannya, dan penyewa di mana itu dibuat.

Untuk login dengan prinsipal 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 sidik jari 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

Setel ulang kredensial

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

Penting

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

Remove-AzADSpCredential -DisplayName ServicePrincipalName

$newCredential = New-AzADSpCredential -ServicePrincipalName ServicePrincipalName

Penyelesaian Masalah

Jika Anda menerima kesalahan: "New-AzADServicePrincipal: Objek lain dengan nilai yang sama untuk properti identifierUris sudah ada.", pastikan bahwa prinsipal layanan dengan nama yang sama tidak sudah 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 ketika sebelumnya Anda sudah membuat principal layanan untuk aplikasi Azure Active Directory. Jika Anda menghapus service principal, aplikasi tetap 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 lagi diperlukan, aplikasi dapat dihapus menggunakan contoh berikut.

Remove-AzADApplication -DisplayName ServicePrincipalName

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