Chainguard Libraries Access
Access to Chainguard Libraries is consistent across all permissions and accounts of the Chainguard platform.
If you are not a Chainguard user yet, a new Chainguard account must be created and configured for access to Chainguard Libraries.
If you are already a Chainguard user, the Chainguard account owner in your organization can grant access to Chainguard Libraries.
In both cases, confirm the name of the organization so you can use it with the
--parent
parameter to specify the organization.
Initial authentication
Once your user account is created and access is confirmed, install the
Chainguard Control chainctl
command line
tool and login to your
account:
chainctl auth login
After authentication in a browser window, a successful login displays a message and a token:
Successfully exchanged token.
Valid! Id: 8a4141a........7d9904d98c
Pull token for libraries
Retrieve a new authentication token for the Chainguard Libraries for Java with the chainctl auth pull-token command:
chainctl auth pull-token --library-ecosystem=java --parent=example --ttl=8670h
--library-ecosystem=java
: retrieve the token for use with Chainguard Libraries for Java. Usepython
for a token to use Chainguard Libraries for Python.--parent=example
: specify the parent organization for your account as provided when requesting access to Chainguard Libraries and replaceexample
.--ttl=8670d
: set the duration for the validity of the token, defaults to720h
(equivalent to 30 days), maximum valid value is8760h
(equivalent to 365 days), valid unit strings range from nanoseconds to hours and arens
,us
,ms
,s
,m
, andh
.
When omitting the parent parameter, potentially a list of organizations is
displayed. Use the arrow keys to navigate the selection displayed after the
question “With which location is the pull token associated?” and select the
organization that has the entitlement to access Chainguard Libraries for Java.
Press /
to filter the list.
chainctl
returns a username and password suitable for basic authentication in
the response:
Username: 45a.....424eb0
Password: eyJhbGciO..........WF0IjoxN
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.
To use this pull token in another environment, supply the following for username and password valid for basic authentication. Note that the actual returned values are much longer.
Use the credentials for manual testing in a browser or with a script if you know the URL for a specific library artifact, for example a Java library.
Use environment variables
Using environment variables for username and password is more secure than hardcoding 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 --library-ecosystem=java --parent=example
export CHAINGUARD_JAVA_IDENTITY_ID=45a.....424eb0
export CHAINGUARD_JAVA_TOKEN=eeyJhbGciO..........WF0IjoxN
Combine the call with eval
to populate the environment variables directly by
calling chainctl
:
eval $(chainctl auth pull-token --output env --library-ecosystem=java --parent=example)
Equivalent commands for Python are supported and result in values for the
CHAINGUARD_PYTHON_IDENTITY_ID
and CHAINGUARD_PYTHON_TOKEN
variables.
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:
.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.
Verify entitlement
You can verify entitlements for your organization example
with the following
command:
chainctl libraries entitlements list --parent=example
The output must include the desired ecosystem in the table:
Ecosystem Library Entitlements for example (45a0...764595)
ID | ECOSYSTEM
------------------------------------------------------------+------------
45a....................................................e1 | JAVA
45a....................................................x6 | PYTHON
Contact your Chainguard account owner for confirmation or adjustments if necessary.
Network Requirements
The following section details the required network access to use Chainguard Libraries and the related tools such as chainctl.
Access for chainctl and Other Tools
For initial configuration with chainctl as well as for verification of downloaded libraries with cosign and other tools, you must have HTTPS access to the following domains:
dl.enforce.dev
for download and update of chainctlissuer.enforce.dev
for authentication in web console and with chainctlconsole-api.enforce.dev
for web console and chainctl to administrate and use your Chainguard accounts.console.chainguard.dev
for the web console to administrate and use your Chainguard accounts.
Access for Libraries
Chainguard Libraries use is transparent for development efforts and typically requires no additional network access for workstations and other infrastructure running builds because the libraries are provided by the repository manager as configured for Java or Python.
The repository manager application must have HTTPS access to the domain
libraries.cgr.dev
for library access and issuer.enforce.dev
for
authentication.
If you are accessing Chainguard Libraries directly for testing with curl or with a build tool, the used workstation must have identical access.
Last updated: 2025-04-07 15:17