Configura la autenticación para Maven y Gradle

En esta página, se describe cómo configurar Maven o Gradle para la autenticación.

Debes autenticarte en Artifact Registry cuando uses una aplicación de terceros para conectarte a un repositorio.

No es necesario que configures la autenticación para los entornos de ejecución de Cloud Build o Google Cloud, como Google Kubernetes Engine y Cloud Run, pero debes verificar que estén configurados los permisos necesarios. , Para obtener más información, consulta la información sobre Cloud Build y la implementación en entornos de ejecución de Google Cloud.

Antes de comenzar

  1. Si el repositorio de destino no existe, crea un repositorio nuevo.
  2. Instala e inicializa el SDK de Cloud.
  3. (Opcional) Configura valores predeterminados para los comandos de gcloud.

Descripción general

Artifact Registry admite los siguientes métodos de autenticación.

Usa un asistente de autenticación
Esta opción proporciona la mayor flexibilidad. Cuando incluyes el asistente en tu configuración de Maven o Gradle, Artifact Registry busca credenciales de la cuenta de servicio en el entorno.
Especifica una clave de cuenta de servicio como una credencial
Usa esta opción cuando una aplicación no sea compatible con las credenciales predeterminadas de la aplicación, pero admita la autenticación mediante un nombre de usuario y una contraseña.

Las claves de la cuenta de servicio son credenciales de larga duración. Usa los siguientes lineamientos para limitar el acceso a tus repositorios:

  • Considera usar una cuenta de servicio dedicada para interactuar con los repositorios.
  • Otorga la función mínima de Artifact Registry que requiera la cuenta de servicio. Por ejemplo, asigna la función de lector de Artifact Registry a una cuenta de servicio que solo descargue artefactos.
  • Si los grupos de tu organización requieren diferentes niveles de acceso a repositorios específicos, otorga acceso a nivel de repositorio en lugar de a nivel de proyecto.
  • Sigue las prácticas recomendadas para administrar credenciales.

Autentica con un auxiliar de credenciales

Artifact Registry proporciona un vagón de Maven y un complemento de Gradle como asistentes de credenciales. Cuando uses el auxiliar de credenciales, las credenciales no se almacenarán en tu proyecto de Java. En su lugar, Artifact Registry busca las credenciales en el siguiente orden:

  1. Las credenciales predeterminadas de la aplicación (ADC), que es una estrategia que busca credenciales en el siguiente orden:

    1. Credenciales definidas en la variable de entorno GOOGLE_APPLICATION_CREDENTIALS

    2. Credenciales que proporciona la cuenta de servicio predeterminada para Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine o Cloud Functions

  2. Credenciales que proporciona el SDK de Cloud, incluidas las credenciales de usuario del comando gcloud auth application-default login

La variable GOOGLE_APPLICATION_CREDENTIALS hace que la autenticación sea explícita, lo que facilita la solución de problemas. Si no usas la variable, verifica que todas las cuentas que ADC pueda usar tengan los permisos necesarios. Por ejemplo, la cuenta de servicio predeterminada para las VM de Compute Engine, los nodos de Google Kubernetes Engine y las revisiones de Cloud Run tiene acceso de solo lectura a los repositorios. Si planeas subir desde estos entornos con la cuenta de servicio predeterminada, debes modificar los permisos.

