Metodi di autenticazione

Questa pagina descrive come configurare un client di terze parti per l'autenticazione con Container Registry.

I servizi Google Cloud che si integrate con Container Registry sono preconfigurati con autorizzazioni per accedere ai repository nello stesso progetto. Non è necessario configurare l'autenticazione per questi servizi, ma devi verificare che le autorizzazioni siano configurate in modo appropriato.

Prima di iniziare

1. Verifica di aver abilitato l'API Container Registry e installato gcloud CLI. Per le istruzioni, vedi Attivazione e disattivazione del servizio.

2. Verifica che l'account che utilizzi per l'autenticazione disponga delle autorizzazioni per accedere a Container Registry. Ti consigliamo di utilizzare un account di servizio anziché un account utente.

3. Installa Docker, se non è già installato. Docker è incluso in Cloud Shell.

4. Docker richiede un accesso privilegiato per interagire con i registry. Su Linux o Windows, aggiungi l'utente che utilizzi per eseguire i comandi Docker al gruppo di sicurezza Docker. Questo passaggio non è obbligatorio su MacOS poiché Docker Desktop viene eseguito su una macchina virtuale come utente root.

   Linux

   Il gruppo di sicurezza Docker è denominato docker. Per aggiungere il nome utente, esegui questo comando:

   sudo usermod -a -G docker ${USER}
   

   Windows

   Il gruppo di sicurezza Docker è denominato docker-users. Per aggiungere un utente dal prompt dei comandi dell'amministratore, esegui questo comando:

   net localgroup docker-users DOMAIN\USERNAME /add
   

   Dove

   • DOMAIN è il tuo dominio Windows.
   • USERNAME è il tuo nome utente.

   Esci e accedi di nuovo per applicare le modifiche all'appartenenza al gruppo. Se utilizzi una macchina virtuale, potrebbe essere necessario riavviare la macchina virtuale per applicare le modifiche all'abbonamento.

   Nota: il gruppo di sicurezza Docker ha un accesso equivalente all'utente root o amministratore. Aggiungi solo utenti attendibili che richiedono l'accesso a Docker. Per maggiori dettagli sugli effetti sulla sicurezza, consulta Sicurezza del daemon di Docker.

Metodi di autenticazione

Devi configurare tutti i client di terze parti che devono accedere a Container Registry.

Sono disponibili i seguenti metodi di autenticazione:

Assistente per le credenziali gcloud (consigliato)

Configura le credenziali di Container Registry per l'utilizzo con Docker direttamente in gcloud. Utilizza questo metodo quando possibile per un accesso sicuro e di breve durata alle risorse del progetto. Questa opzione supporta solo la versione Docker 18.03 o successive.

Assistente per le credenziali autonomo

Questa opzione serve principalmente per configurare le credenziali per l'utilizzo con Docker in assenza di Google Cloud CLI. Questa opzione supporta solo la versione Docker 18.03 o successiva.

Token di accesso

Le credenziali predefinite dell'applicazione forniscono i token di accesso di breve durata utilizzati da un account di servizio per accedere alle risorse Google Cloud. È la più sicura delle alternative all'utilizzo di gcloud come assistente alle credenziali.

File chiave JSON

Una coppia di chiavi gestita dall'utente che puoi utilizzare come credenziale per un account di servizio. Poiché la credenziale è di lunga durata, è l'opzione meno sicura tra tutti i metodi di autenticazione disponibili.

Se possibile, utilizza un token di accesso o un altro metodo di autenticazione disponibile per ridurre il rischio di accessi non autorizzati ai tuoi artefatti. Le chiavi degli account di servizio comportano un rischio per la sicurezza se non vengono gestite correttamente. Dovresti scegliere un'alternativa più sicura alle chiavi degli account di servizio quando è possibile. Se devi eseguire l'autenticazione con una chiave dell'account di servizio, sei responsabile della sicurezza della chiave privata e di altre operazioni descritte nelle Best practice per la gestione delle chiavi degli account di servizio. Se non ti viene consentito di creare una chiave dell'account di servizio, la creazione di chiavi dell'account di servizio potrebbe essere disabilitata per la tua organizzazione. Per saperne di più, consulta Gestione di risorse dell'organizzazione sicure per impostazione predefinita.

Avviso: l'helper delle credenziali Docker è supportato solo per Docker 18.03 o versioni successive. Un bug nelle versioni precedenti del client Docker rallenta drasticamente docker build quando vengono configurati helper per le credenziali.

Alcuni strumenti o flussi di lavoro non offrono un supporto valido per l'utilizzo di gcloud come helper per le credenziali. Se utilizzi una delle opzioni alternative, assicurati di comprendere le implicazioni per la sicurezza.

