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.

Integration with Google Cloud services such as Cloud Build or Google Kubernetes Engine does not require authentication. However, you should verify that the identities that act on behalf of these services have the required permissions to access repositories.

Package management is in alpha. It is only available to alpha users, and might not include all features available for container management. To apply for the alpha, complete the sign up form.

Before you begin

  1. If the target repository does not exist, create a new repository.
  2. (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.

Set the GOOGLE_APPLICATION_CREDENTIALS variable to the service account key that you want to authentication helper to use. When ADC uses the default service account credentials, your repository access is dependent on the permissions granted to the account.

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. Run the following command to print the repository configuration to add to your Java project.

    Maven

    gcloud beta 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 beta 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.
  5. 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.
    <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.0</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.

    1. If your pom.xml file references a parent project with the <parent> element, add a core extensions file to the project.

    Maven resolves parent relationships before applying wagons. The core extensions mechanism enables child projects to resolve the parent dependency before applying wagons in the pom.xml file.

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

    Maven can now resolve parent 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.

      plugins {
        id "maven-publish"
        id "com.google.cloud.artifactregistry.gradle-plugin" version "2.1.0"
      }
      
      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.0"
        }
      }
      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.0"
        }
      }
      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 use for your CI/CD automation.

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

  3. 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.
  4. Run the following command to print the repository configuration to add to your Java project.

    Maven

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

    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.

    Gradle

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

    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.
  5. 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 base64-encoded version of your service account key.

    See the Maven Settings reference for more information.

    <settings>
      <servers>
        <server>
          <id>artifact-registry</id>
          <configuration>
            <httpConfiguration>
              <get>
                <usePreemptive>true</usePreemptive>
              </get>
              <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.

      def artifactRegistryMavenSecret = "KEY"
      

      Where KEY a base64-encoded version of your service account.

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

      plugins {
        id "maven-publish"
      }
      
      publishing {
        repositories {
          maven {
            url "https://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
          }
        }
      }
      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 documentation.

What's next