Autentikasi Azure Container Registry dengan prinsipal layanan

  • Artikel

Anda dapat menggunakan perwakilan layanan Microsoft Entra untuk memberikan pendorongan, penarikan, atau akses lain ke registri kontainer Anda. Dengan menggunakan perwakilan layanan, Anda dapat menyediakan akses ke layanan dan aplikasi "headless".

Apa itu perwakilan layanan?

Perwakilan layanan ID Microsoft Entra menyediakan akses ke sumber daya Azure dalam langganan Anda. Anda dapat menganggap perwakilan layanan sebagai identitas pengguna untuk layanan, di mana "layanan" adalah aplikasi, layanan, atau platform apa pun yang perlu mengakses sumber daya. Anda dapat mengonfigurasi perwakilan layanan dengan hak akses yang hanya tercakup dalam sumber daya yang Anda tentukan. Kemudian, konfigurasikan aplikasi atau layanan Anda untuk menggunakan info masuk perwakilan layanan untuk mengakses sumber daya tersebut.

Dalam konteks Azure Container Registry, Anda dapat membuat perwakilan layanan Microsoft Entra dengan penarikan, pendorongan, dan penarikan, atau izin lain ke registri privat Anda di Azure. Untuk daftar lengkap, lihat peran dan izin Azure Container Registry.

Mengapa menggunakan perwakilan layanan?

Dengan menggunakan perwakilan layanan Microsoft Entra, Anda dapat menyediakan akses tercakup ke registri kontainer privat Anda. Buat perwakilan layanan yang berbeda untuk setiap aplikasi atau layanan Anda, masing-masing dengan hak akses yang disesuaikan untuk registri Anda. Dan, karena Anda dapat menghindari berbagi info masuk antara layanan dan aplikasi, Anda dapat memutar info masuk atau mencabut akses hanya untuk perwakilan layanan (dan dengan demikian aplikasi) yang Anda pilih.

Misalnya, konfigurasikan aplikasi web Anda untuk menggunakan perwakilan layanan yang hanya menyediakan akses pull citra, sementara sistem build Anda menggunakan perwakilan layanan yang menyediakan akses push dan pull. Jika pengembangan aplikasi Anda berpindah tangan, Anda dapat memutar info masuk perwakilan layanan tanpa memengaruhi sistem build.

Kapan menggunakan prinsipal layanan

Anda harus menggunakan perwakilan layanan untuk menyediakan akses registri dalam skenario headless. Yaitu, aplikasi, layanan, atau skrip yang harus mendorong atau menarik citra kontainer secara otomatis atau tanpa pengawasan. Contohnya:

  • Penarikan: Sebarkan kontainer dari registri ke sistem orkestrasi termasuk Kubernetes, DC / OS, dan Docker Swarm. Anda juga dapat menarik dari registri kontainer ke layanan Azure terkait seperti App Service, Batch, Service Fabric, dan lainnya.

    Tip

    Perwakilan layanan disarankan di beberapa skenario Kubernetes untuk melakukan penarikan citra dari registri kontainer Azure. Dengan Azure Kubernetes Service (AKS), Anda juga dapat menggunakan mekanisme otomatis untuk mengautentikasi dengan registri target dengan mengaktifkan identitas terkelola kluster.

    • Pendorongan: Bangun citra kontainer dan dorong ke registri menggunakan solusi integrasi dan penyebaran berkelanjutan seperti Azure Pipelines atau Jenkins.

Untuk akses individual ke registri, seperti ketika Anda menarik gambar kontainer secara manual ke stasiun kerja pengembangan Anda, sebaiknya gunakan identitas Microsoft Entra Anda sendiri sebagai gantinya untuk akses registri (misalnya, dengan az acr login).

Membuat perwakilan layanan

Untuk membuat perwakilan layanan dengan akses ke registri kontainer Anda, jalankan skrip berikut di Azure Cloud Shell atau penginstalan lokal Azure CLI. Skrip diformat untuk shell Bash.

