Token-based authentication

Authentication tokens allow a user to enter their credentials once, then receive an alphanumeric token to use to access different services or parts of the system infrastructure. Authentication tokens are tied to the permissions granted to the user through role-based access control (RBAC), and they provide the user with the appropriate access to HTTP requests.

Authentication tokens manage access to these Puppet Enterprise (PE) services:
  • Activity service
  • Code Manager
  • Node classifier
  • PuppetDB
  • Puppet orchestrator
  • RBAC

You can generate authentication tokens using the PE console, the puppet-access command, or the RBAC API v1 Tokens endpoints. You can also generate one-off tokens that do not need to be saved, which are typically used by a service.

In the PE console, you can view or revoke your own tokens on the Tokens tab of the My account page. Administrators can view and revoke tokens for other users on the User details page. You can also Configure RBAC and token-based authentication settings in the PE Infrastructure node group.

Configure puppet-access

The puppet-access command allows users to generate and manage authentication tokens from the command line of any workstation (Puppet-managed or not), without the need to SSH into the primary server. If you want to use puppet-access, ensure it is configured correctly before using it to generate authentication tokens.

The configuration file for puppet-access allows you to define default settings so that you can generate tokens from the CLI without having to pass additional flags.

Whether you are running puppet-access on a PE-managed server or installing it on a separate work station, you need a global configuration file and a user-specified configuration file.

Global configuration file

The global configuration file is located at:

  • On *nix systems: /etc/puppetlabs/client-tools/puppet-access.conf
  • On Windows systems: C:/ProgramData/PuppetLabs/client-tools/puppet-access.conf
On machines managed by Puppet Enterprise (PE), the global configuration file is created for you. The configuration file is formatted in JSON. For example:
{
    "service-url": "https://<CONSOLE_HOSTNAME>:4433/rbac-api",
    "token-file": "~/.puppetlabs/token",
    "certificate-file": "/etc/puppetlabs/puppet/ssl/certs/ca.pem"
}
Tip: PE determines and populates the service-url setting.

If you're running puppet-access from a workstation not managed by PE, you must create the global file and populate it with the required configuration file settings.

User-specified configuration file

The user-specified configuration file is located at ~/.puppetlabs/client-tools/puppet-access.conf for both *nix and Windows systems.

The user-specified configuration file always takes precedence over the global configuration file. For example, if the two files have contradictory settings for the token-file, the user-specified setting prevails.

You must create the user-specified file and populate it with the configuration file settings. A list of configuration file settings is found in Configuration file settings for puppet-access.

Important: User-specified configuration files must be in JSON format. HOCON and INI-style formatting are not supported.

Configuration file settings for puppet-access

You can manually add or edit configuration settings in your user-specified or global puppet-access configuration files.

The class that manages the global configuration file is: puppet_enterprise::profile::controller

You can also change configuration settings by specifying flags when you Generate a token using puppet-access on the command line.

Setting Description Command line flag
token-file The location for storing authentication tokens. Defaults to: ~/.puppetlabs/token -t or --token-file
certificate-file The location of the CA that signed the console-services server's certificate. Defaults to the PE CA cert location: /etc/puppetlabs/puppet/ssl/certs/ca.pem --ca-cert
config-file Changes the location of your configuration file. Defaults to: ~/.puppetlabs/client-tools/puppet-access.conf -c or --config-file
service-url The URL for your RBAC API. Defaults to the URL automatically determined during the client tools package installation process, which is usually: https://<CONSOLE_HOSTNAME>:4433/rbac-api

Usually, you need to change this only if you are moving your console server.

 --service-url

Generate a token in the console

Use the console to generate an authentication token that you can use to access PE APIs. If SAML is configured, you must have a token to use CLI tools, such as orchestrator jobs or PuppetDB queries triggered from the command line. Generate and export a token to the machine you want to run the CLI tool on.

  1. In the console, on the My account page, click the Tokens tab.
  2. Click Generate new token.
  3. Under Description, enter a description for your new token.
  4. Under Lifetime, select the length of time you want your token to be good for.
  5. Click Get token.
  6. Click Copy token.
    Important: Store the token somewhere secure and do not share it with others. You cannot regenerate this token again once you close this page.
  7. Click Close.

