Authentication with npm - CodeArtifact

Authentication with npm

After you create a repository in CodeArtifact, you can use the npm client to install and publish packages.

Use the CodeArtifact login command to fetch credentials for use with npm.

Note

If you are accessing a repository in a domain that you own, you don't need to include --domain-owner. For more information, see Cross-account domains.

aws codeartifact login --tool npm --domain my_domain --domain-owner 111122223333 --repository my_repo

This command makes the following changes to your ~/.npmrc file:

  • Adds an authorization token after fetching it from CodeArtifact using your AWS credentials.

  • Sets the npm registry to the repository specified by the --repository option.

  • Adds "always-auth=true" so the authorization token is sent for every npm command.

The default authorization period after calling login is 12 hours, and login must be called to periodically refresh the token. For more information about the authorization token created with the login command, see Tokens created with the login command.

Change back to default npm registry

The login command sets the npm registry to the repository specified by the --repository option. You can run the following command to set the npm registry back to its default registry when you're done connecting to CodeArtifact.

npm config set registry https://registry.npmjs.com/

Verify npm authentication and authorization

Invoking the npm ping command is an easy way to verify the following:

  • You have correctly configured your credentials so that you can authenticate to an CodeArtifact repository.

  • The authorization configuration grants you the ReadFromRepository permission.

The output from a successful invocation of npm ping looks like the following.

$ npm -d ping npm info it worked if it ends with ok npm info using npm@6.4.1 npm info using node@v9.5.0 npm info attempt registry request try #1 at 4:30:59 PM npm http request GET https://<domain>.d.codeartifact.us-west-2.amazonaws.com/npm/shared/-/ping?write=true npm http 200 https:///npm/shared/-/ping?write=true Ping success: {} npm timing npm Completed in 716ms npm info ok

The -d option causes npm to print additional debug information, including the repository URL. This information makes it easy to confirm that npm is configured to use the repository you expect.

Configuring npm without using the login command

Use npm config to set the CodeArtifact registry endpoint.

npm config set registry=https://my_domain-111122223333.d.codeartifact.region.amazonaws.com/npm/my_repo/

The registry in the sample above is your CodeArtifact repository's endpoint. npm uses the endpoint to connect to your repository. In the sample, my_domain is the name of your domain, 111122223333 is the ID of the owner of the domain, and my_repo is the name of your repository. You can retrieve a repository's endpoint by using the get-repository-endpoint AWS CLI command.

For example, with a repository named my_repo inside a domain named my_domain, the command is as follows:

aws codeartifact get-repository-endpoint --domain my_domain --domain-owner 111122223333 --repository my_repo --format npm

The get-repository-endpoint command will return the repository endpoint:

https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/my_repo/
Important

The registry URL must end with a forward slash (/). Otherwise, you cannot connect to the repository.

Use the following command to add the auth token returned by get-authorization-token, using the same domain and repository.

npm config set //my_domain-111122223333.d.codeartifact.region.amazonaws.com/npm/my_repo/:_authToken=eyJ2ZX...

To make npm always pass the auth token to CodeArtifact, even for GET requests, set the always-auth configuration variable with npm config.

npm config set //my_domain-111122223333.d.codeartifact.region.amazonaws.com/npm/my_repo/:always-auth=true

Example npm configuration file

The following is an example .npmrc file after following the instructions above to set the CodeArtifact registry endpoint, add an authentication token, and configure always-auth.

registry=https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/my-cli-repo/ //my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/my_repo/:_authToken=eyJ2ZX... //my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/my_repo/:always-auth=true

Run npm commands

After you configure the npm client, you can run npm commands. Assuming that a package is present in your repository or one of its upstream repositories, you can install it with npm install. For example, use the following to install the lodash package.

npm install lodash

Use the following command to publish a new npm package to a CodeArtifact repository.

npm publish

For information about how to create npm packages, see Creating Node.js Modules on the npm documentation website. For a list of npm commands supported by CodeArtifact, see npm Command Support.