Impostazioni di autenticazione nel file di configurazione Docker

Docker salva le impostazioni di autenticazione nel file di configurazione config.json.

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

Nel file sono presenti sezioni separate per i diversi metodi di autenticazione:

credHelpers

Se utilizzi l'helper per le credenziali Docker per l'autenticazione, Container Registry archivia le impostazioni dell'helper per le credenziali nella sezione credHelpers del file.

auths

Se utilizzi Docker per accedere con un token o una chiave dell'account di servizio come password, Docker archivia le tue credenziali nella sezione auths del file.

credStore

Se hai configurato un archivio credenziali per gestire le tue credenziali, le impostazioni dell'archivio credenziali si trovano nella sezione credStore del file.

Quando Docker si connette a un registro, controlla prima se è presente un helper delle credenziali associato all'host. Pertanto, se config.json include le impostazioni di Container Registry in entrambe le sezioni credHelpers e auths, le impostazioni nella sezione auths vengono ignorate.

Assistente per le credenziali gcloud

Ti consigliamo vivamente di utilizzare questo metodo quando possibile. Fornisce un accesso sicuro e di breve durata alle risorse del progetto.

Utilizza gcloud CLI per configurare l'autenticazione in Cloud Shell o in qualsiasi ambiente in cui è installata Google Cloud CLI. Cloud Shell include una versione attuale di Docker.

Per configurare l'autenticazione:

1. Accedi a gcloud con l'account dell'utente che eseguirà i comandi Docker.

   • Per configurare l'autenticazione con credenziali utente, esegui questo comando:

     gcloud auth login
     

   • Per configurare l'autenticazione con le credenziali dell'account di servizio, esegui questo comando:

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

     Dove

     • ACCOUNT è il nome dell'account di servizio nel formato [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com. Puoi visualizzare gli account di servizio esistenti nella pagina Account di servizio della console Google Cloud o con il comando gcloud iam service-accounts list
     • KEY-FILE è il file delle chiavi dell'account di servizio. Per informazioni sulla creazione di una chiave, consulta la documentazione di Identity and Access Management (IAM).
   Nota: le chiavi degli account di servizio comportano un rischio per la sicurezza se non vengono gestite correttamente. Dovresti scegliere un'alternativa più sicura alle chiavi degli account di servizio quando è possibile. Se devi eseguire l'autenticazione con una chiave dell'account di servizio, sei responsabile della sicurezza della chiave privata e di altre operazioni descritte nelle Best practice per la gestione delle chiavi degli account di servizio. Se non ti viene consentito di creare una chiave dell'account di servizio, la creazione di chiavi dell'account di servizio potrebbe essere disabilitata per la tua organizzazione. Per maggiori informazioni, consulta Gestione di risorse dell'organizzazione sicure per impostazione predefinita.

2. Configura Docker con il comando seguente:

   gcloud auth configure-docker
   

   Le credenziali vengono salvate nella home directory dell'utente.

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

Nota: se normalmente esegui comandi Docker su Linux con sudo, Docker cerca le credenziali di Container Registry in /root/.docker/config.json anziché in $HOME/.docker/config.json. Se vuoi utilizzare sudo con i comandi docker anziché utilizzare il gruppo di sicurezza Docker, configura le credenziali con sudo gcloud auth configure-docker.

Assistente per le credenziali autonomo

L'helper per le credenziali Docker autonomo configura Docker per l'autenticazione in Container Registry in un sistema in cui gcloud CLI non è disponibile.

L'helper per le credenziali recupera le credenziali di Container Registry (automaticamente o da una posizione specificata mediante il flag --token-source) e le scrive nel file di configurazione Docker. In questo modo, puoi utilizzare lo strumento a riga di comando di Docker, docker, per interagire direttamente con Container Registry.

Per configurare l'autenticazione:

1. Accedi alla macchina come utente che eseguirà i comandi Docker.

2. Scarica docker-credential-gcr dalle release di GitHub:

   Facoltativamente, puoi utilizzare l'utilità a riga di comando curl. Ad esempio:

   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. Configura Docker con il comando seguente:

   docker-credential-gcr configure-docker
   

   Le credenziali vengono salvate nella home directory dell'utente.

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

Per maggiori informazioni, consulta la documentazione dell'helper per le credenziali Docker autonomo su GitHub.

Nota: se normalmente esegui comandi Docker su Linux con sudo, Docker cerca le credenziali di Container Registry in /root/.docker/config.json anziché $HOME/.docker/config.json. Se vuoi utilizzare sudo con i comandi docker anziché utilizzare il gruppo di sicurezza Docker, configura le credenziali con sudo docker-credential-gcr configure-docker.