Sebelum menjalankan skrip, perbarui variabel ACR_NAME ​​dengan nama registri kontainer Anda. Nilai SERVICE_PRINCIPAL_NAME harus unik dalam penyewa Microsoft Entra Anda. Jika Anda menerima kesalahan "'http://acr-service-principal' already exists.", tentukan nama yang berbeda untuk perwakilan layanan.

Anda dapat secara opsional mengubah nilai --role dalam perintah az ad sp create-for-rbac jika Anda ingin memberikan izin yang berbeda. Untuk daftar lengkap peran, lihat peran dan izin Azure Container Registry.

Setelah Anda menjalankan skrip, catat ID dan kata sandi perwakilan layanan. Setelah memiliki kredensialnya, Anda dapat mengonfigurasi aplikasi dan layanan untuk mengautentikasi ke registri kontainer Anda sebagai perwakilan layanan.

#!/bin/bash
# This script requires Azure CLI version 2.25.0 or later. Check version with `az --version`.

# Modify for your environment.
# ACR_NAME: The name of your Azure Container Registry
# SERVICE_PRINCIPAL_NAME: Must be unique within your AD tenant
ACR_NAME=$containerRegistry
SERVICE_PRINCIPAL_NAME=$servicePrincipal

# Obtain the full registry ID
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query "id" --output tsv)
# echo $registryId

# Create the service principal with rights scoped to the registry.
# Default permissions are for docker pull access. Modify the '--role'
# argument value as desired:
# acrpull:     pull only
# acrpush:     push and pull
# owner:       push, pull, and assign roles
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME --scopes $ACR_REGISTRY_ID --role acrpull --query "password" --output tsv)
USER_NAME=$(az ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv)

# Output the service principal's credentials; use these in your services and
# applications to authenticate to the container registry.
echo "Service principal ID: $USER_NAME"
echo "Service principal password: $PASSWORD"

Menggunakan perwakilan layanan yang ada

Untuk memberikan akses registri ke perwakilan layanan yang ada, Anda harus menetapkan peran baru ke perwakilan layanan. Seperti halnya membuat perwakilan layanan baru, Anda dapat memberikan antara lain tarik, dorong dan tarik, dan akses pemilik.

Skrip berikut menggunakan perintah az role assignment create untuk memberikan izin pull kepada perwakilan layanan yang Anda tentukan dalam variabel SERVICE_PRINCIPAL_ID. Sesuaikan nilai --role jika Anda ingin memberikan tingkat akses yang berbeda.

#!/bin/bash
# Modify for your environment. The ACR_NAME is the name of your Azure Container
# Registry, and the SERVICE_PRINCIPAL_ID is the service principal's 'appId' or
# one of its 'servicePrincipalNames' values.
ACR_NAME=$containerRegistry
SERVICE_PRINCIPAL_ID=$servicePrincipal

# Populate value required for subsequent command args
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)

# Assign the desired role to the service principal. Modify the '--role' argument
# value as desired:
# acrpull:     pull only
# acrpush:     push and pull
# owner:       push, pull, and assign roles
az role assignment create --assignee $SERVICE_PRINCIPAL_ID --scope $ACR_REGISTRY_ID --role acrpull

Skrip sampel

Anda dapat menemukan contoh skrip Azure CLI sebelumnya di GitHub, serta versi untuk Azure PowerShell:

Autentikasi dengan perwakilan layanan

Setelah Anda memiliki perwakilan layanan yang telah Anda beri akses ke registri kontainer, Anda dapat mengonfigurasi info masuknya untuk akses ke layanan dan aplikasi "headless", atau memasukkannya menggunakan perintah docker login. Gunakan nilai berikut:

  • Nama pengguna - ID aplikasi (klien) perwakilan layanan
  • Kata sandi - kata sandi (rahasia klien) perwakilan layanan

Nilai Nama Pengguna memiliki format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Tip

Anda dapat membuat kembali kata sandi (rahasia klien) perwakilan layanan dengan menjalankan perintah az ad sp credential reset.

Menggunakan info masuk dengan layanan Azure

