Metode autentikasi

Halaman ini menjelaskan cara mengonfigurasi klien pihak ketiga untuk mengautentikasi dengan Container Registry.

Layanan Google Cloud yang terintegrasi dengan Container Registry telah dikonfigurasi sebelumnya dengan izin untuk mengakses repositori dalam project yang sama. Anda tidak perlu mengonfigurasi autentikasi untuk layanan ini, tetapi Anda harus memverifikasi bahwa izin dikonfigurasi dengan benar.

Sebelum memulai

1. Pastikan Anda telah mengaktifkan Container Registry API dan menginstal gcloud CLI. Lihat Mengaktifkan dan menonaktifkan layanan untuk mengetahui petunjuknya.

2. Pastikan akun yang Anda gunakan untuk autentikasi memiliki izin untuk mengakses Container Registry. Sebaiknya gunakan akun layanan, bukan akun pengguna.

3. Instal Docker jika belum diinstal. Docker disertakan dalam Cloud Shell.

4. Docker memerlukan akses dengan hak istimewa untuk berinteraksi dengan registry. Di Linux atau Windows, tambahkan pengguna yang Anda gunakan untuk menjalankan perintah Docker ke grup keamanan Docker. Langkah ini tidak diperlukan di MacOS karena Docker Desktop berjalan di virtual machine sebagai pengguna root.

   Linux

   Grup keamanan Docker disebut docker. Untuk menambahkan nama pengguna, jalankan perintah berikut:

   sudo usermod -a -G docker ${USER}
   

   Windows

   Grup keamanan Docker disebut docker-users. Untuk menambahkan pengguna dari command prompt Administrator, jalankan perintah berikut:

   net localgroup docker-users DOMAIN\USERNAME /add
   

   Dari mana

   • DOMAIN adalah domain Windows Anda.
   • USERNAME adalah nama pengguna Anda.

   Logout dan login kembali agar perubahan keanggotaan grup diterapkan. Jika menggunakan virtual machine, Anda mungkin perlu memulai ulang virtual machine agar perubahan keanggotaan diterapkan.

   Catatan: Grup keamanan Docker memiliki akses yang setara dengan pengguna root atau Administrator. Hanya tambahkan pengguna tepercaya yang memerlukan akses ke Docker. Untuk mengetahui detail tentang dampak keamanan, lihat Keamanan daemon Docker.

Metode autentikasi

Anda harus mengonfigurasi klien pihak ketiga yang perlu mengakses Container Registry.

Metode autentikasi berikut tersedia:

Pembantu kredensial gcloud (Direkomendasikan)

Konfigurasi kredensial Container Registry Anda untuk digunakan dengan Docker langsung di gcloud. Gunakan metode ini jika memungkinkan untuk akses aman dan berumur pendek ke resource project Anda. Opsi ini hanya mendukung Docker versi 18.03 atau yang lebih baru.

Pembantu kredensial mandiri

Opsi ini terutama untuk mengonfigurasi kredensial Anda agar dapat digunakan dengan Docker jika tidak ada Google Cloud CLI. Opsi ini hanya mendukung Docker versi 18.03 atau yang lebih baru.

Token akses

Kredensial Default Aplikasi menyediakan token akses berjangka pendek yang digunakan akun layanan untuk mengakses resource Google Cloud Anda. Ini adalah alternatif yang paling aman untuk menggunakan gcloud sebagai helper kredensial.

File kunci JSON

Pasangan kunci yang dikelola pengguna yang dapat Anda gunakan sebagai kredensial untuk akun layanan. Karena kredensial memiliki masa berlaku yang lama, kredensial ini adalah opsi yang paling tidak aman dari semua metode autentikasi yang tersedia.

Jika memungkinkan, gunakan token akses atau metode autentikasi lain yang tersedia untuk mengurangi risiko akses tanpa izin ke artefak Anda. Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan benar. Anda harus memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus mengautentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan atas operasi lainnya yang dijelaskan oleh Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan mungkin dinonaktifkan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.

Peringatan: Pembantu kredensial Docker hanya didukung untuk Docker 18.03 atau yang lebih baru. Bug pada klien Docker versi sebelumnya memperlambat docker build secara drastis saat helper kredensial dikonfigurasi.

Beberapa alat atau alur kerja tidak memberikan dukungan yang baik untuk menggunakan gcloud sebagai helper kredensial. Jika Anda menggunakan salah satu opsi alternatif, pastikan Anda memahami implikasi keamanannya.

Setelan autentikasi di file konfigurasi Docker

Docker menyimpan setelan autentikasi dalam file konfigurasi config.json.