Docker è ora configurato per l'autenticazione con Container Registry. Per eseguire il push e il pull delle immagini, assicurati che le autorizzazioni siano configurate correttamente.

Token di accesso

Puoi generare un token di accesso OAuth di breve durata per autenticarti con Container Registry. Poiché il token è valido per 60 minuti, devi richiederlo meno di un'ora prima di utilizzarlo per connetterti a Container Registry.

1. Crea un nuovo account di servizio che interagirà con Container Registry.

   Console

   1. Nella console Google Cloud, vai alla pagina Crea account di servizio.

      Vai alla pagina Crea account di servizio

   2. Seleziona il progetto che vuoi utilizzare.

   3. Inserisci un nome nel campo Nome account di servizio.

   4. (Facoltativo) Nel campo Descrizione account di servizio, inserisci una descrizione.

   5. Fai clic su Crea.

   6. Fai clic sul campo Seleziona un ruolo. In Tutti i ruoli, seleziona un ruolo Cloud Storage appropriato in base alle autorizzazioni che vuoi concedere all'account di servizio.

   7. Fai clic su Fine.

   gcloud

   Puoi eseguire i comandi seguenti utilizzando Google Cloud CLI sulla tua macchina locale o in Cloud Shell.

   1. Creare l'account di servizio: Sostituisci NAME con un nome per l'account di servizio.

      gcloud iam service-accounts create NAME
      

   2. Concedi un ruolo all'account di servizio. Sostituisci PROJECT_ID con l'ID progetto e ROLE con il ruolo Cloud Storage appropriato per l'account di servizio. Questo ruolo si applica a tutti i repository nel progetto. Puoi modificare il ruolo in un secondo momento e anche concedere ruoli diversi all'account di servizio su repository specifici.

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

2. Ottenere una chiave per l'account di servizio che interagirà con Container Registry.

   Nota: le chiavi degli account di servizio comportano un rischio per la sicurezza se non vengono gestite correttamente. Dovresti scegliere un'alternativa più sicura alle chiavi degli account di servizio quando è possibile. Se devi eseguire l'autenticazione con una chiave dell'account di servizio, sei responsabile della sicurezza della chiave privata e di altre operazioni descritte nelle Best practice per la gestione delle chiavi degli account di servizio. Se non ti viene consentito di creare una chiave dell'account di servizio, la creazione di chiavi dell'account di servizio potrebbe essere disabilitata per la tua organizzazione. Per maggiori informazioni, consulta Gestione di risorse dell'organizzazione sicure per impostazione predefinita.

   Console

   1. Nella console Google Cloud, vai alla pagina Account di servizio.

      Vai alla pagina Account di servizio

   2. Fai clic sull'indirizzo email dell'account di servizio che vuoi utilizzare.

   3. Fai clic su Chiavi.

   4. Fai clic su Aggiungi chiave, quindi su Crea nuova chiave.

   5. Fai clic su Crea. Un file JSON che contiene i download delle chiavi sul computer.

      Le istruzioni in questa pagina utilizzano il nome file keyfile.json per questo file di chiave.

   6. Fai clic su Chiudi.

   gcloud

   Puoi eseguire il comando seguente utilizzando Google Cloud CLI sulla tua macchina locale o in Cloud Shell.

   Le istruzioni in questa pagina utilizzano il nome file keyfile.json per il file della chiave.

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

3. Esegui questo comando per accedere a Google Cloud CLI come account di servizio.

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

   Dove

   • ACCOUNT è il nome dell'account di servizio nel formato [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com.
   • KEY-FILE è il file delle chiavi dell'account di servizio. Per informazioni sulla creazione di una chiave, consulta la documentazione IAM.

4. Verifica che le autorizzazioni siano configurate correttamente per l'account di servizio. Se utilizzi l'account di servizio Compute Engine, devi configurare correttamente sia le autorizzazioni sia gli ambiti di accesso.

5. Richiedi un token di accesso per l'account di servizio. Poiché il token ha vita breve, richiedilo meno di un'ora prima di utilizzarlo per connetterti a Container Registry.

   Esegui questo comando:

   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
   

   dove HOSTNAME è gcr.io, us.gcr.io, eu.gcr.io o asia.gcr.io.

   Nota: i servizi Google Cloud che forniscono immagini in un sottodominio gcr.io potrebbero richiedere l'autenticazione. Ad esempio, devi autenticarti su marketplace.gcr.io per eseguire il pull delle immagini da Google Cloud Marketplace.

Docker è ora autenticato con Container Registry.

File di chiavi JSON

Una chiave dell'account di servizio è una coppia di chiavi di lunga durata che puoi utilizzare come credenziale per un account di servizio. A differenza del token di accesso OAuth, la chiave dell'account di servizio non ha scadenza.