Generate a token using puppet-access

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

Before you begin
Install the PE client tools package and Configure puppet-access.
For information about modifying commands for Windows and privilege escalation, refer to Using example commands and Commands with elevated privileges.
  1. Choose one of the following options, depending on how long you need your token to last:
    • To generate a token with the default one-hour lifetime, run:
      sudo puppet-access login
    • To generate a token with a specific lifetime, run:
      sudo puppet-access login --lifetime <TIME_PERIOD>
      For example, to generate a token that lasts five hours, run: 
      puppet-access login --lifetime 5h
  2. When prompted, enter the user name and password that you use to log into the PE console.
Results

The puppet-access command uses RBAC API v1 Tokens endpoints. If your login credentials are correct, the RBAC service generates a token.

The token is generated and stored in a file for later use. The default token storage location is ~/.puppetlabs/token. You can print the token at any time, such as in curl commands, by using puppet-access show.

You can continue to use this token until it expires, or until your access is revoked. The token has the same permissions as the user that generated it.

CAUTION: If you run the login command with the --debug flag, the client outputs the token, as well as the username and password. For security reasons, exercise caution when using the --debug flag with the login command.
Important: If a remote user generates a token, and the user is then deleted from your external directory service, the deleted user cannot log into the console. However, because 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.

Generate a token using the RBAC API

The RBAC API v1 /auth/token endpoint allows you to generate a token.

  1. Call the POST /auth/token or POST /tokens endpoint.
  2. Save the token by:
    • Copying the token to a text file.
    • Saving the token as an environment variable using: export TOKEN=<TOKEN>
Results

You can use the token until it expires, or until your access is revoked. The token has the same permissions as the user associated with it.

Important: If a remote user generates a token, and that user is then deleted from your external directory service, the deleted user cannot log into the Puppet Enterprise (PE) console. However, because 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 prevent the user from accessing the system through the token, you need to manually revoke or delete the user from PE.

Use a token with PE API endpoints

The example below shows how to use a token in an API endpoint request. For more information, refer to the documentation for the particular API or endpoint you want to use.

Before you begin
Generate a token using puppet-access login.
  1. Generate a token in the console, Generate a token using puppet-access, or Generate a token using the RBAC API.
  2. Supply the token in the endpoint using one of these methods (if necessary, replacing /etc/puppetlabs/puppet/ssl/certs/ca.pem with the correct path to your CA certificate file):
    • An X-Authentication header using puppet-access show to call a stored token:
      auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/rbac-api/v1/users/current"

curl --cacert "/etc/puppetlabs/puppet/ssl/certs/ca.pem" --header "$auth_header" "$uri"
    • An X-Authentication header with the token supplied in full:
      auth_header="X-Authentication: <TOKEN>"
uri="https://$(puppet config print server):4433/rbac-api/v1/users/current"

curl --cacert "/etc/puppetlabs/puppet/ssl/certs/ca.pem" --header "$auth_header" "$uri"
    • Appended as a query parameter:
      GET https://$(puppet config print server):4433/rbac-api/v1/users/current?token=<TOKEN>"

    For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

Generate a token for use by a service

If you need to generate a token that a Puppet Enterprise (PE) service can use, and the token doesn't need to be saved, use the --print option with the puppet-access command.

Before you begin
Install the PE client tools package and Configure puppet-access.
To generate a token for a service, run: 
sudo puppet-access login [username] --print

This command generates a token, and then displays the token content as stdout (standard output) rather than saving it to disk.

Tip: When generating a token for a service, consider specifying a longer token lifetime so that you don't have to regenerate the token too frequently.

For information about modifying commands for Windows and privilege escalation, refer to Using example commands and Commands with elevated privileges.