Para crear una cuenta de servicio y configurar la autenticación mediante la variable de entorno, haz lo siguiente:

  1. Crea una cuenta de servicio que actúe en nombre de tu aplicación o elige una cuenta de servicio existente que uses para la automatización.

    Necesitarás la ubicación del archivo de claves de la cuenta de servicio para configurar la autenticación con Artifact Registry. En las cuentas existentes, puedes ver claves y crear claves nuevas en la página Cuentas de servicio.

    Ir a la página Cuentas de servicio

  2. Otorga la función adecuada de Artifact Registry a la cuenta de servicio para proporcionar acceso al repositorio.

  3. Asigna la ubicación del archivo de claves de la cuenta de servicio a la variable GOOGLE_APPLICATION_CREDENTIALS para que el auxiliar de credenciales de Artifact Registry pueda obtener tu clave cuando se conecta con repositorios.

    export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
    

    En el ejemplo anterior, KEY-FILE es la ruta de acceso al archivo de claves de la cuenta de servicio.

  4. Verifica la política de versión del repositorio de Maven.

    Console

    1. Abre la página Repositorios en Cloud Console.

    Abrir la página Repositorios

    1. Haz clic en el repositorio en el que deseas realizar la autenticación.

    En la sección Detalles (Details), se muestra la política de la versión. Si el repositorio tiene una política de versiones de instantáneas, el campo Permitir reemplazo de instantáneas indica si las instantáneas pueden reemplazar las versiones de instantáneas coincidentes en el repositorio.

    gcloud

    Ejecuta el siguiente comando para ver una descripción de un repositorio.

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

    Donde

    • REPOSITORY es el ID del repositorio. Si configuraste un repositorio predeterminado de Artifact Registry, se usa cuando se omite esta marca del comando.
    • PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.
    • LOCATION es la ubicación regional o multirregional del repositorio.

    En el resultado del comando, se incluye información sobre la política de la versión en mavenConfig. En este ejemplo, el repositorio tiene una política de versión de la instantánea, y las instantáneas no pueden reemplazar las versiones idénticas en el repositorio.

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

    Si un repositorio no tiene una política de versiones, el valor de mavenConfig es {}.

  5. Ejecuta el siguiente comando para imprimir la configuración del repositorio que deseas agregar a tu proyecto de Java.

    Maven

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

    Donde

    • PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.
    • REPOSITORY es el ID del repositorio. Si configuraste un repositorio predeterminado de Artifact Registry, se usa cuando se omite esta marca del comando.
    • LOCATION es la ubicación regional o multirregional del repositorio.

    Gradle

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

    Donde

    • PROJECT es el ID del proyecto.
    • REPOSITORY es el ID o el identificador completamente calificado del repositorio. Si configuraste un repositorio predeterminado de Artifact Registry, se usa cuando se omite esta marca del comando.
  6. Configura tu proyecto de Java.

    Maven

    1. Agrega la configuración que se muestra a las secciones correspondientes del archivo pom.xml en tu proyecto de Maven. Consulta la referencia del gerente de Operaciones con Socios de Maven para obtener detalles sobre la estructura del archivo.

      El siguiente ejemplo es para un repositorio que almacena versiones de instantáneas y de lanzamientos.

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

      En la sección <build>, se declara la alternativa de Artifact Registry como una extensión. Para obtener información sobre esta alternativa, consulta la documentación de las herramientas de Maven de Artifact Registry.

    2. Maven resuelve algunas dependencias antes de aplicar un vagón definido en pom.xml, incluido lo siguiente:

    • Referencias en un proyecto secundario de Maven a un proyecto superior mediante el elemento <parent>
    • Dependencias de complementos almacenadas en Artifact Registry.

    Si tu proyecto necesita resolver estas dependencias, debes usar el mecanismo de extensiones principales para asegurarte de que Maven pueda encontrar archivos y complementos POM superiores.

    En tu proyecto, crea el archivo ${maven.projectBasedir}/.mvn/extensions.xml con el siguiente contenido. El elemento <extension> define la vagón.

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

    Maven ahora puede resolver dependencias superiores o de complementos desde Artifact Registry.

    Gradle

    1. Agrega la configuración del repositorio a tu archivo build.gradle. En el siguiente ejemplo, se muestra la ubicación relativa de las secciones impresas.

      Este ejemplo es para un repositorio que almacena versiones de instantáneas y de lanzamientos.

      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"
          }
        }
      }
      
      • En la sección plugins, se declara el complemento de Artifact Registry. Para obtener información sobre el complemento, consulta la documentación de las herramientas de Maven de Artifact Registry.

      • En la sección publishing, se declaran los archivos que se subirán y el repositorio de destino de Artifact Registry. Puedes actualizar la lista de archivos en la sección publications cuando estés listo para realizar cargas. Para obtener información sobre la configuración de publicación, consulta la documentación del complemento de publicación de Maven.

    2. Si tu compilación incluye dependencias, asegúrate de declararlas en la compilación.

    3. Si necesitas usar repositorios en tu archivo init.gradle o settings.gradle, puedes agregar la configuración del complemento a esos archivos.

      Para init.gradle, agrega la siguiente configuración:

      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 settings.gradle, agrega la siguiente configuración:

      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"
      

Configura la autenticación con contraseña

Usa este enfoque cuando la aplicación de Java requiera la autenticación con un nombre de usuario y una contraseña especificados.

