Setting up authentication for Maven and Gradle

This page describes how to configure Maven or Gradle for authentication.

You must authenticate to Artifact Registry when you use a third-party application to connect to a repository.

You do not need to configure authentication for Cloud Build or Google Cloud runtime environments such as Google Kubernetes Engine and Cloud Run, but you should verify that the required permissions are configured. To learn more, see the information about Cloud Build and deploying to Google Cloud runtime environments.

Before you begin

  1. If the target repository does not exist, create a new repository.
  2. Install and initialize the Cloud SDK.
  3. (Optional) Configure defaults for gcloud commands.

Overview

Artifact Registry supports the following authentication methods.

Using an authentication helper
This option provides the most flexibility. When you include the helper in your Maven or Gradle configuration, Artifact Registry searches for service account credentials in the environment.
Specifying a service account key as a credential
Use this option when an application does not support Application Default Credentials but does support authentication with a username and password.

Service account keys are long-lived credentials. Use the following guidelines to limit access to your repositories:

  • Consider using a dedicated service account for interacting with repositories.
  • Grant the minimum Artifact Registry role required by the service account. For example, assign Artifact Registry Reader to a service account that only downloads artifacts.
  • If groups in your organization require different levels of access to specific repositories, grant access at the repository level rather than the project level.
  • Follow best practices for managing credentials.

Authenticating with a credential helper

Artifact Registry provides a Maven wagon and a Gradle plugin as credential helpers. When you use the credential helper, your credentials are not stored in your Java project. Instead, Artifact Registry searches for credentials in the following order:

  1. Application Default Credentials (ADC), a strategy that looks for credentials in the following order:

    1. Credentials defined in the GOOGLE_APPLICATION_CREDENTIALS environment variable.

    2. Credentials that the default service account for Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine, or Cloud Functions provides.

  2. Credentials provided by the Cloud SDK, including user credentials from the command gcloud auth application-default login.

The GOOGLE_APPLICATION_CREDENTIALS variable makes the account for authentication explicit, which makes troubleshooting easier. If you do not use the variable, verify that any accounts that ADC might use have the required permissions. For example the default service account for Compute Engine VMs, Google Kubernetes Engine nodes, and Cloud Run revisions has read-only access to repositories. If you intend to upload from these environments using the default service account, you must modify the permissions.

To create a service account and set up authentication using the environment variable:

  1. Create a service account to act on behalf of your application, or choose an existing service account that you use for automation.

    You will need the location of the service account key file to set up authentication with Artifact Registry. For existing accounts, you can view keys and create new keys on the Service Accounts page.

    Go to the Service Accounts page

  2. Grant the appropriate Artifact Registry role to the service account to provide repository access.

  3. Assign the service account key file location to the variable GOOGLE_APPLICATION_CREDENTIALS so that the Artifact Registry credential helper can obtain your key when connecting with repositories.

    export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
    

    Where KEY-FILE is path to the service account key file.

  4. Verify the version policy of the Maven repository.

    Console

    1. Open the Repositories page in the Cloud Console.

    Open the Repositories page

    1. Click the repository that you want to authenticate to.

    The Details section displays the version policy. If the repository has a snapshot version policy, the Allow snapshot overwrites field indicates if snapshots can overwrite matching snapshot versions in the repository.

    gcloud

    Run the following command to view a descriptionn of a repository.

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

    Where

    • REPOSITORY is the ID of the repository. If you configured a default Artifact Registry repository, it is used when this flag is omitted from the command.
    • PROJECT is the project ID. If this flag is omitted, the current or default project is used.
    • LOCATION is the regional or multi-regional location for the repository.

    The output of the command includes information about the version policy under mavenConfig. In this example, the repository has a snapshot version policy and snapshots cannot overwrite identical versions in the repository.

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

    If a repository does not have a version policy, the value of mavenConfig is {}.

  5. Run the following command to print the repository configuration to add to your Java project.

    Maven

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

    Where

    • PROJECT is the project ID. If this flag is omitted, the current or default project is used.
    • REPOSITORY is the ID of the repository. If you configured a default Artifact Registry repository, it is used when this flag is omitted from the command.
    • LOCATION is the regional or multi-regional location for the repository.

    Gradle

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

    Where

    • PROJECT is the project ID.
    • REPOSITORY is the ID or fully qualified identifier for the repository. If you configured a default Artifact Registry repository, it is used when this flag is omitted from the command.
  6. Configure your Java project.

    Maven

    1. Add the returned settings to the appropriate sections in the pom.xml file for your Maven project. See the Maven POM reference for details about the structure of the file.

      The following example is for a repository that stores both snapshot and release versions.

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

      The <build> section declares the Artifact Registry wagon as an extension. For information about the wagon, see the documentation for the Artifact Registry Maven tools.

    2. Maven resolves some dependencies before applying a wagon defined in pom.xml, including:

    • References in a child Maven project to a parent project using the <parent> element.
    • Plugin dependencies stored in Artifact Registry.

    If your project needs to resolve these dependencies, you must use the core extensions mechanism to ensure that Maven can locate parent POM files and plugins.

    In your project, create the file ${maven.projectBasedir}/.mvn/extensions.xml with the following content. The <extension> element defines the wagon.

     <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 can now resolve parent or plugin dependencies from Artifact Registry.

    Gradle

    1. Add the repository settings to your build.gradle file. The following example shows the relative location of the printed sections.

      This example is for a repository that stores both snapshot and release versions.

      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"
          }
        }
      }
      
      • The plugins section declares the Artifact Registry plugin. For information about the plugin, see the documentation for the Artifact Registry Maven tools.

      • The publishing section declares the files to upload and the target Artifact Registry repository. You can update the file list in the publications section when you are ready to upload. For information about publishing settings, see the Maven Publish plugin documentation.

    2. If your build includes any dependencies, make sure that you declare them in your build.

    3. If you need to use repositories in your init.gradle or settings.gradle file, you can add the plugin configuration to those files.

      For init.gradle, add the following configuration:

      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
      

      For settings.gradle, add the following configuration:

      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"
      

