Token-based authentication

When are tokens used?

Puppet Enterprise users generate tokens to authenticate their access to certain PE command-line tools and API endpoints. Use authentication tokens to manage access to the following PE services:

Authentication tokens are tied to the permissions granted to the user through RBAC, and provide the user with the appropriate access to HTTP requests.

Benefits of using tokens for authentication

  • Tokens allow you to take action remotely, from your workstation for example, without having to log into PE-managed servers.
  • Tokens are RBAC-aware, meaning that they reflect the user permissions granted through RBAC.
  • Tokens are issued per user. Their usage is logged on a per-user basis.
  • Tokens have a limited lifetime.

Generating a token

The authentication tokens used in PE are JSON web tokens (JWT). They contain the following information:

  • The time that the token was issued.
  • The length of the token’s lifetime.
  • The user’s UUID.

You can generate a token by using the API endpoint, or by using the Puppet Access command-line tool. Each of these methods is explained below.

Note: For security reasons, authentication tokens can only be generated for revocable users. The admin user and api_user cannot be revoked.

Configuring Puppet Access

For information on installing the Puppet Access command line tool, which is bundled in the PE client tools package, see installing the PE client tools package.

After you install the PE client tools (either on the Puppet master or on a separate workstation), run the following command to create the Puppet Access configuration file:

mkdir ~/.puppetlabs
    echo '{"service-url":"https://<HOSTNAME>:4433/rbac-api"}' > ~/.puppetlabs/puppet-access.conf

The service-url setting in this Puppet Access config file points the tool at the RBAC service running on the Puppet console server.

Generating a token using the command line tool

Puppet Access is a command-line tool for generating and managing authentication tokens.

To generate an authentication token using the Puppet Access command-line tool:

  1. From the command line on any PE-managed node, enter puppet-access login.

  2. When prompted, enter the same username and password that you use to log into the PE console.

    You can also pass your username as an argument, such as puppet-access login <YOUR USER NAME>. If you do this, you will only be prompted for a password.

  3. Puppet Access contacts the token endpoint in the RBAC API. If your login credentials are correct, the RBAC service generates a token.

  4. The token is stored in a file for later use. The default location for storing the token is ~/.puppetlabs/token.

Note: If you run the login command with the --debug flag, the Puppet Access tool outputs the token, as well as the username and password. For security reasons, exercise caution when using the --debug flag with the login command.

Tip: You can print the token at any time using puppet-access show.

Generating a token using the API endpoint

The RBAC v1 API includes a token endpoint. (The steps below assume you are using cURL.)

To generate a token:

  1. Post your RBAC user login credentials.

    In the command line, post your RBAC user login credentials using the token endpoint:

    curl -k -X POST -H 'Content-Type: application/json' -d '{"login": "<YOUR PE USER NAME>", "password": "<YOUR PE PASSWORD>"}' https://$<HOSTNAME>:4433/rbac-api/v1/auth/token

    The parts of this cURL request are explained below:

    • -k flag: The -k flag turns off SSL verification of the RBAC server so that you can use the HTTPS protocol without providing a CA cert. Alternatively, use the --cacert [FILE] option and specify a CA certificate as described in Forming requests for node classification. If you do not provide one of these options in your cURL request, cURL complains about not being able to verify the RBAC server.

    Note: The -k flag is shown as an example only. Use your own discretion when choosing the appropriate server verification method for the tool you are using.

    • -X POST: This is an HTTP POST request to provide your login information to the RBAC service.
    • -H 'Content-Type: application/json': Sets the Content-Type header to application/json, which indicates to RBAC that the data being sent is in JSON format.
    • -d '{"login": "<YOUR PE USER NAME>", "password": "<YOUR PE PASSWORD>"}': Provides the username and password that you use to log into the PE console.
    • https://<HOSTNAME>:<PORT>/rbac-api/v1/auth/token: Sends the request to the token endpoint. For HOSTNAME, provide the FQDN of the server that is hosting the PE console service. If you are making the call from the console server, you can use “localhost.” For PORT, provide the port that the PE services (node classifier service, RBAC service, and activity service) listen on. The default port is 4433.
  2. Save the returned token.

    The returned token is a JSON object containing the key token and the token itself. Tokens are quite long. The following returned token example has been truncated:


    Copy the returned token to a text file or environment variable. For example, you can save it as an environment variable using export TOKEN=<PASTE THE TOKEN HERE>.

Generating a token for use by a service

If you need to generate a token for use by a service and the token doesn’t need to be saved, use the --print option with the Puppet Access command line tool. puppet-access login [username] --print generates a token, and then displays the token content as stdout (standard output) rather than saving it to disk.

When generating a token for a service, you may want to specify a longer token lifetime so that you don’t have to regenerate the token too frequently. See Setting a token-specific lifetime.

Using a token

When you generate a token, you can continue to use it until it expires, or until your access is revoked. The token has the exact same set of permissions as the user that generated it.

Using a token with PE API endpoints

The example below shows how to use a token in an API request. In this example, we are using the /users/current endpoint of the RBAC API to get information about the current authenticated user. The example assumes that you saved your token as an environment variable using export TOKEN=<PASTE THE TOKEN HERE>.

