Configurare l'autenticazione in Artifact Registry per Maven e Gradle

Devi autenticarti in Artifact Registry quando utilizzi un'applicazione di terze parti per connetterti a un repository Artifact Registry. Questa documentazione si concentra sulla configurazione di Maven e Gradle.

Non è necessario configurare l'autenticazione per Cloud Build o Google Cloud per gli ambienti di runtime come Google Kubernetes Engine e Cloud Run, ma devi verificare che siano configurate le autorizzazioni richieste. Per saperne di più, consulta le informazioni su Cloud Build e sul deployment negli ambienti di runtime Google Cloud .

Prima di iniziare

  1. Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il comando seguente:

    gcloud init

    Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  2. (Facoltativo) Configura i valori predefiniti per i comandi gcloud.
  3. Se stai configurando l'autenticazione con un repository standard, verifica la policy di gestione delle versioni in modo da poter configurare correttamente il tuo progetto Maven per i tipi di pacchetti Java che puoi caricare.

    Console

    1. Apri la pagina Repository nella console Google Cloud .

      Apri la pagina Repositori

    2. Fai clic sul repository a cui vuoi eseguire l'autenticazione.

      La sezione Dettagli mostra i criteri di versione. Se il repository ha una policy delle versioni degli snapshot, il campo Consenti sovrascritture snapshot indica se gli snapshot possono sovrascrivere le versioni degli snapshot corrispondenti nel repository.

    gcloud

    Esegui questo comando per visualizzare la descrizione di un repository.

    gcloud artifacts repositories describe REPOSITORY \
          --project=PROJECT \
          --location=LOCATION
    

    Dove

    • REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, questo viene utilizzato quando questo flag viene omesso dal comando.
    • PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.
    • LOCATION è la posizione regionale o multiregionale del repository.

    L'output del comando include informazioni sulla policy di versione in mavenConfig. In questo esempio, il repository ha una policy per le versioni degli snapshot e gli snapshot non possono sovrascrivere le versioni identiche nel repository.

    Encryption: Google-owned and Google-managed encryption key
    createTime: '2021-10-04T19:39:10.897404Z'
    format: MAVEN
    mavenConfig:
      allowSnapshotOverwrites: false
      versionPolicy: SNAPSHOT
    

    Se un repository non ha una policy di versione, il valore di mavenConfig è {}.

Panoramica

Artifact Registry supporta i seguenti metodi di autenticazione.

Utilizzare un helper di autenticazione
Questa opzione offre la massima flessibilità. Quando includi l'helper nella configurazione di Maven o Gradle, Artifact Registry cerca le credenziali del account di servizio nell'ambiente.
Specifica di una account di servizio account come credenziale
Utilizza questa opzione quando un'applicazione non supporta le credenziali predefinite dell'applicazione, ma supporta l'autenticazione con un nome utente e una password.

Le chiavi del service account sono credenziali di lunga durata. Utilizza le seguenti linee guida per limitare l'accesso ai tuoi repository:

  • Valuta la possibilità di utilizzare un account di servizio dedicato per interagire con i repository.
  • Concedi il ruolo Artifact Registry minimo richiesto dalaccount di serviziot. Ad esempio, assegna il ruolo Lettore Artifact Registry a unaccount di serviziot che scarica solo gli artefatti.
  • Se i gruppi della tua organizzazione richiedono diversi livelli di accesso a repository specifici, concedi l'accesso a livello di repository anziché a livello di progetto.
  • Segui le best practice per la gestione delle credenziali.

Autenticazione con un helper delle credenziali

Artifact Registry fornisce un wagon Maven e un plug-in Gradle come assistenti per le credenziali. Quando utilizzi l'helper delle credenziali, le tue credenziali non vengono memorizzate nel tuo progetto Java. Artifact Registry cerca le credenziali nel seguente ordine:

  1. Credenziali predefinite dell'applicazione (ADC), una strategia che cerca le credenziali nel seguente ordine:

    1. Credenziali definite nella variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

    2. Credenziali fornite dall'account di servizio predefinito per Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine o Cloud Run Functions.

  2. Credenziali fornite da Google Cloud CLI, incluse le credenziali utente dal comando gcloud auth application-default login.

