Tokens

Tokens provide authorization for agents, agent relays, users, and external systems or applications from the server. Agents use tokens when they run process steps and communicate with the HCL Launch server and external services.

Users can use tokens with the command-line interface (CLI) client instead of supplying a user name and password in certain situations. For information, see Command-line client (CLI) reference.

Follow these steps to create a token. You can also create a token through the CLI; see createAuthToken.

  1. Log in as a user with the Manage Security permission. See Setting server configuration security.
  2. On the server, click Settings > Tokens > Create Token. The Create Token dialog box.
  3. From the User list, select the user for the token. You can limit the actions available to the token by applying a token restriction to it. For information about creating and applying token restrictions, see Restricting authentication tokens.
    Note:

    If you are using the token to integrate with IBM® UrbanCode™ Release, you must specify the administrator.

    If the token is for an agent relay that is intended to use component version replication, the user must have a role that has the Read Artifact Set List permission. For information about the Read Artifact Set List permission, see Setting server configuration security.

  4. Specify the expiration date and time.
  5. To limit the use of the token to certain IP addresses, specify one or more IPv4 addresses in CIDR notation in the Allowed IPs field, such as 10.15.10.0/24.
    Note: If you are using clustered servers as described in Setting up high-availability clusters, leave this field blank.
  6. To map token restrictions to user tokens within the UrbanCode Deploy server during token creation, scroll through the created restrictions in the Auth Token Restriction field and select the desired list. Select New and fill out the required fields to create a new Auth Token Restriction. This feature allows you to restrict a token's usage down to specific REST API endpoints. For example, locking down an administrator user's token to only be able to call /cli/agentCLI/info.
  7. Click Save.
    Important: The token is shown only one time after you create it. Copy the token immediately, because you cannot see it again.

Tokens can be used immediately after they are created. You can revoke a token at any time by clicking Delete in the Actions column.

Note: How to generate AuthTokens

Authentication tokens (AuthTokens) are randomly generated as 128-bit values through the SHA-256 algorithm. These tokens are associated with a user ID and a set of restrictions when they are created. The value is produced by using a type 4 Universally Unique Identifier (UUID) and the Java Virtual Machine’s (JVM) Secure Random generator. The generator provides 122 bits of entropy due to the inclusion of 6 bits of UUID variant information.

The UUID generation is managed by the JVM, which uses its configured secure random data source, which is typically /dev/random or /dev/urandom. However, this source can vary based on the JVM configuration.

The 128 bit entropy is generated by the java.util.UUID.randomUUID() variant, which calls the java.security.SecureRandom.nextBytes() bytes to produce 16 bytes (128 bits) of random data. The SecureRandom instance is created by a plain call of a new SecureRandom() object. You must consult the JVM documentation for details about entropy this process is not implemented in HCL Launch.

For complete information about the JVM, see the following resources: