Token-based authentication

Use puppet-access to generate an authentication tokens from the command line of any workstation (Puppet-managed or not), without the need to SSH into the Puppet master.

1. Choose one of the following options, depending on how long you need your token to last:

   • To generate a token with the default five-minute lifetime, run puppet-access login.

   • To generate a token with a specific lifetime, run puppet-access login --lifetime <TIME PERIOD>.

     For example, puppet-access login --lifetime 5h generates a token that lasts five hours.

2. When prompted, enter the same username and password that you use to log into the PE console.
   The puppet-access command contacts the token endpoint in the RBAC v1 API. If your login credentials are correct, the RBAC service generates a token.
3. The token is generated and stored in a file for later use. The default location for storing the token is ~/.puppetlabs/token. You can print the token at any time using puppet-access show.

The RBAC v1 API includes a token endpoint, which allows you to generate a token using curl commands.

1. On 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 command returns a JSON object containing the key token and the token itself.

   CAUTION: If you are using curl commands with the -k insecure SSL connection option, keep in mind that you are vulnerable to a person-in-the-middle attack.
2. Save the token. Depending on your workflow, either:

   • Copy the token to a text file.

   • Save the token as an environment variable using export TOKEN=<PASTE THE TOKEN HERE>.

The example below shows how to use a token in an API request. In this example, you use the /users/current endpoint of the RBAC v1 API to get information about the current authenticated user.

Tokens have a default authentication lifetime of five minutes, but this default value can be adjusted in the console. You can also change a token's maximum authentication lifetime, which defaults to 10 years.

1. In the console, click Classification.
2. Open the PE Infrastructure node group and click the PE Console node group.
3. On the Configuration tab, find the puppet_enterprise::profile::console class.
4. In the Parameter field, select rbac_token_auth_lifetime to change the default lifetime of all tokens, or rbac_token_maximum_lifetime to adjust the maximum allowable lifetime for all tokens.
5. In the Value field, enter the new default authentication lifetime.
   Specify a numeric value followed by "y" (years), "d" (days), "h" (hours), "m" (minutes), or "s" (seconds). For example, "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.

   The rbac_token_auth_lifetime cannot exceed the rbac_token_maximum_lifetime value.

6. Click Add parameter, and commit changes.

You can affix a plain-text, user-specific label to tokens you generate with the RBAC v1 API. Token labels allow you to more readily refer to your token when working with RBAC API endpoints, or when revoking your own token.

If you logged into puppet-access 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.

Token activity is logged by the activity service. You can see recent token activity on any user's account in the console.

1. In the console, click Access control > Users. Click the full name of the user you are interested in.
2. Click the Activity tab.