Configuring password authentication

Use this approach when your Java application requires authentication with a specified username and password.

To create a service account and configure authentication:

  1. Create a service account to act on behalf of your application, or choose an existing service account that you use for CI/CD automation.

  2. Grant the appropriate Artifact Registry role to the service account to provide repository access.

  3. Verify the version policy of the Maven repository.

    1. Open the Repositories page in the Cloud Console.

      Open the Repositories page

    2. Click the repository that you want to authenticate to.

      The Details section displays the version policy. If the repository has a snapshot version policy, the Allow snapshot overwrites field indicates if snapshots can overwrite matching snapshot versions in the repository.

  4. If you want to activate the service account in the current Cloud SDK session, run the command:

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

    Where

    • ACCOUNT is the user or service account.
    • KEY-FILE is path to the service account JSON key file.
  5. Run the following command to print the repository configuration to add to your Java project.

    Maven

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

    Where

    • PROJECT is the project ID. If this flag is omitted, the current or default project is used.
    • REPOSITORY is the ID of the repository. If you configured a default Artifact Registry repository, it is used when this flag is omitted from the command.
    • LOCATION is the regional or multi-regional location for the repository.
    • KEY-FILE is path to the service account JSON key file.
    • VERSION-POLICY The version policy of the repository.

      • None - No version policy. The repository stores both snapshot and release packages.
      • Release - The repository has a release version policy.
      • Snapshot - The repository has a snapshot version policy.
    • --allow-snapshot-overwrites indicates that the repository supports overwriting existing snapshot versions.

    Gradle

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

    Where

    • PROJECT is the project ID.
    • REPOSITORY is the ID or fully qualified identifier for the repository. If you configured a default Artifact Registry repository, it is used when this flag is omitted from the command.
    • KEY-FILE is path to the service account JSON key file. If you ran the command to activate your service account, you can omit this flag.
    • VERSION-POLICY The version policy of the repository.

      • None - No version policy. The repository stores both snapshot and release packages.
      • Release - The repository has a release version policy.
      • Snapshot - The repository has a snapshot version policy.
    • --allow-snapshot-overwrites indicates that the repository supports overwriting existing snapshot versions.

  6. Configure your Java project with the settings returned by the command.

    Maven

    1. Add the returned repository settings in the <project> element to the appropriate sections of the pom.xml file for your Maven project. See the Maven POM reference for details about the structure of the file.
    <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. Add the returned authentication settings in the <settings> element to the <servers> section of the ~/.m2/settings.xml file. In the following example, KEY is the private key in your service service account key file.

    See the Maven Settings reference for more information.

    <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. The following line from the returned configuration defines a variable named artifactRegistryMavenSecret for your service account key. Add this line to your ~/.gradle/gradle.properties file so that the key is not visible in your builds or your source control repository.

      artifactRegistryMavenSecret = KEY
      

      In this line, KEY is the private key in your service service account key file. For _json_key_base64, the artifactRegistryMavenSecret contains the base64 encrypted password. For example, base64 -w 0 KEY.

    2. In your build.gradle specify the repository settings:

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

    Your authentication configuration is complete. Before you publish files, ensure that the files to upload are defined in a publications section under publishing. For example:

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

    For information about publishing settings, see the [Maven Publish plugin][maven-publish-plugin]{:class="external"} documentation.

What's next