View token activity

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, on theAccess control page, click the Users tab and select the full name of the user you are interested in.
  2. Click the Activity tab.

Change the default token lifetime

Tokens have a default authentication lifetime of one hour, but this default value can be adjusted in the console. You can also change the maximum permitted lifetime, which defaults to 10 years.

  1. In the console, click Node groups.
  2. Open the PE Infrastructure node group and click the PE Console node group.
  3. On the Classes tab, find the puppet_enterprise::profile::console class.
  4. In the Parameter field, select the parameter you want to adjust:
    • rbac_token_auth_lifetime: Set the default token lifetime. The default is one hour.
    • rbac_token_maximum_lifetime: Set the maximum allowable lifetime for all tokens. The default is 10 years.
  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)
    • s (seconds)
    For example, 12h sets the lifetime to 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 (s).

    The rbac_token_auth_lifetime cannot exceed the rbac_token_maximum_lifetime value.

  6. Click Add parameter, and commit changes.

Set a token-specific lifetime

If you want a token to have a different lifetime than the default lifetime, you can set a different lifetime when you generate the token. This allows you to keep one token for multiple sessions.

If you Generate a token using puppet-access, use the --lifetime option. For example: puppet-access login --lifetime 2h generates a token with a two-hour lifetime.

If you're using the POST /auth/token endpoint, use the lifetime key. For example, this JSON body specifies a token lifetime of two hours:
{"login": "<YOUR PE USER NAME>", "password": "<YOUR PE PASSWORD>", "lifetime": "2h"}
Format the lifetime as a numeric value followed by one of the following:
  • y (years)
  • d (days)
  • h (hours)
  • m (minutes)
  • s (seconds)
For example, 12h sets the lifetime to 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 (s).

To set the maximum possible lifetime, set the lifetime to 0. This sets the lifetime to the value of rbac_token_maximum_lifetime. The default value for this setting is 10 years.

If omitted, tokens get the default lifetime, which is one hour, unless you Change the default token lifetime.

Set a token-specific label

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

To generate a token with a label, use the label key in requests to the POST /auth/token endpoint. The value of the label key becomes the token's label. For example: 
{"login": "<YOUR_PE_USER_NAME>",
 "password": "<YOUR_PE_PASSWORD>",
 "label": "My token"}
Labels:
  • Can't have more than 200 characters.
  • Can't contain commas.
  • Can't contain only spaces.

Whitespace is allowed within the label string; however, leading and trailing whitespace is trimmed. For example, " my token label " becomes "my token label".

Token labels are assigned on a per-user basis. This means two users can both have a token labelled my token, but a single user cannot have two tokens both labelled my token.

You cannot use labels to refer to other users’ tokens.

Revoke a token using the API

Revoke tokens by username, label, or full token with the DELETE /tokens endpoint.

All token revocation attempts are logged in the activity service, and they can be viewed on the user's Activity tab in the console.

You can revoke your own token by username, label, or full token.

You can also revoke any other full token you possess.

Users with the permission to revoke other users access can also revoke those users' tokens, because the users:disable permission includes token revocation. Revoking users' tokens does not revoke the users' PE accounts. If a user's account is revoked, all tokens associated with that user account are also automatically revoked.

Revoke a token in the console

Revoke your tokens on the My Account page in the console. Administrators can also revoke other users' tokens.

Administrators can revoke another user's token on the User details page.

To revoke your own token:

  1. In the console, on the My account page, click the Tokens tab.
  2. Find the token you want to revoke and click Revoke token.

Delete a token file

If you used puppet-access to generate a token, you can remove the token file by running the delete-token-file action. This is useful if you are working on a server that is used by multiple people.

Deleting the token file prevents other users from using your authentication token, but does not revoke the token. After the token has expired, there's no risk of obtaining the contents of the token file.
From the command line, run one of the following commands, depending on the path to your token file:
  • If your token is at the default token file location, run:
    puppet-access delete-token-file
  • If you used a different path to store your token file, run:
    puppet-access delete-token-file --token-path <TOKEN_PATH>