La variabile GOOGLE_APPLICATION_CREDENTIALS rende esplicito l'account per l'autenticazione, il che semplifica la risoluzione dei problemi. Se non utilizzi la variabile, verifica che tutti gli account che ADC potrebbe utilizzare dispongano delle autorizzazioni richieste. Ad esempio, il service account predefinito per le VM Compute Engine, i nodi Google Kubernetes Engine e le revisioni di Cloud Run ha accesso in sola lettura ai repository. Se intendi eseguire il caricamento da questi ambienti utilizzando il account di servizio predefinito, devi modificare le autorizzazioni.

Configurare un account di servizio per un helper delle credenziali

Per creare un account di servizio e configurare l'autenticazione utilizzando la variabile di ambiente:

  1. Crea un service account che agisca per conto della tua applicazione oppure scegli un service account esistente che utilizzi per l'automazione.

    Per configurare l'autenticazione con Artifact Registry, devi conoscere la posizione del file della chiave del account di servizio. Per gli account esistenti, puoi visualizzare le chiavi e crearne di nuove nella pagina Account di servizio.

    Vai alla pagina Service account

  2. Concedi il ruolo Artifact Registry specifico all'account di servizio per fornire l'accesso al repository.

  3. Assegna la posizione del file della chiave del account di servizio alla variabile GOOGLE_APPLICATION_CREDENTIALS in modo che l'helper delle credenziali di Artifact Registry possa ottenere la chiave quando si connette ai repository.

    export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
    

    dove KEY-FILE è il percorso del file della chiave del account di servizio.

Configura Maven

  1. Configura Maven per il tipo di repository che utilizzi.

    Standard

    1. Esegui questo comando per stampare la configurazione del repository da aggiungere al tuo progetto Java.

      gcloud artifacts print-settings mvn \
          --project=PROJECT \
          --repository=REPOSITORY \
          --location=LOCATION
      

      Dove

      • PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.
      • REPOSITORY è l'ID del repository. Se hai configurato un repository predefinito di Artifact Registry, questo viene utilizzato quando questo flag viene omesso dal comando.
      • LOCATION è la posizione regionale o multiregionale del repository.
    2. Aggiungi le impostazioni restituite alle sezioni appropriate del file pom.xml per il tuo progetto Maven. Per informazioni dettagliate sulla struttura del file, consulta il riferimento POM di Maven.

      L'esempio seguente mostra le impostazioni per un repository che archivia sia le versioni snapshot che quelle di rilascio.

      
        
          artifact-registry
          artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY
        
        
          artifact-registry
          artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY
        
      
      
      
        
          artifact-registry
          artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY
          
            true
          
          
            true
          
        
      
      
      
        
          
            com.google.cloud.artifactregistry
            artifactregistry-maven-wagon
            2.2.5
          
        
      
      

      Gli elementi e indicano se il repository memorizza pacchetti di release, pacchetti snapshot o entrambi. Queste impostazioni devono corrispondere alle norme relative alle versioni del repository.

      L'elemento definisce il wagon Artifact Registry come un'estensione. Per informazioni sul wagon, consulta la documentazione degli strumenti Maven di Artifact Registry.

    A distanza o virtuale

    Modifica il file pom.xml nel tuo progetto. Per informazioni dettagliate sulla struttura del file, consulta il riferimento POM di Maven.

    L'esempio seguente mostra le impostazioni per un repository remoto che archivia sia le versioni snapshot che quelle release. In questo esempio, il progetto ha una dipendenza da una versione del pacchetto Guava.

     version="1.0" encoding="UTF-8"?>
     xmlns="http://maven.apache.org/POM/4.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
      4.0.0
    
      com.google.hello
      repo-config
      4.1-SNAPSHOT
      version 1 release
    
      
        1.8
        1.8
      
      
        
          com.google.guava
          guava
          28.0-jre
        
      
    
      
        
          central
          Maven Central remote repository
          artifactregistry://LOCATION-maven.pkg.dev/PROJECT_ID/REMOTE-REPOSITORY-NAME
          default
          
            true
          
          
            true
          
        
      
    
      
        
          
            com.google.cloud.artifactregistry
            artifactregistry-maven-wagon
            2.2.5
          
        
      
    
    
    • La sezione definisce il repository Artifact Registry. Per un repository remoto, l'elemento deve essere impostato su central. Questa impostazione sostituisce il valore predefinito dell'ID repository central ereditato dal Super POM.

    • La sezione imposta il wagon Artifact Registry come estensione. Per informazioni sul wagon, consulta la documentazione degli strumenti Maven di Artifact Registry.

    • In questo esempio, la sezione imposta una dipendenza dalla versione 28.0-jre del pacchetto Guava.

  2. Maven risolve alcune dipendenze prima di applicare un wagon definito in pom.xml, tra cui:

    • Riferimenti in un progetto Maven secondario a un progetto principale utilizzando l'elemento .
    • Dipendenze del plug-in archiviate in Artifact Registry.

    Se il tuo progetto deve risolvere queste dipendenze, devi utilizzare il meccanismo delle estensioni principali per assicurarti che Maven possa individuare i file POM e i plug-in principali.

    Nel tuo progetto, crea il file ${maven.projectBasedir}/.mvn/extensions.xml con il seguente contenuto. L'elemento definisce il vagone.

     xmlns="http://maven.apache.org/EXTENSIONS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://maven.apache.org/EXTENSIONS/1.0.0 http://maven.apache.org/xsd/core-extensions-1.0.0.xsd">
      
        com.google.cloud.artifactregistry
        artifactregistry-maven-wagon
        2.2.5
      
    
    

    Maven ora può risolvere le dipendenze principali o dei plug-in da Artifact Registry.

