Membuat token dengan izin yang dicakup repositori

  • Artikel

Artikel ini menjelaskan cara membuat token dan peta cakupan untuk mengelola akses ke repositori di registri kontainer Anda. Dengan membuat token, pemilik registri dapat menyediakan pengguna atau layanan dengan akses terbatas waktu ke repositori untuk menarik atau mendorong gambar atau melakukan tindakan lain. Token menyediakan izin yang lebih baik daripada opsi autentikasi registri lainnya, yang mencakup izin ke seluruh registri.

Skenario umum untuk membuat token meliputi:

  • Izinkan perangkat IoT dengan token individual untuk menarik gambar dari repositori.
  • Berikan izin kepada organisasi eksternal ke jalur repositori.
  • Membatasi akses repositori ke grup pengguna yang berbeda di organisasi Anda. Misalnya, berikan akses tulis dan baca ke pengembang yang membangun gambar yang menargetkan repositori tertentu, dan membaca akses ke tim yang menyebar dari repositori tersebut.

Fitur ini tersedia di semua tingkat layanan. Untuk informasi tentang tingkat dan batas layanan registri, lihat Tingkat layanan Azure Container Registry

Batasan

  • Saat ini Anda tidak dapat menetapkan izin cakupan repositori ke identitas Microsoft Entra, seperti perwakilan layanan atau identitas terkelola.

Konsep

Untuk mengonfigurasi izin yang dicakup repositori, Anda membuat token dengan peta lingkup terkait.

  • Token bersama dengan kata sandi yang dihasilkan memungkinkan pengguna mengautentikasi dengan registri. Anda dapat mengatur tanggal kedaluwarsa untuk kata sandi token, atau menonaktifkan token kapan saja.

    Setelah mengautentikasi dengan token, pengguna atau layanan dapat melakukan satu atau beberapa tindakan yang tercakup ke satu atau beberapa repositori.

    Tindakan Deskripsi Contoh
    content/delete Menghapus data dari repositori Menghapus repositori atau manifes
    content/read Membaca data dari repositori Menarik artefak
    content/write Menulis data ke repositori Menggunakan dengan content/read untuk mendorong artefak
    metadata/read Membaca metadata dari repositori Mencantumkan tag atau manifes
    metadata/write Menulis metadata ke repositori Mengaktifkan atau menonaktifkan operasi baca, tulis, atau hapus

Catatan

Izin yang tercakup dalam repositori tidak mendukung kemampuan untuk mencantumkan katalog semua repositori dalam registri.

  • Peta cakupan mengelompokkan izin repositori yang Anda terapkan ke token dan dapat diterapkan kembali ke token lain. Setiap token dikaitkan dengan satu peta lingkup. Dengan peta cakupan, Anda dapat:

    • Konfigurasikan beberapa token dengan izin yang identik ke sekumpulan repositori.
    • Perbarui izin token saat Anda menambahkan atau menghapus tindakan repositori di peta cakupan, atau menerapkan peta cakupan yang berbeda.

    Azure Container Registry juga menyediakan beberapa peta lingkup yang ditentukan sistem yang dapat Anda terapkan saat membuat token. Izin peta cakupan yang ditentukan sistem berlaku untuk semua repositori di registri Anda. Tindakan individual sesuai dengan batas Repositori per peta cakupan.

Gambar berikut menunjukkan hubungan antara token dan peta lingkup.

Registry tokens and scope maps

Prasyarat

  • Azure CLI - Contoh perintah Azure CLI dalam artikel ini memerlukan Azure CLI versi 2.17.0 atau yang lebih baru. Jalankan az --version untuk menemukan versinya. Jika Anda perlu memasang atau meningkatkan, lihat Memasang Azure CLI.
  • Docker - Untuk mengautentikasi dengan registri untuk menarik atau mendorong gambar, Anda memerlukan penginstalan Docker lokal. Docker menyediakan instruksi instalasi untuk sistem macOS, Windows, dan Linux.
  • Registri kontainer - Jika Anda tidak memilikinya, buat registri kontainer di langganan Azure Anda. Misalnya, gunakan portal Microsoft Azure atau Azure CLI.

Buat token - CLI

Buat token dan tentukan repositori

