Chainguard Libraries access

Chainguard Libraries provide controlled access to security-enhanced Java and Python dependencies through the unified Chainguard platform authentication system. This guide explains how to access (download) Chainguard library artifacts for your organization.

Getting started

Prerequisites

• Ensure you have access to Chainguard Libraries.
  • If you are not a Chainguard user yet, create a Chainguard account. To add an entitlement to Chainguard Libraries for your organization, contact your Chainguard account team.
• If you have access to more than one Chainguard organization, confirm the name of the one you want to use. You can then pass it to chainctl commands with the --parent parameter.

Direct access vs. artifact manager

There are two approaches to access: Using an artifact manager or direct access.

Artifact manager

If your organization uses an artifact manager such as Cloudsmith, JFrog Artifactory, or Sonatype Nexus, you can set up and configure credentials once per language ecosystem. Then, all projects and developers automatically inherit the configuration. This option suits organizations with multiple teams, and provides centralized access controls and consistent uptime.

Direct access

Set up authentication directly in each project’s build configuration. This option allows for faster initial setup, but it does not allow for global configuration. It requires configuration per project and workstation, which creates more overhead as you scale across teams and projects.

An artifact manager authenticates to Chainguard Libraries with a pull token. For direct access, you can use a session token or a pull token.

Choose an authentication method

Chainguard Libraries supports both short-lived credentials and long-lived pull tokens. Chainguard recommends short-lived credentials where your tools and workflows support them, because they expire on their own and are tied to a person or workload. Pull tokens work with every build tool and artifact manager.

For guidance that applies to every option, see Credential guidelines.

A check in Chainguard Checks doesn’t need a pull token. It can download JavaScript and Python libraries through a workload identity that holds the libraries.javascript.pull or libraries.python.pull role. A Chainguard Workspaces session has no credential for Chainguard Libraries, as described in Credentials a session can’t supply.

Initial authentication

Once your user account is created and access is confirmed, install the Chainguard Control chainctl command line tool and log in to your account:

chainctl auth login

Note: chainctl auth login supports several login flows, including device-code login for machines without a browser and assumable identities for CI. If the default browser flow doesn't work in your environment, see Authentication options.

After authentication in a browser window, a successful login displays a message and a token:

Successfully exchanged token.
Valid! Id: 8a4141a........7d9904d98c

Session tokens and pull tokens

Chainguard Libraries accepts two kinds of credentials:

• Session token: a token from your own chainctl login, scoped to libraries.cgr.dev. It’s valid for up to one hour, pulls are associated with your user, and you can end the session with chainctl auth sessions revoke. Getting one needs no permissions beyond pull access, and every machine that uses it needs chainctl.
• Pull token: a username and password for a separate identity that holds only a pull role. It works in any tool that supports basic authentication and doesn’t need chainctl, but it stays valid until its TTL ends or you delete it. Creating one requires a pull_token_creator role. For details, see Creating pull tokens for libraries.

Build tools get session tokens from chainctl in the following ways:

• The Python keyring provider runs chainctl auth token --audience=libraries.cgr.dev each time pip or uv needs credentials, so no token is written to your configuration files.

• chainctl auth configure-npm writes your session token to the project .npmrc. Re-run the command when the token expires.

• chainctl auth configure nuget writes your session token to the NuGet configuration file. Re-run the command when the token expires.

• Other build tools, such as Maven, Gradle, and Go, accept a session token in place of a pull token. Use _token as the username and the output of chainctl auth token as the password. For example, set the environment variables that the Java build configuration uses:

  export CHAINGUARD_JAVA_IDENTITY_ID=_token
  export CHAINGUARD_JAVA_TOKEN="$(chainctl auth token --audience=libraries.cgr.dev)"

  Run the commands again when the token expires.

To reduce how often you need to log in again on a workstation, install the token refresh service:

chainctl auth configure-refresh-service install --audience=libraries.cgr.dev

The refresh service renews the libraries.cgr.dev token in the chainctl token cache, which the Python keyring provider and chainctl auth token read. It only renews a token that’s already in the cache, so log in with chainctl auth login --audience=libraries.cgr.dev first. It doesn’t update a token that was already copied into a file or an environment variable, such as .npmrc, the NuGet configuration file, or CHAINGUARD_JAVA_TOKEN.

Credential guidelines

Follow these guidelines for whichever option you choose:

