Como configurar a autenticação no Maven e no Gradle

Nesta página, descrevemos como configurar o Maven ou o Gradle para autenticação.

É necessário se autenticar no Artifact Registry ao usar um aplicativo de terceiros para se conectar a um repositório.

Você não precisa configurar a autenticação para os ambientes de execução do Cloud Build ou do Google Cloud, como Google Kubernetes Engine e Cloud Run, mas é necessário verificar se as permissões necessárias estão configuradas de dados. Para saber mais, consulte as informações sobre o Cloud Build e a implantação nos ambientes de execução do Google Cloud.

Antes de começar

  1. Se não existir um repositório de destino, crie um novo repositório.
  2. Instale e inicialize o SDK do Cloud..
  3. (Opcional) Configure padrões para comandos gcloud.

Visão geral

O Artifact Registry é compatível com os seguintes métodos de autenticação.

Como usar um auxiliar de autenticação
Essa opção oferece a maior flexibilidade. Quando você inclui o auxiliar na configuração do Maven ou Gradle, o Artifact Registry busca credenciais da conta de serviço no ambiente.
Como especificar uma chave de conta de serviço como uma credencial
Use esta opção quando um aplicativo não for compatível com credenciais de aplicativo padrão, mas for compatível com autenticação com nome de usuário e senha.

As chaves da conta de serviço são credenciais de longa duração. Use as seguintes diretrizes para limitar o acesso aos seus repositórios:

  • Considere usar uma conta de serviço dedicada para interagir com repositórios.
  • Conceda o papel mínimo do Artifact Registry exigido pela conta de serviço. Por exemplo, atribua o leitor do Artifact Registry a uma conta de serviço que faz o download apenas de artefatos.
  • Se os grupos na sua organização exigirem níveis diferentes de acesso a repositórios específicos, conceda acesso no nível do repositório em vez de no nível do projeto.
  • Siga as práticas recomendadas para gerenciar as credenciais.

Como autenticar com um auxiliar de credenciais

O Artifact Registry oferece um wagon Maven e um plug-in Gradle como auxiliares de credencial. Quando você usa o auxiliar de credenciais, elas não são armazenadas no projeto Java. Em vez disso, o Artifact Registry procura credenciais na seguinte ordem:

  1. Application Default Credentials (ADC), uma estratégia que procura credenciais na seguinte ordem:

    1. Credenciais definidas na variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

    2. Credenciais que a conta de serviço padrão do Compute Engine, do Google Kubernetes Engine, do Cloud Run, do App Engine ou do Cloud Functions fornece.

  2. Credenciais fornecidas pelo SDK do Cloud, incluindo credenciais de usuário do comando gcloud auth application-default login.

A variável GOOGLE_APPLICATION_CREDENTIALS torna a conta explícita para a autenticação, o que facilita a solução de problemas. Se ela não for usada, verifique se as contas usadas pelo ADC têm as permissões necessárias. Por exemplo, a conta de serviço padrão para VMs do Compute Engine, nós do Google Kubernetes Engine e revisões do Cloud Run tem acesso somente leitura a repositórios. Se você pretende fazer o upload desses ambientes usando a conta de serviço padrão, modifique as permissões.