La configurazione dell'autenticazione è stata completata.

Configura Gradle

  1. Configura Gradle per il tipo di repository che utilizzi.

    Standard

    1. Esegui questo comando per stampare la configurazione del repository da aggiungere al tuo progetto Java.

      gcloud artifacts print-settings gradle \
          --project=PROJECT \
          --repository=REPOSITORY \
          --location=LOCATION
      

      Dove

      • PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.
      • REPOSITORY è l'ID del repository. Se hai configurato un repository predefinito di Artifact Registry, questo viene utilizzato quando questo flag viene omesso dal comando.
      • LOCATION è la posizione regionale o multiregionale del repository.
    2. Aggiungi le impostazioni del repository al file build.gradle. L'esempio seguente mostra la posizione relativa delle sezioni stampate.

      plugins {
        id "maven-publish"
        id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.5"
      }
      
      publishing {
        publications {
          mavenJava(MavenPublication) {
            groupId 'maven.example.id'
            from components.java
           }
        }
        repositories {
          maven {
            url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
          }
        }
      }
      repositories {
        maven {
          url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
        }
      }
      
      • La sezione plugins dichiara il plug-in Artifact Registry. Per informazioni sul plug-in, consulta la documentazione degli strumenti Maven di Artifact Registry.

      • La sezione publishing definisce i file da caricare e il repository Artifact Registry di destinazione. Puoi aggiornare l'elenco dei file nella sezione publications quando è tutto pronto per il caricamento. Per informazioni sulle impostazioni di pubblicazione, consulta la documentazione del plug-in Maven Publish.

    A distanza o virtuale

    Aggiungi le impostazioni del repository al file build.gradle.

    L'esempio seguente mostra le impostazioni per un repository remoto. In questo esempio, il progetto ha una dipendenza da una versione del pacchetto Guava.

    plugins {
      id 'java'
      id "maven-publish"
      id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.5"
      id 'maven'
    }
    
    repositories {
      maven {
        url "artifactregistry://LOCATION-maven.pkg.dev /PROJECT_ID/REMOTE-REPOSITORY-NAME"
      }
    }
    dependencies {
      compile "com.google.guava:guava:31.1-jre"
    }
    
    • La sezione plugins dichiara il plug-in Artifact Registry. Per informazioni sul plug-in, consulta la documentazione degli strumenti Maven di Artifact Registry.

    • La sezione repositories definisce il repository Artifact Registry.

    • In questo esempio, la sezione dependencies imposta una dipendenza dalla versione 31.1-jre del pacchetto Guava.

    Definisci le dipendenze per il pacchetto nella sezione dependencies.

  2. Se devi utilizzare i repository nel file init.gradle o settings.gradle, puoi aggiungere la configurazione del plug-in a questi file.

    Per init.gradle, aggiungi la seguente configurazione:

    initscript {
      repositories {
        maven {
          url "https://plugins.gradle.org/m2/"
        }
      }
      dependencies {
        classpath "gradle.plugin.com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.2.5"
      }
    }
    apply plugin: com.google.cloud.artifactregistry.gradle.plugin.ArtifactRegistryGradlePlugin
    

    Per settings.gradle, aggiungi la seguente configurazione:

    buildscript {
      repositories {
        maven {
          url "https://plugins.gradle.org/m2/"              }
        }
      dependencies {
        classpath "gradle.plugin.com.google.cloud.artifactregistry:artifactregistry-gradle-plugin:2.2.5"
      }
    }
    apply plugin: "com.google.cloud.artifactregistry.gradle-plugin"
    

