Shape the future of software delivery and make your voice heard by taking the 2021 State of DevOps survey.

Setting up authentication for npm

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.

Before you begin

  1. If the target repository does not exist, create a new repository.
  2. If you are connecting to repositories from Windows, install PowerShell,
  3. (Optional) Configure defaults for gcloud commands. if you want to connect to a Node.js package repository from Windows.
  4. Create a service account to act on behalf of your application.
  5. If you are new to npm, read the overview to learn about scoped packages and the configuration file for your authentication settings.

Overview

Artifact Registry supports the following authentication methods.

Using a credential helper
This option provides the most flexibility. When you include the helper in your npm 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.

Authenticating with a credential helper

When you use the npm credential helper, your credentials are not stored in your Node.js 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 the GOOGLE_APPLICATION_CREDENTIALS environment variable:

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

To configure authentication:

  1. Run the following command to print the repository configuration to add to your Node.js project. If you want to store the settings in the npm global or per-user configuration file, you must include a scope.

    gcloud artifacts print-settings npm [--project=PROJECT] \
    [--repository=REPOSITORY] [--location=LOCATION]
    --scope=@SCOPE-NAME
    

    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.
    • SCOPE-NAME is the name of the npm scope to associate with the repository.

      You specify this scope to publish or install packages using this repository. Unscoped packages are associated with your default npm registry.

      If you do not specify a scope, the returned configuration will set the repository as your default npm registry.

  2. Add the returned configuration settings to your project .npmrc configuration file, which is in the same directory as package.json.

  3. If you have other Node.js repositories to connect to, repeat the previous steps to obtain the settings and add them to the .npmrc file.

When you want to connect to a repository, refresh the access token for authentication within 60 minutes of making the connection. google-artifactregistry-auth is a client library that updates credentials for Artifact Registry repositories.

To refresh credentials, use one of these options:

  • Use npx directly to refresh the access token. If you are using npm 5.2.0 or newer, it is included with npm.

    1. Ensure that credentials for connecting to the public npm registry are in your user npm configuration file, ~/.npmrc.

    2. Run the following command in the folder above your Node.js project.

      npx google-artifactregistry-auth PROJECT-NPMRC
      

      Where PROJECT-NPMRC is the path to the .npmrc file in your project directory.

      You must run the command outside of your project directory so that npx uses your public npm registry credentials in ~/.npmrc to download google-artifactregistry-auth.

  • Add a script to the package.json file in your project.

    "scripts": {
     "artifactregistry-login": "npx google-artifactregistry-auth"
    }
    

    Run the script:

    npm run artifactregistry-login PROJECT-NPMRC
    

    Where PROJECT-NPMRC is the path to the .npmrc file in your project directory.

  • For versions of npm older than 5.2.0, perform the following steps:

    1. Run the command:

      npm install google-artifactregistry-auth --save-dev --registry https://registry.npmjs.org/
      
    2. Add it to an authentication script:

    "scripts": {
        "artifactregistry-login": "./node_modules/.bin/artifactregistry-auth",
    }
    

    Run the script:

    npm run artifactregistry-login PROJECT-NPMRC
    

    Where PROJECT-NPMRC is the path to the .npmrc file in your project directory.

If you did not specify a scope with the print-settings command, you can run the following command to associate a scope with an Artifact Registry repository.

npm config set @SCOPE_NAME:registry https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY/

Configuring password authentication

Use this approach when your Node.js application requires authentication with a specified 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.

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 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. 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 Node.js project. If you want to store the settings in the npm global or per-user configuration file, you must include a scope.

    gcloud artifacts print-settings npm [--project=PROJECT] \
    [--repository=REPOSITORY] [--location=LOCATION] --scope=@SCOPE-NAME --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.
    • SCOPE-NAME is the name of the npm scope to associate with the repository.

      You specify this scope to publish or install packages using this repository. Unscoped packages are associated with your default npm registry.

      If you do not specify a scope, the returned configuration will set the repository as your default npm registry.

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

  5. Add the returned configuration settings to your project .npmrc configuration file, which is in the same directory as package.json.

  6. If you have other Node.js repositories to connect to, repeat the previous steps to obtain the settings and add them to the .npmrc file.

What's next