• Commit the registry URL to your project, but do not commit credentials. Keep authentication lines, such as _auth and _authToken entries in .npmrc, out of version control.
• Prefer short-lived credentials where your build tools and workflows support them.
• Store pull tokens in a secrets manager or password manager, and load them from environment variables instead of writing them into configuration files. A team can share one pull token this way.
• Set the shortest pull token TTL that fits how often you can rotate it, replace the token before it expires, and delete expired tokens.
• Limit who can create pull tokens, so you know where each one is used.
• Give CI/CD pipelines and other automated workloads, such as AI agents that run outside a workstation, their own credential, ideally an assumable identity, instead of an engineer’s session token or a team’s shared pull token.

Creating pull tokens for libraries

Pull tokens authenticate requests to download library artifacts from Chainguard. You can create the pull tokens:

• With the chainctl command, or
• Using the Chainguard console.

For environments where short-lived credentials are not suitable, such as some CI/CD platforms, you can generate a pull token, which provides longer-lived access to Chainguard Libraries.

To create a pull token you must have the relevant entitlement for the ecosystem and the libraries.java.pull_token_creator, libraries.javascript.pull_token_creator, or libraries.python.pull_token_creator role.

Creating pull tokens with chainctl

Create a new pull token for the Chainguard Libraries for Java with the chainctl auth pull-token command:

chainctl auth pull-token --repository=java --ttl=8670h

• --repository=java: retrieve the token for use with Chainguard Libraries for Java. Use python for a token to use Chainguard Libraries for Python and javascript for a token to use Chainguard Libraries for JavaScript.
• --ttl=8670h: set the duration for the validity of the token, defaults to 720h (equivalent to 30 days), maximum valid value is 8760h (equivalent to 365 days), valid unit strings range from nanoseconds to hours and are ns, us, ms, s, m, and h.

Use the optional --name flag to supply a meaningful and short name for the token, to be able to locate it easier at a later stage.

If you belong to a single organization, chainctl selects it automatically. If you have access to more than one, it asks “With which location is the pull token associated?” Use the arrow keys to select the organization that has the entitlement to access Chainguard Libraries for Java, and press / to filter the list. Pass --parent=<organization> to skip the prompt.

chainctl returns a username and password suitable for basic authentication in the response:

Username: <identity-id>

Password: <pull-token>

Creating pull tokens with the Chainguard Console

Follow these steps to create a pull token for Chainguard Libraries in the Chainguard console:

1. Use your authentication details to access the console at https://console.chainguard.dev/.
2. In the left-hand navigation, click Overview.
3. Click the Manage pull tokens link, then click Create token.
   • Alternatively, select Access Tokens from the menu on the Settings page.
4. Configure the access token:
   • Name: Provide a name. The name can later be used to locate the token in the list.
   • Description: Optionally provide a description of the token.
   • Access: Choose the library that this token should access.
   • Expiration: Set an expiration date for the token. The default is 30 days.
5. Click Create token.
6. When the username and password values are displayed, save them in a secure location. You need them to use the pull token, and the console doesn’t display them again.

Pull token characteristics and use

The username is the identity ID of the pull token identity that chainctl just created, and the password is the token itself. chainctl labels the same two values identity_id and token with --output=json, and CHAINGUARD_JAVA_IDENTITY_ID and CHAINGUARD_JAVA_TOKEN with --output=env. Refer to pull token output formats and credential names for the full mapping.

The returned username and password combination is a new credential set in the organization that is independent of the account used to create and retrieve the credential set. It is therefore suitable for use in any service application, such as a repository manager or a build tool that is not tied to a specific user. For individual development with direct access, prefer a session token where your build tool supports it.

To use the pull token in another environment, supply the username and password for basic authentication. Note that the actual returned values are much longer.

Note: Chainguard does not offer an SLA for uptime availability of the Chainguard Libraries repositories at libraries.cgr.dev. To reduce production risk and ensure reliability, we recommend proxying the repositories through your own artifact repository whenever possible.

For artifact manager setup, see the global configuration guides:

• Java
• JavaScript
• Python

For direct access, see the build configuration guides:

• Java
• JavaScript
• Python

Use environment variables for pull token credentials

Using environment variables for username and password is more secure than hard coding the values in configuration files. In addition, you can use the same configuration and files for all users to simplify setup and reduce errors.

Use the env environment output option to create a snippet for a new token suitable for integration in a script.

$ chainctl auth pull-token --output env --repository=java
export CHAINGUARD_JAVA_IDENTITY_ID=<identity-id>
export CHAINGUARD_JAVA_TOKEN=<pull-token>

Combine the call with eval to populate the environment variables directly by calling chainctl:

eval $(chainctl auth pull-token --output env --repository=java)