Para crear una cuenta de servicio y configurar la autenticación, haz lo siguiente:

  1. Crea una cuenta de servicio que actúe en nombre de tu aplicación o elige una cuenta de servicio existente que uses para la automatización de CI/CD.

  2. Otorga la función adecuada de Artifact Registry a la cuenta de servicio para proporcionar acceso al repositorio.

  3. Verifica la política de versión del repositorio de Maven.

    1. Abre la página Repositorios en Cloud Console.

      Abrir la página Repositorios

    2. Haz clic en el repositorio en el que deseas realizar la autenticación.

      En la sección Detalles (Details), se muestra la política de la versión. Si el repositorio tiene una política de versiones de instantáneas, el campo Permitir reemplazo de instantáneas indica si las instantáneas pueden reemplazar las versiones de instantáneas coincidentes en el repositorio.

  4. Si deseas activar la cuenta de servicio en la sesión del SDK de Cloud actual, ejecuta el siguiente comando:

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

    Donde

    • ACCOUNT es la cuenta de usuario o servicio.
    • KEY-FILE es la ruta al archivo de claves JSON de la cuenta de servicio.
  5. Ejecuta el siguiente comando para imprimir la configuración del repositorio que deseas agregar a tu proyecto de Java.

    Maven

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

    Donde

    • PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto predeterminado o actual.
    • REPOSITORY es el ID del repositorio. Si configuraste un repositorio predeterminado de Artifact Registry, se usa cuando se omite esta marca del comando.
    • LOCATION es la ubicación regional o multirregional del repositorio.
    • KEY-FILE es la ruta al archivo de claves JSON de la cuenta de servicio.
    • VERSION-POLICY: Es la política de la versión del repositorio.

      • None: No hay política de versión. El repositorio almacena paquetes de instantáneas y de actualizaciones.
      • Release: El repositorio tiene una política de versión de actualización.
      • Snapshot: El repositorio tiene una política de versión de instantánea.
    • --allow-snapshot-overwrites indica que el repositorio admite la sobrescritura de versiones de instantáneas existentes.

    Gradle

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

    Donde

    • PROJECT es el ID del proyecto.
    • REPOSITORY es el ID o el identificador completamente calificado del repositorio. Si configuraste un repositorio predeterminado de Artifact Registry, se usa cuando se omite esta marca del comando.
    • KEY-FILE es la ruta al archivo de claves JSON de la cuenta de servicio. Si ejecutaste el comando para activar tu cuenta de servicio, puedes omitir esta marca.
    • VERSION-POLICY: Es la política de la versión del repositorio.

      • None: No hay política de versión. El repositorio almacena paquetes de instantáneas y de actualizaciones.
      • Release: El repositorio tiene una política de versión de actualización.
      • Snapshot: El repositorio tiene una política de versión de instantánea.
    • --allow-snapshot-overwrites indica que el repositorio admite la sobrescritura de versiones de instantáneas existentes.

  6. Configura tu proyecto de Java con la configuración que muestra el comando.

    Maven

    1. Agrega la configuración del repositorio que se muestra en el elemento <project> a las secciones correspondientes del archivo pom.xml en tu proyecto de Maven. Consulta la referencia del gerente de Operaciones con Socios de Maven para obtener detalles sobre la estructura del archivo.
    <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. Agrega la configuración de autenticación que se muestra en el elemento <settings> a la sección <servers> del archivo ~/.m2/settings.xml. En el siguiente ejemplo, KEY es la clave privada en el archivo de claves de la cuenta de servicio de servicio.

    Consulta la referencia de configuración de Maven para obtener más información.

    <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. En la siguiente línea de configuración que se muestra, se define una variable llamada artifactRegistryMavenSecret para la clave de tu cuenta de servicio. Agrega esta línea a tu archivo ~/.gradle/gradle.properties para que la clave no sea visible en tus compilaciones ni en tu repositorio de control de origen.

      artifactRegistryMavenSecret = KEY
      

      En esta línea, KEY es la clave privada en el archivo de claves de la cuenta de servicio de servicio. Para _json_key_base64, el artifactRegistryMavenSecret contiene la contraseña encriptada en base64. Por ejemplo, base64 -w 0 KEY.

    2. En tu build.gradle, especifica la configuración del repositorio:

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

    Se completó la configuración de autenticación. Antes de publicar archivos, asegúrate de que los archivos que deseas subir estén definidos en una sección publications en publishing. Por ejemplo:

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

    Para obtener información sobre la configuración de publicación, consulta la documentación de [complemento de Maven Publish][maven-publish-plugin]{:class="external"}.

¿Qué sigue?