Buat token menggunakan perintah az acr token create. Saat membuat token, Anda dapat menentukan satu atau beberapa repositori dan tindakan terkait di setiap repositori. Repositori tidak perlu berada di registri dulu. Untuk membuat token dengan menentukan peta lingkup yang sudah ada, lihat bagian berikutnya.

Contoh berikut membuat token di myregistry registri dengan izin berikut pada samples/hello-world repo: content/write dan content/read. Secara default, perintah mengatur status token default ke enabled, tetapi Anda dapat memperbarui status disabled kapan saja.

az acr token create --name MyToken --registry myregistry \
  --repository samples/hello-world \
  content/write content/read \
  --output json

Output menunjukkan detail tentang token. Secara default, dua kata sandi dibuat yang tidak kedaluwarsa, tetapi Anda dapat secara opsional mengatur tanggal kedaluwarsa. Disarankan untuk menyimpan kata sandi di tempat yang aman agar dapat digunakan nanti untuk autentikasi. Kata sandi tidak dapat diambil lagi, tetapi kata sandi baru dapat dihasilkan.

{
  "creationDate": "2020-01-18T00:15:34.066221+00:00",
  "credentials": {
    "certificates": [],
    "passwords": [
      {
        "creationTime": "2020-01-18T00:15:52.837651+00:00",
        "expiry": null,
        "name": "password1",
        "value": "uH54BxxxxK7KOxxxxRbr26dAs8JXxxxx"
      },
      {
        "creationTime": "2020-01-18T00:15:52.837651+00:00",
        "expiry": null,
        "name": "password2",
        "value": "kPX6Or/xxxxLXpqowxxxxkA0idwLtmxxxx"
      }
    ],
    "username": "MyToken"
  },
  "id": "/subscriptions/xxxxxxxx-adbd-4cb4-c864-xxxxxxxxxxxx/resourceGroups/myresourcegroup/providers/Microsoft.ContainerRegistry/registries/myregistry/tokens/MyToken",
  "name": "MyToken",
  "objectId": null,
  "provisioningState": "Succeeded",
  "resourceGroup": "myresourcegroup",
  "scopeMapId": "/subscriptions/xxxxxxxx-adbd-4cb4-c864-xxxxxxxxxxxx/resourceGroups/myresourcegroup/providers/Microsoft.ContainerRegistry/registries/myregistry/scopeMaps/MyToken-scope-map",
  "status": "enabled",
  "type": "Microsoft.ContainerRegistry/registries/tokens"
}

Catatan

Untuk meregenerasi kata sandi token dan periode kedaluwarsa, lihat Meregenerasi kata sandi token nanti di artikel ini.

Output termasuk detail tentang peta lingkup yang dibuat perintah. Anda dapat menggunakan peta lingkup, di sini bernama MyToken-scope-map, untuk menerapkan tindakan repositori yang sama ke token lain. Atau, perbarui peta lingkup nanti untuk mengubah izin token terkait.

Membuat token dan menentukan peta lingkup

Cara alternatif untuk membuat token adalah dengan menentukan peta lingkup yang ada. Jika Anda belum memiliki peta lingkup, pertama-tama buat dengan menentukan repositori dan tindakan terkait. Kemudian, tentukan peta lingkup saat membuat token.

Untuk membuat peta lingkup, gunakan perintah az acr scope-map create. Perintah berikut membuat peta lingkup dengan izin yang sama pada repositori samples/hello-world yang digunakan sebelumnya.

az acr scope-map create --name MyScopeMap --registry myregistry \
  --repository samples/hello-world \
  content/write content/read \
  --description "Sample scope map"

Jalankan az acr token create untuk membuat token, menentukan peta lingkup MyScopeMap. Seperti contoh sebelumnya, perintah mengatur status token default menjadi enabled.

az acr token create --name MyToken \
  --registry myregistry \
  --scope-map MyScopeMap

Output menunjukkan detail tentang token. Secara default, dua kata sandi dihasilkan. Disarankan untuk menyimpan kata sandi di tempat yang aman agar dapat digunakan nanti untuk autentikasi. Kata sandi tidak dapat diambil lagi, tetapi kata sandi baru dapat dihasilkan.

Catatan

Untuk meregenerasi kata sandi token dan periode kedaluwarsa, lihat Meregenerasi kata sandi token nanti di artikel ini.

