Setting up authentication for Maven and Gradle

This page describes how to configure Maven or Gradle to connect with Artifact Registry repositories.

Package management is only available to alpha users. 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.

Defining the repository

Configure your build to connect to a repository.

Maven

  1. Run the following command to print the repository configuration to add to your Maven project.

    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.
  2. Add the settings to the pom.xml file for your Maven project. The following outline shows the relative placement of each main element. See the Maven POM reference for details about the structure of the file.

    <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">
    
      <!-- Build Settings -->
      <build>
        ...
        <extensions>...</extensions>
      </build>
    
      <!-- Environment Settings -->
      <repositories>...</repositories>
      <distributionManagement>...</distributionManagement>
    </project>
    ````
    
  3. If your POM 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 file.

    These instructions describe the core extensions mechanism available in Maven 3.3.1 or newer. See the Maven 3.3.1 release notes for more information.

    1. 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. Run the following command to print the repository configuration settings:

    gcloud beta artifacts print-settings gradle [--project=PROJECT] [--repository=REPOSITORY]
    

    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.
  2. Add the repository settings to your build.gradle file. The following example shows the relative location of the printed sections. Note that you must include a publications section under publishing to deploy to a repository.

    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"
        }
      }
    }
    
    repositories {
      maven {
        url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
      }
    }
    
  3. If your build includes any dependencies, make sure that you declare them in your build.

  4. 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 authentication

We recommend using a service account for authentication. Service accounts are not associated with a specific user, and Google Cloud applications can obtain credentials automatically from the environment.

The service accounts for applications that typically integrate with Artifact Registry, such as Cloud Build, are configured by default with permissions to access repositories in the same project. You do not need to configure authentication for these applications, but you should verify that the default permissions meet your needs.

If you are using a custom service account, Artifact Registry looks for your credentials in the following order:

  1. Google Application Default Credentials, a strategy for finding your credentials in the environment.

  2. OAuth access token. A short-lived token for the current account in a Cloud SDK session.

If the client you are using requires password authentication, you can use the service account key as the password.

Application Default Credentials

In your build environment, set the variable GOOGLE_APPLICATION_CREDENTIALS so that Application Default Credentials can locate your service account key file.

export GOOGLE_APPLICATION_CREDENTIALS=PATH_TO_KEY_FILE

Access token

Access tokens are short-lived, so generate the token shortly before you run commands to access the repository.

  1. Log in as the service account:

    gcloud auth activate-service-account ACCOUNT --key-file=JSON_KEY
    

    Where

    • ACCOUNT is the user or service account.
    • JSON_KEY is path to the service account JSON key file.
  2. Generate and a new access token with the command:

    gcloud auth print-access-token
    

The command returns the access token.

Password authentication with a service account key

Since the service account key is a long-lived credential, use the following guidelines to limit access to your repositories:

  • Create dedicated service accounts that are only used to interact with repositories.
  • Grant the specific Artifact Registry role for the access required by the service account. For example, a service account that only downloads artifacts only requires the Artifact Registry Reader role.
  • Configure the permissions for your dedicated service accounts on each repository rather than at the project level. You can then specify access based on the repository context.
  • Follow best practices for managing credentials.

To create a service account and use the service account key in your client:

  1. Create the service account for interacting with repositories:

    Console

    1. In Google Cloud Console, open the Service account keys page.

      Go to the Create Service Account Key page

    2. From the Service account list, select New service account.

    3. In the Service account name field, enter a name.

    4. From the Role list, select the appropriate Artifact Registry role for the service account.

    5. Click Create. A JSON file that contains your key downloads to your computer.

    gcloud

    You can run the following commands using Cloud SDK on your local machine, or in Cloud Shell.

    1. Create the service account. Replace NAME with a name for the service account.

      gcloud iam service-accounts create NAME
      
    2. Grant permissions to the service account. Replace PROJECT with your project ID and ROLE with the appropriate Artifact Registry role for the service account. This role applies across repositories in the project. You can change the role later and you can also set different permissions for the service account on specific repositories.

      gcloud projects add-iam-policy-binding PROJECT --member "serviceAccount:NAME@PROJECT.iam.gserviceaccount.com" --role "roles/ROLE"
      
    3. Generate the key file. Replace FILE-NAME with a name for the key file.

      gcloud iam service-accounts keys create FILE-NAME.json --iam-account NAME@PROJECT.iam.gserviceaccount.com
      

    The service account key file is in JSON format and includes your base64-encoded private key.

  2. Verify that permissions are correctly configured for the service account.

  3. You can optionally base64-encode all the contents of the key file.

    Linux

    base64 FILE-NAME &gt; NEW-FILE-NAME
    

    macOS

    base64 -i FILE-NAME -o NEW-FILE-NAME
    

    Windows

    Base64.exe -e FILE-NAME &gt; NEW-FILE-NAME
    

    Where FILE-NAME is the original key file name and NEW-FILE-NAME is your base64-encoded key file.

  4. Use the contents of the service account key file as the password for the repository.

    Maven

    In the Maven ~/.m2/settings.xml file, add credentials in a <server> element.

    The value of the <id> element must match the ID of the repository configured in the POM file. Replace KEY with the contents of the service account key file.

    • For a base64-encoded key file, use _json_key_base64 as the user name.
    <server>
      <id>artifact-registry</id>
      <username>_json_key_base64</username>
      <password>KEY</password>
    </server>
    
    • For an unencoded key file, use _json_key as the user name.
    <server>
      <id>artifact-registry</id>
      <username>_json_key</username>
      <password>KEY</password>
    </server>
    

    Gradle

    1. Assign the key to a variable in a local ~/.gradle/gradle.properties file so that the key is not visible in the build file or your source control repository. Replace KEY with the contents of the service account key file.

      artifactRegistryKey=KEY
      
    2. In build.gradle specify your credentials.

      • For a base64-encoded key file, use _json_key_base64 as the user name:
      repositories {
          maven {
              url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
              credentials {
                  username "json_key_base64"
                  password artifactRegistryKey
              }
          }
      }
      
      • For an unencoded key file, use _json_key as the user name.
        repositories {
            maven {
                url "artifactregistry://LOCATION-maven.pkg.dev/PROJECT/REPOSITORY"
                credentials {
                    username "json_key_base64"
                    password artifactRegistryKey
                }
            }
        }
        ```
      

What's next