Para criar uma conta de serviço e configurar a autenticação usando a variável de ambiente:

  1. Crie uma conta de serviço para agir em nome do seu aplicativo ou escolha uma conta de serviço atual que você usa para automação.

    Você precisará do local do arquivo de chave da conta de serviço para configurar a autenticação com o Artifact Registry. Para contas existentes, é possível ver as chaves e criar novas chaves na página "Contas de serviço".

    Acessar a página "Contas de serviço"

  2. Conceda o papel apropriado do Artifact Registry à conta de serviço para fornecer acesso ao repositório.

  3. Atribua o local do arquivo de chave da conta de serviço à variável GOOGLE_APPLICATION_CREDENTIALS para que o auxiliar de credenciais do Artifact Registry possa conseguir sua chave ao se conectar com os repositórios.

    export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
    

    Em que KEY-FILE é o caminho para o arquivo de chave da conta de serviço.

  4. Verifique a política de versões do repositório Maven.

    Console

    1. Abra a página Repositórios no Console do Cloud.

    Abrir a página Repositórios

    1. Clique no repositório em que você quer se autenticar.

    A seção Detalhes exibe a política da versão. Se o repositório tiver uma política de versão de snapshot, o campo Permitir substituições de snapshots indicará se eles podem substituir versões de snapshots correspondentes no repositório.

    gcloud

    Execute o comando a seguir para ver a descrição de um repositório.

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

    Onde

    • REPOSITORY é o ID do repositório. Se você tiver configurado um repositório do Artifact Registry padrão, ele será usado quando essa sinalização for omitida no comando.
    • PROJECT é o ID do projeto. Se essa sinalização for omitida, o projeto padrão ou atual é usado.
    • LOCATION é o local regional ou multirregional do repositório.

    A saída do comando inclui informações sobre a política de versão em mavenConfig. Neste exemplo, o repositório tem uma política de versão de snapshot, e os snapshots não podem substituir versões idênticas no repositório.

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

    Se um repositório não tiver uma política de versão, o valor de mavenConfig será {}.

  5. Execute o comando a seguir para imprimir a configuração do repositório para adicioná-la ao seu projeto Java.

    Maven

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

    Onde

    • PROJECT é o ID do projeto. Se essa sinalização for omitida, o projeto padrão ou atual é usado.
    • REPOSITORY é o ID do repositório. Se você tiver configurado um repositório do Artifact Registry padrão, ele será usado quando essa sinalização for omitida no comando.
    • LOCATION é o local regional ou multirregional do repositório.

    Gradle

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

    Onde

    • PROJECT é o ID do projeto.
    • REPOSITORY é o ID ou o identificador totalmente qualificado para o repositório. Se você tiver configurado um repositório padrão do Artifact Registry, ele será usado quando essa sinalização for omitida no comando.
  6. Configure o projeto Java.

    Maven

    1. Adicione as configurações retornadas às seções apropriadas no arquivo pom.xml do projeto do Maven. Consulte a referência do POM do Maven para ver detalhes sobre a estrutura do arquivo.

      O exemplo a seguir é para um repositório que armazena versões de snapshot e de lançamento.

      <distributionManagement>
        <snapshotRepository>
          <id>artifact-registry</id>
          <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
        </snapshotRepository>
        <repository>
          <id>artifact-registry</id>
          <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
        </repository>
      </distributionManagement>
      
      <repositories>
        <repository>
          <id>artifact-registry</id>
          <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
      
      <build>
        <extensions>
          <extension>
            <groupId>com.google.cloud.artifactregistry</groupId>
            <artifactId>artifactregistry-maven-wagon</artifactId>
            <version>2.1.4</version>
          </extension>
        </extensions>
      </build>
      

      A seção <build> declara o compilador do Artifact Registry como uma extensão. Para saber mais sobre o compilador, consulte a documentação das ferramentas Maven do Artifact Registry.

    2. O Maven resolve algumas dependências antes de aplicar um vagão definido em pom.xml, incluindo:

    • Referências em um projeto filho do Maven a um projeto pai usando o elemento <parent>.
    • As dependências de plug-in armazenadas no Artifact Registry.

    Caso seu projeto precise resolver essas dependências, use o mecanismo das extensões principais para garantir que o Maven possa localizar plug-ins e arquivos POM pai.

    No seu projeto, crie o arquivo ${maven.projectBasedir}/.mvn/extensions.xml com o seguinte conteúdo. O elemento <extension> define o vagão.

     <extensions 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">
       <extension>
         <groupId>com.google.cloud.artifactregistry</groupId>
         <artifactId>artifactregistry-maven-wagon</artifactId>
         <version>2.1.4</version>
       </extension>
     </extensions>
    

    Agora, o Maven pode resolver dependências pai ou de plug-in do Artifact Registry.

    Gradle

    1. Adicione as configurações do repositório ao arquivo build.gradle. Veja a seguir o local relativo das seções impressas.

      Esse exemplo é de um repositório que armazena versões de snapshot e de lançamento.

      plugins {
        id "maven-publish"
        id "com.google.cloud.artifactregistry.gradle-plugin" version "2.1.4"
      }
      
      publishing {
        publications {
          mavenJava(MavenPublication) {
            groupId 'maven.example.id'
            from components.java
           }
        }
        repositories {
          maven {
            url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
          }
        }
      }
      
      • A seção plugins declara o plug-in do Artifact Registry. Para saber mais sobre o plug-in, consulte a documentação das ferramentas do Maven do Artifact Registry.

      • A seção publishing declara os arquivos a serem enviados e o repositório do Artifact Registry de destino. É possível atualizar a lista de arquivos na seção publications quando estiver pronto para fazer upload. Para ver informações sobre configurações de publicação, consulte a documentação do plug-in do Maven Publish.

    2. Se sua versão incluir alguma dependência, certifique-se de declará-la na sua versão.

    3. Se você precisar usar repositórios no arquivo init.gradle ou settings.gradle, poderá adicionar a configuração do plug-in a esses arquivos.

      Para init.gradle, adicione a seguinte configuração:

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

      Para o settings.gradle, adicione a seguinte configuração:

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