Cara menggunakan peta cakupan untuk menentukan dan menetapkan izin untuk beberapa repositori

Peta cakupan memungkinkan penggunaan karakter kartubebas untuk menentukan dan memberikan izin serupa untuk beberapa repositori yang berbagi awalan umum. Repositori dengan izin tertentu, repositori dengan karakter kartubebas juga dapat digunakan dalam peta cakupan yang sama. Ini memberikan fleksibilitas dalam mengelola izin untuk beberapa set repositori dalam satu peta cakupan.

Izin repositori dapat dibuat saat peta cakupan dibuat dan ditetapkan ke token. Atau, token dapat dibuat dan langsung ditetapkan ke repositori.

Contoh berikut membuat peta cakupan dengan karakter kartubebas lalu menetapkannya ke token.

az acr scope-map create --name MyScopeMapWildcard --registry myregistry \
  --repository samples/* \
  content/write content/read \
  --description "Sample scope map with wildcards"
az acr token create --name MyTokenWildcard \
  --registry myregistry \
  --scope-map MyScopeMapWildcard

Contoh berikut membuat token dengan kartubebas.

 az acr token create --name MyTokenWildcard --registry myregistry \
  --repository samples/* \
  content/write content/read \

Izin kartubebas bersifat aditif, yang berarti bahwa ketika repositori tertentu diakses, izin yang dihasilkan akan menyertakan izin untuk semua aturan peta cakupan yang cocok dengan awalan kartubebas.

Dalam contoh ini, peta cakupan menentukan izin untuk tiga jenis repositori yang berbeda:

Repositori Izin
sample/* content/read
sample/teamA/* content/write
sample/teamA/projectB content/delete

Token diberi peta cakupan untuk memberikan [content/read, content/write, content/delete] izin untuk mengakses repositori sample/teamA/projectB. Namun, ketika token yang sama digunakan untuk mengakses sample/teamA/projectC repositori, token tersebut hanya memiliki [content/read, content/write] izin.

Penting

Repositori yang menggunakan kartubebas dalam peta cakupan harus selalu diakhiri dengan /* akhiran agar valid dan memiliki satu karakter kartubebas dalam nama repositori. Berikut adalah beberapa contoh kartubebas yang tidak valid:

  • sample/*/teamA dengan kartubebas di tengah nama repositori.
  • sample/teamA* dengan kartubebas tidak diakhir dengan '/*''.
  • sample/teamA/*/projectB/* dengan beberapa kartubebas dalam nama repositori.

Kartubebas tingkat akar

Kartubebas juga dapat diterapkan pada tingkat akar. Ini berarti bahwa setiap izin yang ditetapkan ke repositori yang didefinisikan sebagai *, akan diterapkan di seluruh registri.

Contoh menunjukkan cara membuat token dengan kartubebas tingkat akar yang akan memberikan izin token [content/read, content/write] ke semua repositori di registri. Ini menyediakan cara sederhana untuk memberikan izin ke semua repositori dalam registri tanpa harus menentukan setiap repositori satu per satu.

 az acr token create --name MyTokenWildcard --registry myregistry \
  --repository * \
  content/write content/read \

Penting

Jika aturan wildcard mencakup repositori yang belum ada, izin aturan wildcard masih akan berlaku untuk nama repositori tersebut. Misalnya, token yang ditetapkan ke peta cakupan yang memberikan [content/write, metadata/write] izin untuk sample/* repositori. Selain itu, misalkan repositori sample/teamC/teamCimage belum ada. Token akan memiliki izin untuk mendorong gambar ke repositori sample/teamC/teamCimage, yang secara bersamaan akan membuat repositori pada pendorongan yang berhasil.

Buat token - portal

Anda dapat menggunakan portal Microsoft Azure untuk membuat token dan peta lingkup. Seperti halnya perintah CLI az acr token create, Anda dapat menerapkan peta lingkup yang ada, atau membuat peta lingkup saat Anda membuat token dengan menentukan satu atau beberapa repositori dan tindakan terkait. Repositori tidak perlu berada di registri dulu.

Contoh berikut membuat token, dan membuat peta lingkup dengan izin berikut di repositori samples/hello-world: content/write dan content/read.

  1. Di portal, navigasi ke registri kontainer Anda.

  2. Di bawah Izin repositori, pilih Token > +Tambahkan.

    Create token in portal

  3. Masukkan nama token.

  4. Di bawah Peta lingkup, pilih Buat baru.

  5. Mengonfigurasi peta lingkup:

    1. Masukkan nama dan deskripsi untuk peta lingkup.

    2. Di bawah Repositori, masukkan samples/hello-world, dan di bawah Izin, pilih content/read dan content/write. Lalu pilih +Tambahkan.

      Create scope map in portal

    3. Setelah menambahkan repositori dan izin, pilih Tambahkan untuk menambahkan peta lingkup.

  6. Terima Status token default Diaktifkan lalu pilih Buat.

Setelah token divalidasi dan dibuat, detail token muncul di layar Token.

Menambahkan kata sandi token

Untuk menggunakan token yang dibuat di portal, Anda harus membuat kata sandi. Anda dapat membuat satu atau dua kata sandi, dan menetapkan tanggal kedaluwarsa untuk masing-masing kata sandi. Kata sandi baru yang dibuat untuk token segera tersedia. Pembuatan ulang kata sandi baru untuk token akan memakan waktu 60 detik untuk direplikasi dan tersedia.

  1. Di portal, navigasi ke registri kontainer Anda.

  2. Di bawah Izin repositori, pilih Token, dan pilih token.

  3. Dalam detail token, pilih kata password1 atau password2, dan pilih ikon Hasilkan.

  4. Di layar kata sandi, secara opsional atur tanggal kedaluwarsa untuk kata sandi, dan pilih Hasilkan. Disarankan untuk menetapkan tanggal kedaluwarsa.

  5. Setelah membuat kata sandi, salin dan simpan ke lokasi yang aman. Anda tidak dapat mengambil kata sandi yang dihasilkan setelah menutup layar, tetapi Anda dapat menghasilkan kata sandi baru.

    Create token password in portal

Mengautentikasi dengan token

Ketika pengguna atau layanan menggunakan token untuk mengautentikasi dengan registri target, ia menyediakan nama token sebagai nama pengguna dan salah satu kata sandi yang dihasilkan.

Metode autentikasi bergantung pada tindakan atau tindakan yang dikonfigurasi yang terkait dengan token.

Perbuatan Cara mengautentikasi
content/delete az acr repository delete di Azure CLI

Contoh: az acr repository delete --name myregistry --repository myrepo --username MyToken --password xxxxxxxxxx
content/read docker login

az acr login di Azure CLI

Contoh: az acr login --name myregistry --username MyToken --password xxxxxxxxxx
content/write docker login

az acr login di Azure CLI
metadata/read az acr repository show

az acr repository show-tags

az acr manifest list-metadata di Azure CLI
metadata/write az acr repository untag

az acr repository update di Azure CLI

Contoh: Gunakan token

Contoh berikut menggunakan token yang dibuat sebelumnya dalam artikel ini untuk melakukan operasi umum pada repositori: mendorong dan menarik gambar, menghapus gambar, dan tag repositori daftar. Token disiapkan awalnya dengan izin dorong content/write (dan content/read tindakan) di repositori samples/hello-world.

Gambar uji tarik dan tandai

Untuk contoh berikut, tarik gambar publik hello-world dan nginx dari Microsoft Container Registry, dan tandai untuk registri dan repositori Anda.

docker pull mcr.microsoft.com/hello-world
docker pull mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine
docker tag mcr.microsoft.com/hello-world myregistry.azurecr.io/samples/hello-world:v1
docker tag mcr.microsoft.com/oss/nginx/nginx:1.15.5-alpine myregistry.azurecr.io/samples/nginx:v1

Mengautentikasi menggunakan token

Jalankan docker login atau az acr login autentikasi dengan registri untuk mendorong atau menarik gambar. Berikan nama token sebagai nama pengguna, dan berikan salah satu kata sandinya. Token harus memiliki status Enabled.

Contoh berikut diformat untuk shell bash, dan menyediakan nilai menggunakan variabel lingkungan.

TOKEN_NAME=MyToken
TOKEN_PWD=<token password>

echo $TOKEN_PWD | docker login --username $TOKEN_NAME --password-stdin myregistry.azurecr.io

Output harus menunjukkan autentikasi yang berhasil:

Login Succeeded

Mendorong gambar ke registri

Setelah berhasil masuk, coba dorong gambar yang ditandai ke registri. Karena token memiliki izin untuk mendorong gambar ke repositori samples/hello-world, dorongan berikut berhasil:

docker push myregistry.azurecr.io/samples/hello-world:v1

Token tidak memiliki izin ke repo samples/nginx, sehingga upaya dorong berikut gagal dengan kesalahan yang mirip dengan requested access to the resource is denied:

docker push myregistry.azurecr.io/samples/nginx:v1

Perbarui izin token

Untuk memperbarui izin token, perbarui izin di peta lingkup terkait. Peta lingkup yang diperbarui diterapkan langsung ke semua token terkait.

Misalnya, perbarui MyToken-scope-map dengan content/write dan tindakan content/read pada repositori samples/ngnx, dan hapus tindakan content/write di repositori samples/hello-world.

Untuk menggunakan Azure CLI, jalankan az acr scope-map update untuk memperbarui peta lingkup:

az acr scope-map update \
  --name MyScopeMap \
  --registry myregistry \
  --add-repository samples/nginx content/write content/read \
  --remove-repository samples/hello-world content/write

Di portal Microsoft Azure:

  1. Navigasikan ke registri kontainer Anda.
  2. Di bawah Izin repositori, pilih Peta cakupan, dan pilih peta cakupan yang akan diperbarui.
  3. Di bawah Repositori, masukkan samples/nginx, dan di bawah Izin, pilih content/read dan content/write. Lalu pilih +Tambahkan.
  4. Di bawah Repositori, pilih samples/hello-world dan di bawah Izin, batal pilih content/write. Kemudian pilih Simpan.

Setelah memperbarui peta lingkup, dorongan berikut berhasil:

docker push myregistry.azurecr.io/samples/nginx:v1

Karena peta lingkup hanya memiliki izin content/read pada repositori samples/hello-world, upaya dorong ke repo samples/hello-world sekarang gagal:

docker push myregistry.azurecr.io/samples/hello-world:v1

Menarik gambar dari kedua repo berhasil, karena peta lingkup menyediakan izin content/read pada kedua repositori:

docker pull myregistry.azurecr.io/samples/nginx:v1
docker pull myregistry.azurecr.io/samples/hello-world:v1

Hapus gambar

Perbarui peta lingkup dengan menambahkan tindakan content/delete ke repositori nginx. Tindakan ini memungkinkan penghapusan gambar di repositori, atau penghapusan seluruh repositori.

Untuk singkatnya, kami hanya menampilkan perintah az acr scope-map update untuk memperbarui peta cakupan:

az acr scope-map update \
  --name MyScopeMap \
  --registry myregistry \
  --add-repository samples/nginx content/delete

Untuk memperbarui peta cakupan yang menggunakan portal, lihat bagian sebelumnya.

Gunakan perintah az acr repository delete berikut untuk menghapus repositori samples/nginx. Untuk menghapus gambar atau repositori, berikan nama dan kata sandi token ke perintah. Contoh berikut menggunakan variabel lingkungan yang dibuat sebelumnya dalam artikel:

az acr repository delete \
  --name myregistry --repository samples/nginx \
  --username $TOKEN_NAME --password $TOKEN_PWD

Tampilkan tag repo

Perbarui peta lingkup dengan menambahkan tindakan metadata/read ke repositori hello-world. Tindakan ini memungkinkan membaca data manifes dan tag di repositori.

Untuk singkatnya, kami hanya menampilkan perintah az acr scope-map update untuk memperbarui peta cakupan:

az acr scope-map update \
  --name MyScopeMap \
  --registry myregistry \
  --add-repository samples/hello-world metadata/read

Untuk memperbarui peta cakupan yang menggunakan portal, lihat bagian sebelumnya.

Untuk membaca metadata dalam samples/hello-world repositori, jalankan perintah az acr manifest list-metadata atau az acr repository show-tags.

Untuk membaca metadata, berikan nama dan kata sandi token ke salah satu perintah. Contoh berikut menggunakan variabel lingkungan yang dibuat sebelumnya dalam artikel:

az acr repository show-tags \
  --name myregistry --repository samples/hello-world \
  --username $TOKEN_NAME --password $TOKEN_PWD

Contoh output:

[
  "v1"
]

Token registri dan peta lingkup

Daftar peta lingkup

Gunakan perintah az acr scope-map list, atau layar Peta cakupan di portal, untuk mencantumkan semua peta cakupan yang dikonfigurasi dalam registri. Contohnya:

az acr scope-map list \
  --registry myregistry --output table

Output terdiri dari tiga peta lingkup yang ditentukan sistem dan peta lingkup lainnya yang dihasilkan oleh Anda. Token dapat dikonfigurasi dengan salah satu peta lingkup ini.

NAME                 TYPE           CREATION DATE         DESCRIPTION
-------------------  -------------  --------------------  ------------------------------------------------------------
_repositories_admin  SystemDefined  2020-01-20T09:44:24Z  Can perform all read, write and delete operations on the ...
_repositories_pull   SystemDefined  2020-01-20T09:44:24Z  Can pull any repository of the registry
_repositories_push   SystemDefined  2020-01-20T09:44:24Z  Can push to any repository of the registry
MyScopeMap           UserDefined    2019-11-15T21:17:34Z  Sample scope map

Tampilkan detil token

Untuk melihat detail token, seperti status dan tanggal kedaluwarsa kata sandinya, jalankan perintah az acr token show , atau pilih token di layar Token di portal. Contohnya:

az acr scope-map show \
  --name MyScopeMap --registry myregistry

Gunakan perintah az acr token list, atau layar Token di portal, untuk mencantumkan semua token yang dikonfigurasi dalam registri. Contohnya:

az acr token list --registry myregistry --output table

Meregenerasi kata sandi token

Jika Anda tidak menghasilkan kata sandi token, atau Anda ingin membuat kata sandi baru, jalankan perintah az acr token credential generate. Pembuatan ulang kata sandi baru untuk token akan memakan waktu 60 detik untuk direplikasi dan tersedia.

Contoh berikut menghasilkan nilai baru untuk kata sandi1 untuk token MyToken, dengan periode kedaluwarsa 30 hari. Ini menyimpan kata sandi dalam variabel TOKEN_PWD lingkungan. Contoh ini diformat untuk shell bash.

TOKEN_PWD=$(az acr token credential generate \
  --name MyToken --registry myregistry --expiration-in-days 30 \
  --password1 --query 'passwords[0].value' --output tsv)

Untuk menggunakan portal Microsoft Azure untuk menghasilkan kata sandi token, lihat langkah-langkah di Buat token - portal sebelumnya di artikel ini.

Perbarui token dengan peta lingkup baru

Jika Anda ingin memperbarui token dengan peta lingkup yang berbeda, jalankan az acr token update dan tentukan peta lingkup baru. Contohnya:

az acr token update --name MyToken --registry myregistry \
  --scope-map MyNewScopeMap

Di portal, pada layar Token , pilih token, dan di bawah Peta cakupan, pilih peta cakupan yang berbeda.

Tip

Setelah memperbarui token dengan peta lingkup baru, Anda mungkin ingin membuat kata sandi token baru. Gunakan perintah az acr token credential generate atau regenerasi kata sandi token di portal Microsoft Azure.

Menonaktifkan atau menghapus token

Anda mungkin perlu menonaktifkan sementara penggunaan kredensial token untuk pengguna atau layanan.

Menggunakan Azure CLI, jalankan perintah az acr token update untuk mengatur status ke disabled:

az acr token update --name MyToken --registry myregistry \
  --status disabled

Di portal, pilih token di layar Token , dan pilih Nonaktifkan di bawah Status.

Untuk menghapus token agar membatalkan akses secara permanen oleh siapa pun yang menggunakan kredensialnya, jalankan perintah az acr token delete.

az acr token delete --name MyToken --registry myregistry

Di portal, pilih token di layar Token , dan pilih Buang.

Langkah berikutnya

  • Untuk mengelola peta lingkup dan token, gunakan perintah tambahan di kelompok perintah az acr scope-map dan az acr token.
  • Lihat gambaran umum autentikasi untuk opsi lain untuk mengautentikasi dengan registri kontainer Azure, termasuk menggunakan identitas Microsoft Entra, perwakilan layanan, atau akun admin.
  • Pelajari tentang pendaftar yang terhubung dan menggunakan token untuk akses.