Metode autentikasi

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

Layanan Google Cloud yang integrate 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 telah 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 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 mesin virtual 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 setiap klien pihak ketiga yang perlu mengakses Container Registry.

Tersedia metode autentikasi berikut:

Pembantu kredensial gcloud (Direkomendasikan)

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

Helper kredensial mandiri

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

Token akses

Kredensial Default Aplikasi menyediakan token akses jangka pendek yang digunakan akun layanan untuk mengakses resource Google Cloud Anda. Cara ini paling aman dari alternatif 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 berumur panjang, 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 tidak sah 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 melakukan autentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan untuk operasi lain yang dijelaskan dalam 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 informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.

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

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

Setelan autentikasi di file konfigurasi Docker

Docker menyimpan setelan autentikasi di file konfigurasi config.json.

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

Ada bagian terpisah dalam file tersebut 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 pada 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 helper kredensial yang terkait dengan host terlebih dahulu. Jadi, jika config.json Anda menyertakan setelan Container Registry di bagian credHelpers dan auths, setelan di bagian auths akan diabaikan.

helper kredensial gcloud

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

Gunakan gcloud CLI untuk mengonfigurasi autentikasi di Cloud Shell atau lingkungan apa pun tempat Google Cloud CLI diinstal. Cloud Shell menyertakan versi Docker saat ini.

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 Service Accounts di Google Cloud Console 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 merupakan risiko keamanan jika tidak dikelola dengan benar. Anda harus memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus melakukan autentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan untuk operasi lain yang dijelaskan dalam 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 utama 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.

Helper kredensial mandiri

Helper kredensial Docker mandiri mengonfigurasi Docker untuk melakukan autentikasi ke Container Registry pada sistem yang tidak menyediakan gcloud CLI.

Helper kredensial mengambil kredensial Container Registry Anda—baik secara otomatis, maupun dari lokasi yang ditentukan menggunakan flag --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 komputer sebagai pengguna yang akan menjalankan perintah Docker.

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

   Secara opsional, Anda dapat menggunakan utilitas command line curl. Contoh:

   VERSION=2.1.22
   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 utama 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 mengambil image, pastikan izin dikonfigurasi dengan benar.

Token akses

Anda dapat membuat token akses OAuth yang memiliki masa aktif singkat untuk melakukan autentikasi dengan Container Registry. Karena token ini berlaku selama 60 menit, Anda harus memintanya kurang dari satu jam sebelum menggunakannya untuk terhubung dengan Container Registry.

1. Membuat 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 All roles, 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 mesin lokal Anda, 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 tersebut nanti, dan 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 melakukan autentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan untuk operasi lain yang dijelaskan dalam 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 didownload ke komputer.

      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 Anda, 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 pembuatan 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 berumur pendek, 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 melakukan autentikasi ke marketplace.gcr.io untuk mengambil gambar dari Google Cloud Marketplace.

Docker kini diautentikasi dengan Container Registry.

File kunci JSON

Kunci akun layanan adalah pasangan kunci yang berumur panjang dan 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 melakukan autentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan untuk operasi lain yang dijelaskan dalam 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 otomatis dibuat oleh Google Cloud, seperti akun layanan Container Registry, diberi peran baca-tulis Editor 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 (sehingga 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 paling sedikit yang diperlukan akun layanan.
• Ikuti praktik terbaik untuk mengelola kredensial.

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

1. Membuat 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 All roles, pilih peran Cloud Storage yang sesuai untuk akun layanan tersebut.

   7. Klik Done.

   gcloud

   Anda dapat menjalankan perintah berikut menggunakan Google Cloud CLI di mesin lokal Anda, 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 didownload ke komputer.

      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 Anda, 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 melakukan autentikasi dengan Docker.

   Linux / Mac

   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 image di subdomain gcr.io mungkin memerlukan autentikasi. Misalnya, Anda harus melakukan autentikasi ke marketplace.gcr.io untuk mengambil gambar dari Google Cloud Marketplace.

Docker kini diautentikasi dengan Container Registry.