Equivalent commands for Python and JavaScript are supported and result in values for the CHAINGUARD_PYTHON_IDENTITY_ID/CHAINGUARD_PYTHON_TOKEN and CHAINGUARD_JAVASCRIPT_IDENTITY_ID/CHAINGUARD_JAVASCRIPT_TOKEN variables.

Use the export commands in a ~/.env or similar file or use your preferred secrets management application to reuse the token in multiple sessions. Source the file or load the secrets from the app to have access to the tokens in your shell session, including build configurations file that can load from environment variables, for example a Maven settings.xml file.

Running this command as part of a login script or some other automation allows your organization to replace actual username and password values in your build tool configuration with environment variable placeholders:

• Java build tool configuration
• JavaScript build tool configuration
• Python build tool configuration

uv index-scoped environment variables

When using uv for Python, you can supply credentials through index-scoped environment variables instead of a shared secrets file or .netrc. For a named index, uv reads UV_INDEX_<NAME>_USERNAME and UV_INDEX_<NAME>_PASSWORD, where <NAME> is the index name uppercased with hyphens replaced by underscores.

For an index named chainguard, set:

export UV_INDEX_CHAINGUARD_USERNAME="${CHAINGUARD_PYTHON_IDENTITY_ID}"
export UV_INDEX_CHAINGUARD_PASSWORD="${CHAINGUARD_PYTHON_TOKEN}"

This pairs well with the eval approach above: generate the CHAINGUARD_PYTHON_IDENTITY_ID and CHAINGUARD_PYTHON_TOKEN variables, then map them to uv’s index-scoped names. Refer to the uv build configuration for index setup details.

.netrc for authentication

curl and a number of other tools support configuration of username and password authentication details for a specific domain in the .netrc file, typically located in the user’s home directory.

Use this approach for authentication to a repository manager in your organization or to Chainguard Libraries directly, for example with pip and others for Chainguard Libraries for Python, with bazel for Chainguard Libraries for Java or for manual testing with curl.

The following example shows a suitable setup for a repo manager available at repo.example.com:

machine repo.example.com
login YOUR_USERNAME_FOR_REPOSITORY_MANAGER
password YOUR_PASSWORD

For a direct connection to Chainguard Libraries, for example for testing with curl, use the following example with the username CHAINGUARD_PYTHON_IDENTITY_ID and password CHAINGUARD_PYTHON_TOKEN value for the pull token for the desired language ecosystem:

machine libraries.cgr.dev
login CHAINGUARD_PYTHON_IDENTITY_ID
password CHAINGUARD_PYTHON_TOKEN

Note that the long string for the password value must use only one line.

When you use this .netrc file in a container build, mount it as a build secret rather than copying it into an image layer. See Container builds.

Verification

Use the credentials for manual testing in a browser or with a script and curl if you know the URL for a specific library artifact. Refer to the following sections for more details:

• Technical details and manual testing for Java libraries
• Technical details and manual testing for JavaScript libraries
• Technical details and manual testing for Python libraries
• Use environment variables
• .netrc for authentication

Python keyring provider

Python users can leverage an alternative to pull tokens. The Chainguard keyring implementation provides short-lived credentials from supported environments, such as local development and CI/CD platforms that can use assumable identities. For GitHub Actions, follow Create an assumable identity for a GitHub Actions workflow and bind the libraries.python.pull role.

Where possible, Chainguard recommends using short-lived credentials to access Chainguard Libraries.

To set up the keyring, install the keyrings-chainguard-libraries package:

pip install keyrings-chainguard-libraries

Note: If you haven’t set up access to Chainguard Libraries for Python, the above command installs the package from PyPI. After installing and configuring Chainguard Libraries for Python, you can get the private package again, to get the package built by Chainguard. To re-install the package:

pip install keyrings-chainguard-libraries --ignore-installed --no-cache-dir

Once the keyring package is installed, when you request to install packages from Chainguard Libraries for Python, the keyring automatically retrieves short-lived credentials for you, using chainctl. The keyring requires chainctl to be installed and logged in on the same machine. It holds the token in memory only, and it works only for requests that go directly to libraries.cgr.dev, not through an artifact manager. To reduce how often you need to log in again, pair it with the token refresh service.

To use the keyring with a project uv, install the keyring:

uv pip install keyrings-chainguard-libraries

Note: If you haven’t set up access to Chainguard Libraries for Python, the above command installs the package from PyPI. After installing and configuring Chainguard Libraries for Python, you can get the private package again, to get the package built by Chainguard. To re-install the package:

uv pip install keyrings-chainguard-libraries --reinstall --no-cache

By default, uv disables keyring auth.

To enable it in the global uv.toml:

keyring-provider = "subprocess"

To enable it in a project-specific pyproject.toml:

[tool.uv]
keyring-provider = "subprocess"

Pull token management

Pull tokens are separate identities with username and password that are used for access to Chainguard Libraries. The tokens have a limited Time to Live (TTL) with a default of 30 days and a maximum TTL of 365 days.

As a result, pull tokens become invalid after the TTL and are flagged as expired. For your use of Chainguard Libraries you must replace the token with a new one.

Expired tokens can no longer be used for access to Chainguard Libraries, but otherwise do not cause any issues and continue to exist until you delete them.

Inspect all pull tokens for your organization in the Chainguard console:

• Use your authentication details to access the console at https://console.chainguard.dev/.
• Select Overview in the left-hand navigation.
• Select the Manage pull tokens link.
  • Alternatively, select Settings in the left-hand navigation, and select Access Tokens in the menu on the settings page.

The list includes the following columns:

• Name - the name of the pull token. Expired pull tokens show an Expired warning.
• Description - the description of the pull token.
• Access - what the pull token can pull, such as Java Libraries.
• Created - the date when the pull token was created.
• Expiration - string description of the expiration status of the token, such as in 8 months or 4 days ago.
• Actions - menu button to perform actions on the pull token: Delete and Edit.

Use the action to remove a pull token:

• Locate the row of the desired pull token, typically an expired token.
• Use the menu button in the Actions column of the same row and select Delete.
• Confirm the deletion in the dialog by pressing Delete pull token.

Alternatively use chainctl with the auth pull-token and iam identities commands for various inspection and management tasks.

List all pull tokens with the list command:

chainctl auth pull-token list

The displayed list includes the following columns:

• ID - the identifying username of the pull token
• NAME - the name of the pull token
• DESCRIPTION - the description of the pull token
• ROLES - the assigned organization and role for the pull token. The value shows the name of the organization separate from the role with a colon. Valid roles are all pull authorization from for apk packages apk.pull, container images registry.pull, Python libraries libraries.python.pull, Java libraries libraries.java.pull, and JavaScript libraries libraries.javascript.pull .
• EXPIRES - the number of days until the end of the TTL period. Negative values indicate expired tokens.

List all pull tokens for Chainguard Libraries for Java that are not yet expired:

chainctl auth pull-token list --repository=java

List all expired pull tokens for Chainguard Libraries for Python:

chainctl auth pull-token list --repository=python --expired=true

Use the delete command for IAM identities to delete a specific pull token using its ID 45a0c61ea6fd97...:

chainctl iam identities delete 45a0c61ea6fd97...

Use the --expired flag with the identifier or name of your organization, example in this sample, to remove all expired static identities, including expired pull tokens:

chainctl iam ids rm --expired --parent=example

Manage library entitlements

An entitlement grants your organization access to a Chainguard Libraries ecosystem. To add or remove an entitlement, contact your Chainguard account team.

Once your organization is entitled to an ecosystem, you can list your entitlements and change their upstream fallback policy yourself with chainctl libraries entitlements.

Enable upstream fallback

New entitlements have upstream fallback on by default. To turn on upstream fallback for an entitlement that has it off, use the --policy flag:

chainctl libraries entitlements create --ecosystems=JAVASCRIPT --policy=CHAINGUARD_AND_UPSTREAM

To change the upstream fallback policy on an existing entitlement, rerun the command with the new --policy value. For example, --policy=CHAINGUARD serves only Chainguard-built packages.

List entitlements

You can verify entitlements for your organization example.com to verify which ecosystems are enabled:

chainctl libraries entitlements list

The output includes the ecosystem and configured policy in the table:

Ecosystem Library Entitlements for example (45a0...p7q)

                            ID                             | ECOSYSTEM  |             POLICY
-----------------------------------------------------------|------------|--------------------------------
 45a0c61a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q/12345abc67890 | JAVASCRIPT | POLICY_CHAINGUARD_AND_UPSTREAM
 45a0c61a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q/45678abc67890 | JAVA       | POLICY_CHAINGUARD
 45a0c61a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q/56789abc67890 | PYTHON     | POLICY_CHAINGUARD

Manage library policies

Users with the Owner role can create, enable, disable, and list library policies using chainctl libraries policy commands. These policies apply to all packages pulled through Chainguard Repository. The upstream fallback must be enabled for an ecosystem in order to use policies.

Learn about how to manage policies in the Libraries policies page.