• Linux: ~/.docker/config.json
• Windows: %USERPROFILE%\.docker\config.json

Ada bagian terpisah dalam file untuk metode autentikasi yang berbeda:

credHelpers

Jika Anda menggunakan helper kredensial Docker untuk autentikasi, Container Registry akan menyimpan setelan helper kredensial di bagian credHelpers file.

auths

Jika Anda menggunakan Docker untuk login dengan token atau kunci akun layanan sebagai sandi, Docker akan menyimpan kredensial Anda di bagian auths file.

credStore

Jika Anda mengonfigurasi penyimpanan kredensial untuk mengelola kredensial, setelan untuk penyimpanan kredensial berada di bagian credStore file.

Saat terhubung ke registry, Docker akan memeriksa terlebih dahulu helper kredensial yang terkait dengan host. Jadi, jika config.json Anda menyertakan setelan Container Registry di bagian credHelpers dan auths, setelan di bagian auths akan diabaikan.

gcloud credential helper

Sebaiknya gunakan metode ini jika memungkinkan. API ini memberikan akses yang aman dan berumur pendek ke resource project Anda.

Gunakan gcloud CLI untuk mengonfigurasi autentikasi di Cloud Shell atau lingkungan mana pun tempat Google Cloud CLI diinstal. Cloud Shell menyertakan Docker versi terbaru.

Untuk mengonfigurasi autentikasi:

