Configure authentication to Artifact Registry for npm

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

You don't 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.

Before you begin

Install the Google Cloud CLI, then initialize it by running the following command:
```
gcloud init
```
Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
(Optional) Configure defaults for gcloud CLI commands.
If you are connecting to repositories from Windows, install PowerShell.
Create a service account to act on behalf of your application.
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

google-artifactregistry-auth is a client library that obtains credentials for Artifact Registry repositories.

Artifact Registry searches for credentials in the following order:

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.
Credentials provided by the Google Cloud CLI, 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:

Create a service account to act on behalf of your application, or choose an existing service account that use for your CI/CD automation.
Grant the specific Artifact Registry role to the service account to provide repository access.
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:

Run the following command to print the repository configuration:
```
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.
  
  Using scopes ensures that you always publish and install packages from the correct repository.
  
  Unscoped packages are associated with your default npm registry, typically the npm public registry. If you don't specify a scope, the returned configuration sets your Artifact Registry repository as the default registry. This can cause problems if your Node.js projects need to install packages from both the public npm registry and your Artifact Registry repository.
Add the returned configuration settings to the .npmrc configuration file in your Node.js projects. This file is usually in the same directory as package.json.

Make sure that you include these settings in Node.js projects for packages that you publish as well as projects that will install dependencies from your npm repository.
If you have other Node.js repositories to connect to, repeat the previous steps to obtain the settings and add them to the appropriate .npmrc files.
When you are ready to connect a repository, obtain an access token for authentication.

Each Artifact Registry Node.js package repository is associated with a registry endpoint https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY

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/

Obtaining an access token

Access tokens are valid for 60 minutes. Generate an access token shortly before running commands that interact with repositories.

To obtain a token, use one of these options:

Use the npx command to refresh the access token.
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 your Node.js project directory.
```
npx google-artifactregistry-auth
```
  If your Artifact Registry repository is set as your global registry and your packages are not scoped, use the following command instead so that the command can download the credential helper from the public npm registry instead of your Artifact Registry repository.
```
npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
```

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

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

Run the script in your Node.js project directory.

npm run artifactregistry-login

Artifact Registry reads Artifact Registry repository settings in your project .npmrc file and uses them to add token credentials to your user .npmrc file. Storing the token in your user .npmrc file isolates your credentials from your source code and your source control system.

--repo-config is the .npmrc file with your repository settings. If you don't specify this flag, the default location is the current directory.
--credential-config is the path to the .npmrc file where you want to write the access token. The default is your user .npmrc file.

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:

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

Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.
Grant the specific Artifact Registry role to the service account to provide repository access.
If you want to activate the service account in the current gcloud CLI 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.
Run the following command to print the repository configuration:
```
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.
  
  Using scopes ensures that you always publish and install packages from the correct repository.
  
  Unscoped packages are associated with your default npm registry, typically the npm public registry. If you don't specify a scope, the returned configuration sets your Artifact Registry repository as the default registry. This can cause problems if your Node.js projects need to install packages from both the public npm registry and your Artifact Registry repository.
- KEY-FILE is path to the service account JSON key file.
Note: The returned configuration settings includes a placeholder email address. An email address is required in the npm configuration to publish npm packages. The placeholder email address is not used by Artifact Registry for authentication.
Add the returned configuration settings to the .npmrc configuration file in your Node.js projects. This file is usually in the same directory as package.json. Make sure that you include these settings in Node.js projects for packages that you publish as well as projects that will install dependencies from your npm repository.
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.