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.

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.

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

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.

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.

    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.

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.

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:

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.

Docker kini diautentikasi dengan Container Registry.