Como configurar a autenticação por senha

Use essa abordagem quando o aplicativo Java exigir autenticação com um nome de usuário e uma senha especificados.

Para criar uma conta de serviço e configurar a autenticação:

  1. Crie uma conta de serviço para agir em nome do seu aplicativo ou escolha uma conta de serviço atual que você usa para automação de CI/CD.

  2. Conceda o papel apropriado do Artifact Registry à conta de serviço para fornecer acesso ao repositório.

  3. Verifique a política de versões do repositório Maven.

    1. Abra a página Repositórios no Console do Cloud.

      Abrir a página Repositórios

    2. Clique no repositório em que você quer se autenticar.

      A seção Detalhes exibe a política da versão. Se o repositório tiver uma política de versão de snapshot, o campo Permitir substituições de snapshots indicará se eles podem substituir versões de snapshots correspondentes no repositório.

  4. Se você quiser ativar a conta de serviço na sessão atual do SDK do Cloud, execute o comando:

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

    Onde

    • ACCOUNT é a conta de usuário ou de serviço.
    • KEY-FILE é o caminho para o arquivo de chaves JSON da conta de serviço.
  5. Execute o comando a seguir para imprimir a configuração do repositório para adicioná-la ao seu projeto Java.

    Maven

    gcloud artifacts print-settings mvn \
        [--project=PROJECT] \
        [--repository=REPOSITORY] \
        [--location=LOCATION] \
        --json-key=KEY-FILE \
        [--version-policy=VERSION-POLICY] \
        [--allow-snapshot-overwrites]
    

    Onde

    • PROJECT é o ID do projeto. Se essa sinalização for omitida, o projeto padrão ou atual é usado.
    • REPOSITORY é o ID do repositório. Se você tiver configurado um repositório do Artifact Registry padrão, ele será usado quando essa sinalização for omitida no comando.
    • LOCATION é o local regional ou multirregional do repositório.
    • KEY-FILE é o caminho para o arquivo de chaves JSON da conta de serviço.
    • VERSION-POLICY A política de versão do repositório.

      • None: nenhuma política de versão. O repositório armazena pacotes de snapshot e de lançamento.
      • Release: o repositório tem uma política de versão de lançamento.
      • Snapshot: o repositório tem uma política de versão do snapshot.
    • --allow-snapshot-overwrites indica que o repositório é compatível com a substituição de versões de snapshots atuais.

    Gradle

    gcloud artifacts print-settings gradle \
        [--project=PROJECT] \
        [--repository=REPOSITORY] \
        [--location=LOCATION] \
        --json-key=KEY-FILE \
        [--version-policy=VERSION-POLICY] \
        [--allow-snapshot-overwrites]
    

    Onde

    • PROJECT é o ID do projeto.
    • REPOSITORY é o ID ou o identificador totalmente qualificado para o repositório. Se você tiver configurado um repositório padrão do Artifact Registry, ele será usado quando essa sinalização for omitida no comando.
    • KEY-FILE é o caminho para o arquivo de chaves JSON da conta de serviço. Se você executou o comando para ativar a conta de serviço, omita essa sinalização.
    • VERSION-POLICY A política de versão do repositório.

      • None: nenhuma política de versão. O repositório armazena pacotes de snapshot e de lançamento.
      • Release: o repositório tem uma política de versão de lançamento.
      • Snapshot: o repositório tem uma política de versão do snapshot.
    • --allow-snapshot-overwrites indica que o repositório é compatível com a substituição de versões de snapshots atuais.

  6. Configure o projeto Java com as configurações retornadas pelo comando.

    Maven

    1. Adicione as configurações retornadas do repositório no elemento <project> às seções apropriadas do arquivo pom.xml para seu projeto do Maven. Consulte a referência do POM do Maven para ver detalhes sobre a estrutura do arquivo.
    <project>
      <distributionManagement>
        <snapshotRepository>
          <id>artifact-registry</id>
          <url>https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
        </snapshotRepository>
        <repository>
          <id>artifact-registry</id>
          <url>https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
        </repository>
      </distributionManagement>
    
      <repositories>
        <repository>
          <id>artifact-registry</id>
          <url>https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
    </project>
    
    1. Adicione as configurações de autenticação retornadas no elemento <settings> à seção <servers> do arquivo ~/.m2/settings.xml. No exemplo a seguir, KEY é a chave privada no arquivo da chave da conta de serviço.

    Consulte a referência de configurações do Maven para mais informações.

    <settings>
      <servers>
        <server>
          <id>artifact-registry</id>
          <configuration>
            <httpConfiguration>
              <get>
                <usePreemptive>true</usePreemptive>
              </get>
              <head>
                <usePreemptive>true</usePreemptive>
              </head>
              <put>
                <params>
                  <property>
                    <name>http.protocol.expect-continue</name>
                    <value>false</value>
                  </property>
                </params>
              </put>
            </httpConfiguration>
          </configuration>
          <username>_json_key_base64</username>
          <password>KEY</password>
        </server>
      </servers>
    </settings>
    

    Gradle

    1. A linha a seguir da configuração retornada define uma variável chamada artifactRegistryMavenSecret para a chave da conta de serviço. Adicione esta linha ao arquivo ~/.gradle/gradle.properties para que a chave não fique visível nas versões ou no repositório de controle de origem.

      artifactRegistryMavenSecret = KEY
      

      Nesta linha, KEY é a chave privada no arquivo da chave da conta de serviço. Para _json_key_base64, o artifactRegistry MavenSecret contém a senha criptografada em Base64. Por exemplo, base64 -w 0 KEY.

    2. Em build.gradle, especifique as configurações do repositório:

      plugins {
        id "maven-publish"
      }
      
      publishing {
        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)
          }
        }
      }
      

    A configuração de autenticação foi concluída. Antes de publicar arquivos, verifique se os arquivos para upload estão definidos em uma seção publications em publishing. Exemplo:

    publishing {
    publications {
         mavenJava(MavenPublication) {
            groupId 'maven.example.id'
            from components.java
         }
    }
    repositories {
    ...
    }
    }
    

    Para informações sobre configurações de publicação, consulte a documentação do [plug-in do Maven Publish][maven-publish-plugin]{:class="external"}.

A seguir