La configurazione dell'autenticazione è stata completata.

Configurazione dell'autenticazione password

Utilizza questo approccio quando la tua applicazione Java richiede l'autenticazione con un nome utente e una password specifici.

Configurare un account di servizio per l'autenticazione con password

Per creare un account di servizio:

  1. Crea un service account che agisca per conto della tua applicazione oppure scegli un service account esistente che utilizzi per l'automazione.

    Per configurare l'autenticazione con Artifact Registry, devi conoscere la posizione del file della chiave del account di servizio. Per gli account esistenti, puoi visualizzare le chiavi e crearne di nuove nella pagina Account di servizio.

    Vai alla pagina Service account

  2. Se vuoi attivare il account di servizio nella sessione gcloud CLI corrente, esegui il comando:

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

    Dove

    • ACCOUNT è l'utente o il account di servizio.
    • KEY-FILE è il percorso del file della chiave JSON del account di servizio.

Configura Maven

  1. Configura Maven per il tipo di repository che utilizzi.

    Standard

    1. Esegui questo comando per stampare la configurazione del repository da aggiungere al tuo progetto Java.

      gcloud artifacts print-settings mvn \
          --project=PROJECT \
          --repository=REPOSITORY \
          --location=LOCATION \
          --json-key=KEY-FILE
      

      Dove

      • PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto corrente o predefinito.
      • REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, questo viene utilizzato quando questo flag viene omesso dal comando.
      • LOCATION è la posizione regionale o multiregionale del repository.
      • KEY-FILE è il percorso del file della chiave JSON del account di servizio.

    Il comando restituisce le impostazioni da includere nel progetto Java, inclusa una versione con codifica in base64 della chiave privata.

    1. Aggiungi le impostazioni del repository restituite nell'elemento alle sezioni appropriate del file pom.xml per il tuo progetto Maven. Per informazioni dettagliate sulla struttura del file, consulta il riferimento POM di Maven.
    
      
        
          artifact-registry
          https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY
        
        
          artifact-registry
          https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY
        
      
    
      
        
          artifact-registry
          https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY
          
            true
          
          
            true
          
        
      
    
    

    Gli elementi e indicano se il repository memorizza pacchetti di release, pacchetti snapshot o entrambi. Queste impostazioni devono corrispondere alle norme relative alle versioni del repository.

    1. Aggiungi le impostazioni di autenticazione restituite nell'elemento alla sezione del file ~/.m2/settings.xml. Nell'esempio seguente, KEY è la chiave con codifica base64 del file di chiave.

    Per saperne di più, consulta la Guida di riferimento alle impostazioni di Maven.

    
      
        
          artifact-registry
          
            
              
                true
              
              
                true
              
              
                
                  
                    http.protocol.expect-continue
                    false
                  
                
              
            
          
          _json_key_base64
          KEY
        
      
    
    

    A distanza o virtuale

    1. Aggiungi le impostazioni del repository alle sezioni appropriate del file pom.xml per il tuo progetto Maven. Per informazioni dettagliate sulla struttura del file, consulta il riferimento POM di Maven.

      
        
           central
           Maven Central remote repository
           artifactregistry://LOCATION-maven.pkg.dev/PROJECT_ID/REMOTE-REPOSITORY-NAME
           default
           
             true
           
           
            true
          
        
      
      

    La sezione definisce il repository Artifact Registry. Per un repository remoto, l'elemento deve essere impostato su central. Questa impostazione sostituisce il valore predefinito dell'ID repository central ereditato dal Super POM.

    1. Codifica in base64 il file della chiave con il seguente comando. Sostituisci KEY-FILE con il nome del file della chiave.

      base64 -w 0 KEY-FILE
      
    2. Aggiungi le impostazioni di autenticazione nell'elemento alla sezione del file ~/.m2/settings.xml.

    Per saperne di più, consulta la Guida di riferimento alle impostazioni di Maven.

    
      
        
          artifact-registry
          
            
              
                true
              
              
                true
              
              
                
                  
                    http.protocol.expect-continue
                    false
                  
                
              
            
          
          _json_key_base64
          KEY
        
      
    
    
    1. Se utilizzi endpoint HTTP e vuoi utilizzare la connettività nativa di Maven per l'autenticazione, puoi trasmettere un'intestazione di autenticazione utilizzando un'intestazione HTTP personalizzata in settings.xml.

    Esempio:

    
    
      
        artifact-registry
        
          
            
              Authorization 
              Bearer ${artifact.registry.token}
            
          
          
            
              true
            
            
              true
            
            
              
                
                  http.protocol.expect-continue
                  false
                
              
            
          
        
      
    
    
    