Nota: le chiavi degli account di servizio comportano un rischio per la sicurezza se non vengono gestite correttamente. Dovresti scegliere un'alternativa più sicura alle chiavi degli account di servizio quando è possibile. Se devi eseguire l'autenticazione con una chiave dell'account di servizio, sei responsabile della sicurezza della chiave privata e di altre operazioni descritte nelle Best practice per la gestione delle chiavi degli account di servizio. Se non ti viene consentito di creare una chiave dell'account di servizio, la creazione di chiavi dell'account di servizio potrebbe essere disabilitata per la tua organizzazione. Per maggiori informazioni, consulta Gestione di risorse dell'organizzazione sicure per impostazione predefinita.

Chiunque abbia accesso a una chiave privata valida per un account di servizio potrà accedere alle risorse tramite l'account di servizio. Ad esempio, ad alcuni account di servizio creati automaticamente da Google Cloud, come l'account di servizio Container Registry, viene concesso il ruolo di lettura e scrittura Editor per il progetto padre. L'account di servizio predefinito di Compute Engine è configurato con accesso di sola lettura allo spazio di archiviazione all'interno dello stesso progetto.

Inoltre, il ciclo di vita dell'accesso della chiave all'account di servizio (e quindi ai dati a cui ha accesso l'account di servizio) è indipendente dal ciclo di vita dell'utente che ha scaricato la chiave.

Segui queste linee guida per limitare l'accesso alle immagini container:

• Creare account di servizio dedicati che vengono utilizzati solo per interagire con Container Registry.
• Concedi il ruolo specifico per il livello di accesso minimo richiesto dall'account di servizio.
• Segui le best practice per la gestione delle credenziali.

Per creare un nuovo account di servizio e una chiave dell'account di servizio da utilizzare solo con i repository Container Registry:

1. Crea un nuovo account di servizio che interagirà con Container Registry.

   Console

   1. Nella console Google Cloud, vai alla pagina Crea account di servizio.

      Vai alla pagina Crea account di servizio

   2. Seleziona il progetto che vuoi utilizzare.

   3. Inserisci un nome nel campo Nome account di servizio.

   4. (Facoltativo) Nel campo Descrizione account di servizio, inserisci una descrizione.

   5. Fai clic su Crea.

   6. Fai clic sul campo Seleziona un ruolo. In Tutti i ruoli, seleziona un ruolo di Cloud Storage appropriato per l'account di servizio.

   7. Fai clic su Fine.

   gcloud

   Puoi eseguire i comandi seguenti utilizzando Google Cloud CLI sulla tua macchina locale o in Cloud Shell.

   1. Creare l'account di servizio: Sostituisci NAME con un nome per l'account di servizio.

      gcloud iam service-accounts create NAME
      

   2. Concedi un ruolo all'account di servizio. Sostituisci PROJECT_ID con l'ID progetto e ROLE con il ruolo Cloud Storage appropriato per l'account di servizio.

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

2. Ottenere una chiave per l'account di servizio che interagirà con Container Registry.

   Console

   1. Nella console Google Cloud, vai alla pagina Account di servizio.

      Vai alla pagina Account di servizio

   2. Fai clic sull'indirizzo email dell'account di servizio che vuoi utilizzare.

   3. Fai clic su Chiavi.

   4. Fai clic su Aggiungi chiave, quindi su Crea nuova chiave.

   5. Fai clic su Crea. Un file JSON che contiene i download delle chiavi sul computer.

      Le istruzioni in questa pagina utilizzano il nome file keyfile.json per questo file di chiave.

   6. Fai clic su Chiudi.

   gcloud

   Puoi eseguire il comando seguente utilizzando Google Cloud CLI sulla tua macchina locale o in Cloud Shell.

   Le istruzioni in questa pagina utilizzano il nome file keyfile.json per il file della chiave.

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

3. Verifica che le autorizzazioni siano configurate correttamente per l'account di servizio. Se utilizzi l'account di servizio Compute Engine, devi configurare correttamente sia le autorizzazioni sia gli ambiti di accesso.

4. Utilizza la chiave dell'account di servizio come password per l'autenticazione con 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
   

   Sostituisci quanto segue:

   • KEY-FILE è il nome del file della chiave dell'account di servizio in formato JSON.
   • HOSTNAME è gcr.io, us.gcr.io, eu.gcr.io o asia.gcr.io.
   Nota: i servizi Google Cloud che forniscono immagini in un sottodominio gcr.io potrebbero richiedere l'autenticazione. Ad esempio, devi autenticarti su marketplace.gcr.io per eseguire il pull delle immagini da Google Cloud Marketplace.

Docker è ora autenticato con Container Registry.