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
• --parent=example: specify the parent organization for your account as provided when requesting access to Chainguard Libraries for Java and the replace example.
• --ttl=8670d: set the duration for the validity of the token, defaults to 720h (equivalent to 30 days), maximum valid value is 8760d (equivalent to 365 days), valid unit strings range from nanoseconds to hours and are ns, us, ms, s, m, and h.

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)

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

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 Java ecosystem in the table:

Ecosystem Library Entitlements for chainguard.edu (45a0...764595)

                             ID                             | ECOSYSTEM
------------------------------------------------------------+------------
  45a....................................................e1 | JAVA

Contact your Chainguard account owner for confirmation or adjustments if necessary.