curl -k -x GET https://<HOSTNAME>:4433/rbac-api/v1/users/current -H "X-Authentication:$TOKEN"

The example above uses the X-Authentication header to supply the token information. In some cases, such as GitHub webhooks, you may need to supply the token in a token parameter by specifing the request as follows:

curl -k -X GET https://<HOSTNAME>:4433/rbac-api/v1/users/current?token=$TOKEN

Viewing token activity

Token activity is logged by the PE activity service.

To view token generation activity in the PE console, click Access control > Users, and click on the user that you are interested in. In the user details screen, click the Activity tab.

Managing tokens

Changing the default lifetime

Tokens have a default lifetime of five minutes. To change the default period, in the PE console, click Nodes > Classification > PE Console. In the classes tab, find the puppet_enterprise::profile::console class. In the Parameter name dropdown, select the rbac_token_auth_lifetime parameter. In Value, enter the lifetime value. You can specify a numeric value followed by “y” (years), “d” (days), “h” (hours), “m” (minutes), or “s”(seconds). For example, a value of “12h” generates a token valid for 12 hours. Do not add a space between the numeric value and the unit of measurement. If you do not specify a unit, it is assumed to be seconds.

Note: If you do not want the token to expire, set the lifetime to “0”, which gives the token a lifetime of approximately 10 years.

Note: Any user with permission to edit infrastructure-related node groups will be able to change the default lifetime setting. To restrict access, see the recommendation in Managing user access to the lifetime setting for authentication tokens.

Setting a token-specific lifetime

When generating a token, you can change the lifetime of the token if you have the “Tokens - Override default expiry” permission. This permission is given to the Administrators and Operators roles by default. You can remove the permission from the Operators role.

Note: If a user doesn’t have this permission, but has the permission to edit the PE Console node group, the user is able to change the default lifetime setting for all tokens through the rbac_token_auth_lifetime parameter. To avoid unintentionally granting excessive permissions, see the note in Managing user access to the lifetime setting for authentication tokens.

When generating a token using the command line tool:

When generating a token using the Puppet Access command line tool, use the lifetime option to specify the amount of time for which the token is valid. For example, puppet-access login --lifetime 1h.

When generating a token using the API endpoint:

When generating a token using the token endpoint of the RBAC API, use the lifetime value to specify the amount of time for which the token is valid. For example, {"login": "<YOUR PE USER NAME>", "password": "<YOUR PE PASSWORD>", "lifetime": "1h"}.

Note: With the exception of the UUID, the user information in a token is subject to change. If user information changes in your user directory, the token will become invalid.

Deleting a token file

If you logged into the Puppet Access command line tool to generate a token, you can remove the file that stores that token simply by running the delete-token-file command. This is useful if you are working on a server that is used by other people. Removing the token file prevents other users from using your authentication token, but it does not actually revoke the token. Once the token has expired, there’s no risk of obtaining the contents of the token file.

To delete your token file, from the command line, type puppet-access delete-token-file.

If you do not specify a path, the tool looks for the token file at the default path. If you used a different path to store your token file, specify --token-path as follows:

puppet-access delete-token-file --token-path <YOUR TOKEN PATH>

Revoking a token

Revoke tokens through the token endpoint of the v2 RBAC API. All token revocation attempts are logged in the activity service, and may be viewed on the user’s Activity tab in the console.

You can revoke your own token and any other token you possess. Users with the permission to revoke other users can also revoke those users’ tokens, as the users:disable permission includes token revocation. Revoking a user’s token(s) does not revoke the user’s PE account.

If a user’s account is revoked, all tokens associated with that user account are also automatically revoked.

Changing configuration settings

There are several options that you can specify with the puppet-access command in the command line.

  • --service-url: Changes the contact information for the server issuing the token. The token is issued by the RBAC service. You typically only need to change this if you are moving the PE console server.

    (Example: puppet-access --service-url

  • -c, --config-file: Changes the location of your configuration file.

    (Default: ~/.puppetlabs/puppet-access.conf)

  • -t, --token-file: Changes the location of the file that the token is stored in.

    (Default: ~/.puppetlabs/token)

Security best practices for using token authentication

  1. Store credentials with care

    • Restrict access to files that store tokens or certificates. Make sure only people who should be using those credentials can read the files.

    • Don’t save your password, especially not in a script.

  2. Don’t accidentally expose credentials

    • If you use query parameters for your tokens (when using Code Manager, for example), unencrypted passwords can get logged by various tools.

    • In Puppet Access, your password is output when you log in using the debug flag.

  3. Using cURL -k

    If you are using cURL with the -k insecure SSL connection option, keep in mind that you are vulnerable to a person-in-the-middle attack.

  4. Revoke or remove external directory users

    If a remote user generates a token and then is deleted from your external directory service, the deleted user cannot log into the console. However, since the token has already been authenticated, the RBAC service does not contact the external directory service again when the token is used in the future. To fully remove the token’s access, you need to manually revoke or delete the user from PE.

↑ Back to top