La configurazione dell'autenticazione è stata completata.

Configura Gradle

  1. Configura Gradle per il tipo di repository che utilizzi.

    Standard

    1. Esegui questo comando per stampare la configurazione del repository da aggiungere al tuo progetto Java.

      gcloud artifacts print-settings gradle \
          --project=PROJECT \
          --repository=REPOSITORY \
          --location=LOCATION \
          --json-key=KEY-FILE
      

      Dove

      • PROJECT è l'ID progetto.
      • REPOSITORY è l'ID o l'identificatore completo del repository. Se hai configurato un repository Artifact Registry predefinito, questo viene utilizzato quando questo flag viene omesso dal comando.
      • KEY-FILE è il percorso del file della chiave JSON del account di servizio. Se hai eseguito il comando per attivare ilaccount di serviziot, puoi omettere questo flag.

      Il comando restituisce le impostazioni da includere nel progetto Java, inclusa una versione con codifica in base64 della chiave privata.

    2. La seguente riga della configurazione restituita definisce una variabile denominata artifactRegistryMavenSecret per la chiave del account di servizio. Aggiungi questa riga al file ~/.gradle/gradle.properties in modo che la chiave non sia visibile nelle build o nel repository di controllo del codice sorgente.

      artifactRegistryMavenSecret = KEY
      

      In questa riga, KEY è la chiave privata nel file della chiave del account di servizio. Per _json_key_base64, artifactRegistryMavenSecret è impostato sulla chiave codificata in base64 come password.

    3. Nel tuo build.gradle specifica le impostazioni del repository:

      plugins {
        id "maven-publish"
      }
      
      publishing {
        publications {
          mavenJava(MavenPublication) {
            groupId 'maven.example.id'
            from components.java
          }
        }
        repositories {
          maven {
            url "https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
            credentials {
              username = "_json_key_base64"
              password = "$artifactRegistryMavenSecret"
            }
            authentication {
              basic(BasicAuthentication)
            }
          }
        }
      }
      repositories {
        maven {
          url "https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
          credentials {
            username = "_json_key_base64"
            password = "$artifactRegistryMavenSecret"
          }
          authentication {
            basic(BasicAuthentication)
          }
        }
      }
      
      • La sezione repositories imposta l'URL e le credenziali del repository per l'autenticazione.
      • La sezione publishing definisce i file da caricare e il repository Artifact Registry di destinazione. Puoi aggiornare l'elenco dei file nella sezione publications quando è tutto pronto per il caricamento. Per informazioni sulle impostazioni di pubblicazione, consulta la documentazione del plug-in Maven Publish.

    A distanza o virtuale

    1. Codifica in base64 il file della chiave con il seguente comando. Sostituisci KEY-FILE con il nome del file della chiave.

      base64 -w 0 KEY-FILE
      
    2. Nel file ~/.gradle/gradle.properties, aggiungi la seguente riga in modo che la chiave non sia visibile nelle build o nel repository di controllo del codice sorgente.

      artifactRegistryMavenSecret = KEY
      

      In questa riga, KEY è il contenuto del file di chiavi codificato in base64.

    3. Aggiungi le impostazioni del repository al file build.gradle.

    L'esempio seguente mostra la configurazione di un repository remoto.

    plugins {
      id 'java'
      id "maven-publish"
      id 'maven'
    }
    
    repositories {
      maven {
        url "artifactregistry://LOCATION-maven.pkg.dev /PROJECT_ID/REMOTE-REPOSITORY-NAME"
        credentials {
        username = "_json_key_base64"
        password = "$artifactRegistryMavenSecret"
      }
      authentication {
        basic(BasicAuthentication)
      }
      dependencies {
        compile "com.google.guava:guava:31.1-jre"
      }
    
    • La sezione repositories definisce il repository Artifact Registry.

    • In questo esempio, la sezione dependencies imposta una dipendenza dalla versione 31.1-jre del pacchetto Guava.

    Definisci le dipendenze per il pacchetto nella sezione dependencies.

La configurazione dell'autenticazione è stata completata.

Passaggi successivi