1. Login ke gcloud sebagai pengguna yang akan menjalankan perintah Docker.

   • Untuk mengonfigurasi autentikasi dengan kredensial pengguna, jalankan perintah berikut:

     gcloud auth login
     

   • Untuk mengonfigurasi autentikasi dengan kredensial akun layanan, jalankan perintah berikut:

     gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
     

     Dari mana

     • ACCOUNT adalah nama akun layanan dalam format [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com. Anda dapat melihat akun layanan yang ada di halaman Akun Layanan di konsol Google Cloud atau dengan perintah gcloud iam service-accounts list
     • KEY-FILE adalah file kunci akun layanan. Lihat dokumentasi Identity and Access Management (IAM) untuk mengetahui informasi tentang cara membuat kunci.
   Catatan: Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan benar. Anda harus memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus mengautentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan atas operasi lainnya yang dijelaskan oleh Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan mungkin dinonaktifkan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.

2. Konfigurasikan Docker dengan perintah berikut:

   gcloud auth configure-docker
   

   Kredensial Anda disimpan di direktori beranda pengguna.

   • Linux: $HOME/.docker/config.json
   • Windows: %USERPROFILE%/.docker/config.json

Catatan: Jika Anda biasanya menjalankan perintah Docker di Linux dengan sudo, Docker akan mencari kredensial Container Registry di /root/.docker/config.json, bukan $HOME/.docker/config.json. Jika Anda ingin menggunakan sudo dengan perintah docker, bukan menggunakan grup keamanan Docker, konfigurasikan kredensial dengan sudo gcloud auth configure-docker.

Pemandu kredensial mandiri

Helper kredensial Docker mandiri mengonfigurasi Docker untuk mengautentikasi ke Container Registry di sistem tempat gcloud CLI tidak tersedia.

Helper kredensial mengambil kredensial Container Registry Anda—baik secara otomatis, maupun dari lokasi yang ditentukan menggunakan tanda --token-source-nya, lalu menulisnya ke file konfigurasi Docker. Dengan cara ini, Anda dapat menggunakan alat command line Docker, docker, untuk berinteraksi langsung dengan Container Registry.

Untuk mengonfigurasi autentikasi:

1. Login ke mesin sebagai pengguna yang akan menjalankan perintah Docker.

2. Download docker-credential-gcr dari rilis GitHub:

   Anda dapat menggunakan utilitas command line curl secara opsional. Contoh:

   VERSION=2.1.23
   OS=linux  # or "darwin" for OSX, "windows" for Windows.
   ARCH=amd64  # or "386" for 32-bit OSs, "arm64" for ARM 64.
   
   curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
   | tar xz docker-credential-gcr \
   && chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/
   

3. Konfigurasikan Docker dengan perintah berikut:

   docker-credential-gcr configure-docker
   

   Kredensial Anda disimpan di direktori beranda pengguna.

   • Linux: $HOME/.docker/config.json
   • Windows: %USERPROFILE%/.docker/config.json

Lihat dokumentasi helper kredensial Docker mandiri di GitHub untuk mengetahui informasi selengkapnya.

Catatan: Jika Anda biasanya menjalankan perintah Docker di Linux dengan sudo, Docker akan mencari kredensial Container Registry di /root/.docker/config.json, bukan $HOME/.docker/config.json. Jika Anda ingin menggunakan sudo dengan perintah docker, bukan menggunakan grup keamanan Docker, konfigurasikan kredensial dengan sudo docker-credential-gcr configure-docker.

Docker kini dikonfigurasi untuk melakukan autentikasi dengan Container Registry. Untuk mengirim dan menarik gambar, pastikan izin dikonfigurasi dengan benar.

Token akses

Anda dapat membuat token akses OAuth berumur pendek untuk mengautentikasi dengan Container Registry. Karena token valid selama 60 menit, Anda harus memintanya kurang dari satu jam sebelum menggunakannya untuk terhubung dengan Container Registry.

1. Buat akun layanan baru yang akan berinteraksi dengan Container Registry.

   Konsol

   1. Di konsol Google Cloud, buka halaman Create service account.

      Buka halaman Create Service Account

   2. Pilih project yang ingin Anda gunakan.

   3. Di kolom Nama akun layanan, masukkan nama.

   4. Opsional: Di kolom Deskripsi akun layanan, masukkan deskripsi.

   5. Klik Create.

   6. Klik kolom Pilih peran. Di bagian Semua peran, pilih peran Cloud Storage yang sesuai berdasarkan izin yang ingin Anda berikan ke akun layanan.

   7. Klik Done.

   gcloud

   Anda dapat menjalankan perintah berikut menggunakan Google Cloud CLI di komputer lokal, atau di Cloud Shell.

   1. Buat akun layanan. Ganti NAME dengan nama untuk akun layanan.

      gcloud iam service-accounts create NAME

   2. Berikan peran ke akun layanan. Ganti PROJECT_ID dengan project ID Anda dan ROLE dengan peran Cloud Storage yang sesuai untuk akun layanan. Peran ini berlaku di seluruh repositori dalam project. Anda dapat mengubah peran nanti, dan Anda juga dapat memberikan peran yang berbeda ke akun layanan di repositori tertentu.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

2. Dapatkan kunci untuk akun layanan yang akan berinteraksi dengan Container Registry.

   Catatan: Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan benar. Anda harus memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus mengautentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan atas operasi lainnya yang dijelaskan oleh Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan mungkin dinonaktifkan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.

   Konsol

   1. Di konsol Google Cloud, buka halaman Akun Layanan.

      Buka halaman Service Accounts

   2. Klik alamat email akun layanan yang ingin Anda gunakan.

   3. Klik Kunci.

   4. Klik Tambahkan kunci, lalu Buat kunci baru.

   5. Klik Create. File JSON yang berisi kunci Anda akan didownload ke komputer Anda.

      Petunjuk di halaman ini menggunakan nama file keyfile.json untuk file kunci ini.

   6. Klik Close.

   gcloud

   Anda dapat menjalankan perintah berikut menggunakan Google Cloud CLI di komputer lokal, atau di Cloud Shell.

   Petunjuk di halaman ini menggunakan nama file keyfile.json untuk file kunci.

   gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

3. Jalankan perintah berikut untuk login ke Google Cloud CLI sebagai akun layanan.

   gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
   

   Dari mana

   • ACCOUNT adalah nama akun layanan dalam format [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com.
   • KEY-FILE adalah file kunci akun layanan. Lihat dokumentasi IAM untuk mengetahui informasi tentang cara membuat kunci.

4. Pastikan izin dikonfigurasi dengan benar untuk akun layanan. Jika menggunakan akun layanan Compute Engine, Anda harus mengonfigurasi izin dan cakupan akses dengan benar.

5. Dapatkan token akses untuk akun layanan. Karena token memiliki masa berlaku yang singkat, minta token kurang dari satu jam sebelum Anda menggunakannya untuk terhubung dengan Container Registry.

   Jalankan perintah berikut:

   Linux

   gcloud auth print-access-token | docker login -u oauth2accesstoken \
       --password-stdin https://HOSTNAME
   

   Windows

   gcloud auth print-access-token |
       docker login -u oauth2accesstoken --password-stdin https://HOSTNAME
   

   dengan HOSTNAME adalah gcr.io, us.gcr.io, eu.gcr.io, atau asia.gcr.io.

   Catatan: Layanan Google Cloud yang menyediakan image di subdomain gcr.io mungkin memerlukan autentikasi. Misalnya, Anda harus mengautentikasi ke marketplace.gcr.io untuk mengambil image dari Google Cloud Marketplace.

Docker kini diautentikasi dengan Container Registry.

File kunci JSON

Kunci akun layanan adalah pasangan kunci jangka panjang yang dapat Anda gunakan sebagai kredensial untuk akun layanan. Tidak seperti token akses OAuth, masa berlaku kunci akun layanan tidak akan berakhir.

Catatan: Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan benar. Anda harus memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus mengautentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan atas operasi lainnya yang dijelaskan oleh Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan mungkin dinonaktifkan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.

Siapa pun yang memiliki akses ke kunci pribadi yang valid untuk akun layanan akan dapat mengakses resource melalui akun layanan. Misalnya, beberapa akun layanan yang dibuat secara otomatis oleh Google Cloud, seperti akun layanan Container Registry, diberi peran Editor baca-tulis untuk project induk. Akun layanan default Compute Engine dikonfigurasi dengan akses hanya baca ke penyimpanan dalam project yang sama.

Selain itu, siklus proses akses kunci ke akun layanan (dan dengan demikian, data yang dapat diakses akun layanan) tidak bergantung pada siklus proses pengguna yang telah mendownload kunci.

Gunakan panduan berikut untuk membatasi akses ke image container Anda:

• Buat akun layanan khusus yang hanya digunakan untuk berinteraksi dengan Container Registry.
• Berikan peran tertentu untuk jumlah akses minimum yang diperlukan akun layanan.
• Ikuti praktik terbaik untuk mengelola kredensial.

Untuk membuat akun layanan baru dan kunci akun layanan hanya untuk digunakan dengan repositori Container Registry:

1. Buat akun layanan baru yang akan berinteraksi dengan Container Registry.

   Konsol

   1. Di konsol Google Cloud, buka halaman Create service account.

      Buka halaman Create Service Account

   2. Pilih project yang ingin Anda gunakan.

   3. Di kolom Nama akun layanan, masukkan nama.

   4. Opsional: Di kolom Deskripsi akun layanan, masukkan deskripsi.

   5. Klik Create.

   6. Klik kolom Pilih peran. Di bagian Semua peran, pilih peran Cloud Storage yang sesuai untuk akun layanan.

   7. Klik Done.

   gcloud

   Anda dapat menjalankan perintah berikut menggunakan Google Cloud CLI di komputer lokal, atau di Cloud Shell.

   1. Buat akun layanan. Ganti NAME dengan nama untuk akun layanan.

      gcloud iam service-accounts create NAME

   2. Berikan peran ke akun layanan. Ganti PROJECT_ID dengan project ID Anda dan ROLE dengan peran Cloud Storage yang sesuai untuk akun layanan.

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

2. Dapatkan kunci untuk akun layanan yang akan berinteraksi dengan Container Registry.

   Konsol

   1. Di konsol Google Cloud, buka halaman Akun Layanan.

      Buka halaman Service Accounts

   2. Klik alamat email akun layanan yang ingin Anda gunakan.

   3. Klik Kunci.

   4. Klik Tambahkan kunci, lalu Buat kunci baru.

   5. Klik Create. File JSON yang berisi kunci Anda akan didownload ke komputer Anda.

      Petunjuk di halaman ini menggunakan nama file keyfile.json untuk file kunci ini.

   6. Klik Close.

   gcloud

   Anda dapat menjalankan perintah berikut menggunakan Google Cloud CLI di komputer lokal, atau di Cloud Shell.

   Petunjuk di halaman ini menggunakan nama file keyfile.json untuk file kunci.

   gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

3. Pastikan izin dikonfigurasi dengan benar untuk akun layanan. Jika menggunakan akun layanan Compute Engine, Anda harus mengonfigurasi izin dan cakupan akses dengan benar.

4. Gunakan kunci akun layanan sebagai sandi Anda untuk mengautentikasi dengan Docker.

   Linux / macOS

   cat KEY-FILE | docker login -u _json_key --password-stdin \
   https://HOSTNAME
   

   Windows

   Get-Content KEY-FILE |
   docker login -u _json_key --password-stdin https://HOSTNAME
   

   Ganti kode berikut:

   • KEY-FILE adalah nama file kunci akun layanan dalam format JSON.
   • HOSTNAME adalah gcr.io, us.gcr.io, eu.gcr.io, atau asia.gcr.io.
   Catatan: Layanan Google Cloud yang menyediakan gambar di subdomain gcr.io mungkin memerlukan autentikasi. Misalnya, Anda harus mengautentikasi ke marketplace.gcr.io untuk mengambil image dari Google Cloud Marketplace.

Docker kini diautentikasi dengan Container Registry.