Configurar a autenticação do Artifact Registry para Maven e Gradle

Faça a autenticação no Artifact Registry ao usar um aplicativo de terceiros para se conectar a um repositório do Artifact Registry. Esta documentação se concentra na configuração do Maven e do Gradle.

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

Antes de começar

  1. Instale a Google Cloud CLI e inicialize-a executando o seguinte comando: 

    gcloud init
  2. (Opcional) Configure padrões para comandos gcloud.

  3. Se você estiver configurando a autenticação com um repositório padrão, verifique a política de versão para configurar o projeto Maven corretamente para os tipos de pacotes Java que podem ser enviados por upload.

    Console

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

      Abrir a página Repositórios

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

      A seção Detalhes mostra a política de versão. Se o repositório tiver uma política de versão de snapshot, o campo Permitir substituições de snapshot vai indicar se os snapshots podem substituir as versões 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

    Por

    • 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á {}.

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 essa opção quando um aplicativo não for compatível com o Application Default Credentials, mas aceitar a autenticação com um nome de usuário e uma 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 fornece um wagon do Maven e um plug-in do Gradle (links em inglês) como auxiliares de credenciais. Quando você usa o auxiliar de credenciais, suas credenciais 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 pela Google Cloud CLI, incluindo credenciais de usuário do comando gcloud auth application-default login.

A variável GOOGLE_APPLICATION_CREDENTIALS torna a autenticação da conta explícita, o que facilita a solução de problemas. Se você não usar a variável, verifique se alguma conta que o ADC pode usar tem 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 aos repositórios. Se você pretende fazer o upload a partir desses ambientes usando a conta de serviço padrão, modifique as permissões.

Configurar uma conta de serviço para um auxiliar de credenciais

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

    Acesse a página Contas de serviço

  2. Conceda o papel específico 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.

Configure o Maven

  1. Configure o Maven de acordo com o tipo de repositório que você está usando.

    Standard

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

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

      Por

      • 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 padrão do Artifact Registry, ele será usado quando essa sinalização for omitida do comando.
      • LOCATION é o local regional ou multirregional do repositório.

    2. 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 mostra as configurações de 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.2.1</version>
    </extension>
  </extensions>
</build>

      Os elementos <release> e <snapshot> indicam se o repositório armazena pacotes de lançamento, pacotes de snapshot ou ambos. Essas configurações precisam corresponder à política de versão do repositório.

      O elemento <build> define o vagão do Artifact Registry como uma extensão. Para informações sobre o vagão, consulte a documentação das ferramentas do Maven do Artifact Registry.

    Remoto ou virtual

    Edite o arquivo pom.xml no projeto. Consulte a referência do POM do Maven para ver detalhes sobre a estrutura do arquivo.

    O exemplo a seguir mostra as configurações de um repositório remoto que armazena versões de snapshot e de lançamento. Neste exemplo, o projeto tem uma dependência de uma versão do pacote Guava.

    <?xml version="1.0" encoding="UTF-8"?>
<project 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">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.google.hello</groupId>
  <artifactId>repo-config</artifactId>
  <version>4.1-SNAPSHOT</version>
  <description>version 1 release</description>

  <properties>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
  </properties>
  <dependencies>
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>28.0-jre</version>
    </dependency>
  </dependencies>

  <repositories>
    <repository>
      <id>central</id>
      <name>Maven Central remote repository</name>
      <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT_ID/REMOTE-REPOSITORY-NAME</url>
      <layout>default</layout>
      <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.2.1</version>
      </extension>
    </extensions>
  </build>
</project>

    • A seção <repositories> define o repositório do Artifact Registry. Para um repositório remoto, o elemento <id> precisa ser definido como central. Essa configuração substitui o valor padrão do ID do repositório central, herdado do Super POM.

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

    • Neste exemplo, a seção <dependencies> define uma dependência na versão 28.0-jre do pacote Guava.

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

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

    Se o projeto precisar resolver essas dependências, use o mecanismo de extensões principais para garantir que o Maven possa localizar arquivos POM e plug-ins pais.

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

    <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.2.1</version>
  </extension>
</extensions>

    O Maven agora pode resolver dependências pai ou de plug-in do Artifact Registry.

A configuração de autenticação foi concluída.