Anda dapat menggunakan info masuk perwakilan layanan dari layanan Azure apa pun yang mengautentikasi dengan registri kontainer Azure. Gunakan info masuk perwakilan layanan di tempat info masuk admin registri untuk berbagai skenario.

Penggunaan dengan login docker

Anda dapat menjalankan docker login menggunakan perwakilan layanan. Dalam contoh berikut, ID aplikasi perwakilan layanan diteruskan dalam variabel lingkungan $SP_APP_ID, dan kata sandi dalam variabel $SP_PASSWD. Untuk praktik yang direkomendasikan dalam mengelola info masuk Docker, lihat referensi perintah login docker.

# Log in to Docker with service principal credentials
docker login myregistry.azurecr.io --username $SP_APP_ID --password $SP_PASSWD

Setelah masuk, Docker menyimpan info masuk.

Penggunaan dengan sertifikat

Jika Anda telah menambahkan sertifikat ke perwakilan layanan, Anda dapat masuk ke Azure CLI dengan autentikasi berbasis sertifikat, lalu menggunakan perintah az acr login untuk mengakses registri. Menggunakan sertifikat sebagai rahasia, alih-alih kata sandi, memberikan keamanan tambahan saat Anda menggunakan CLI.

Sertifikat yang ditandatangani sendiri dapat dibuat ketika Anda membuat perwakilan layanan. Atau, tambahkan satu atau beberapa sertifikat ke perwakilan layanan yang ada. Misalnya, jika Anda menggunakan salah satu skrip dalam artikel ini untuk membuat atau memperbarui perwakilan layanan dengan hak untuk menarik atau mendorong citra dari registri, tambahkan sertifikat menggunakan perintah az ad sp credential reset.

Untuk menggunakan perwakilan layanan dengan sertifikat untuk masuk ke Azure CLI, sertifikat harus dalam format PEM dan menyertakan kunci privat. Jika sertifikat Anda tidak dalam format yang diwajibkan, gunakan alat seperti openssl untuk mengonversinya. Ketika Anda menjalankan az login untuk masuk ke CLI menggunakan perwakilan layanan, juga menyediakan ID aplikasi perwakilan layanan dan ID penyewa Direktori Aktif. Contoh berikut menunjukkan nilai-nilai ini sebagai variabel lingkungan:

az login --service-principal --username $SP_APP_ID --tenant $SP_TENANT_ID  --password /path/to/cert/pem/file

Kemudian, jalankan az acr login untuk mengautentikasi dengan registri:

az acr login --name myregistry

CLI menggunakan token yang dibuat saat Anda menjalankan az login untuk mengautentikasi sesi Anda dengan registri.

Membuat perwakilan layanan untuk skenario lintas penyewa

Perwakilan layanan juga dapat digunakan dalam skenario Azure yang memerlukan penarikan gambar dari registri kontainer dalam satu ID Microsoft Entra (penyewa) ke layanan atau aplikasi di layanan atau aplikasi lain. Misalnya, organisasi mungkin menjalankan aplikasi di Penyewa A yang perlu menarik citra dari registri kontainer bersama di Penyewa B.

Untuk membuat perwakilan layanan yang dapat mengautentikasi dengan registri kontainer dalam skenario lintas penyewa:

  • Buat aplikasi multipenyewa baru (perwakilan layanan) di Penyewa A
  • Provisikan aplikasi di Penyewa B
  • Beri perwakilan layanan izin untuk melakukan penarikan dari registri di Penyewa B
  • Perbarui layanan atau aplikasi di Penyewa A untuk mengautentikasi menggunakan perwakilan layanan baru

Untuk contoh langkah-langkah, lihat Menarik citra dari registri kontainer ke kluster AKS di penyewa AD yang berbeda.

Perpanjangan perwakilan layanan

Perwakilan layanan dibuat dengan masa berlaku satu tahun. Anda memiliki opsi untuk memperpanjang masa berlaku lebih dari satu tahun, atau dapat memberikan tanggal kedaluwarsa pilihan Anda menggunakan az ad sp credential reset perintah.

Langkah berikutnya