Configurar o Gradle

  1. Configure o Gradle de acordo com o tipo de repositório que você está usando.

    Standard

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

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

      Por

      • 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 padrão do Artifact Registry, ele será usado quando essa sinalização for omitida do comando.
      • LOCATION é o local regional ou multirregional do repositório.

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

      plugins {
  id "maven-publish"
  id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.1"
}

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"
  }
}

      • 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 define os arquivos para upload e o repositório de destino do Artifact Registry. É 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.

    Remoto ou virtual

    Adicione as configurações do repositório ao arquivo build.gradle.

    O exemplo a seguir mostra as configurações de um repositório remoto. Neste exemplo, o projeto tem uma dependência em uma versão do pacote Guava.

    plugins {
  id 'java'
  id "maven-publish"
  id "com.google.cloud.artifactregistry.gradle-plugin" version "2.2.1"
  id 'maven'
}

repositories {
  maven {
    url "artifactregistry://LOCATION-maven.pkg.dev /PROJECT_ID/REMOTE-REPOSITORY-NAME"
  }
}
dependencies {
  compile "com.google.guava:guava:31.1-jre"
}

    • 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 repositories define o repositório do Artifact Registry.

    • Neste exemplo, a seção dependencies define uma dependência na versão 31.1-jre do pacote Guava.

    Defina as dependências do pacote na seção dependencies.

  2. 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.2.1"
  }
}
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.2.1"
  }
}
apply plugin: "com.google.cloud.artifactregistry.gradle-plugin"

A configuração de autenticação foi concluída.

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.

Configurar uma conta de serviço para autenticação por senha

Para criar uma conta de serviç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.

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

    Acesse a página Contas de serviço

  2. Se você quiser ativar a conta de serviço na sessão atual da CLI gcloud, execute o comando:

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

    Por

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

Configure o Maven

  1. Configure o Maven de acordo com o tipo de repositório que você está usando.

    Standard

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

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

      Por

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

    O comando retorna configurações a serem incluídas no projeto Java, incluindo uma versão codificada em base64 da sua chave privada.

    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>

    Os elementos <release> e <snapshot> indicam se o repositório armazena pacotes de lançamento, pacotes de snapshot ou ambos. Essas configurações precisam corresponder à política de versão do repositório.

    1. Adicione as configurações de autenticação retornadas no elemento <settings> à seção <servers> do arquivo ~/.m2/settings.xml. No exemplo abaixo, KEY é a chave codificada em base64 do seu arquivo de chave.

    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>

    Remoto ou virtual

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

      <repositories>
  <repository>
     <id>central</id>
     <name>Maven Central remote repository</name>
     <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT_ID/REMOTE-REPOSITORY-NAME</url>
     <layout>default</layout>
     <releases>
       <enabled>true</enabled>
     </releases>
     <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

    A seção <repositories> define o repositório do Artifact Registry. Para um repositório remoto, o elemento <id> precisa ser definido como central. Essa configuração substitui o valor padrão do ID do repositório central, herdado do Super POM.

    1. Codifique o arquivo de chave em Base64 com o seguinte comando. Substitua KEY-FILE pelo nome do arquivo de chave.

      base64 -w 0 KEY-FILE

    2. Adicione configurações de autenticação no elemento <settings> à seção <servers> do arquivo ~/.m2/settings.xml.

    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>

A configuração de autenticação foi concluída.

Configurar o Gradle

  1. Configure o Gradle de acordo com o tipo de repositório que você está usando.

    Standard

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

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

      Por

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

      O comando retorna configurações a serem incluídas no projeto Java, incluindo uma versão codificada em base64 da sua chave privada.

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

      Nessa linha, KEY é a chave privada no arquivo de chave da conta de serviço. Para _json_key_base64, artifactRegistryMavenSecret é definido como a chave codificada em base64 como sua senha.

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

      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)
    }
  }
}
      • A seção repositories define o URL e as credenciais do repositório para autenticação.
      • A seção publishing define os arquivos para upload e o repositório de destino do Artifact Registry. É 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.

    Remoto ou virtual

    1. Codifique o arquivo de chave em Base64 com o seguinte comando. Substitua KEY-FILE pelo nome do arquivo de chave.

      base64 -w 0 KEY-FILE

    2. No arquivo ~/.gradle/gradle.properties, adicione a linha a seguir para que a chave não fique visível nos builds ou no repositório de controle de origem.

      artifactRegistryMavenSecret = KEY

      Nesta linha, KEY é o conteúdo do arquivo de chave codificado em base64.

    3. Adicione as configurações do repositório ao arquivo build.gradle.

    O exemplo a seguir mostra a configuração de um repositório 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"
  }

    • A seção repositories define o repositório do Artifact Registry.

    • Neste exemplo, a seção dependencies define uma dependência na versão 31.1-jre do pacote Guava.

    Defina as dependências do pacote na seção dependencies.

A configuração de autenticação foi concluída.

A seguir