Puppet Enterprise users generate tokens to authenticate their access to certain PE command-line tools and API endpoints. Authentication tokens are tied to the permissions granted to the user through RBAC, and provide the user with the appropriate access to HTTP requests.
Authentication tokens manage access to the following PE services:
- Puppet orchestrator
- Code Manager
- Node classifier
- Role-based access control (RBAC)
- Activity service
You can generate tokens with the puppet-access
command or with the API endpoint.
Generate a token using puppet-access
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.
Install the PE client tools package and configure puppet-access
.
You can continue to use this token until it expires, or until your access is revoked. The token has the exact same set of permissions as the user that generated it.
--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.Generate 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.
Install the PE client tools package and configure puppet-access
.
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.
Configuring 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 Puppet master.
The configuration file for puppet-access
allows you to 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'll need a global configuration file and a user-specified configuration file.
-
A global configuration file at:
-
nix ---
/etc/puppetlabs/client-tools/puppet-access.conf
- Windows ---
C:/ProgramData/PuppetLabs/client-tools/puppet-access.conf
This global configuration file is created by Puppet Enterprise for PE-managed machines only. 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"
}
PE will add the service-url setting.
If you're running puppet-access
from a non-managed workstation, you will need to create the global file and populate it with the configuration file settings.
- A user-specified configuration file at
~/.puppetlabs/client-tools/puppet-access.conf
(for both *nix and Windows), which you will need to create and populate with the configuration file settings.
Important: User-specified configuration files must be in JSON format; HOCON and INI-style formatting are not supported.
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 settings will prevail.
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, this 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"
}
PE will determine and add 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 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. You must create the user-specified file and populate it with the configuration file settings. A list of configuration file settings is found in the next section.
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 settings will prevail.
Configuration file settings for puppet-access
As needed, you can manually add configuration settings to your user-specified or global puppet-access
configuration file.
The class that manages the global configuration file is puppet_enterprise::profile::controller
.
You can also change configuration settings by specifying flags when using the puppet-access
command in the command line.
Setting | Description | Command line flag |
---|---|---|
token-file
| The location for storing authentication tokens. Defaults to ~/.puppetlabs/token . | -t , --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 , --config-file |
service-url
| The URL for your RBAC API. Defaults to the URL automatically determined during the client tools package installation process, generally https://<CONSOLE HOSTNAME>:4433/rbac-api . You typically only need to change this if you are moving the console server. |
--service-url
|
Generate a token using the API endpoint
The RBAC v1 API includes a token endpoint, which allows you to generate a token using curl commands.
You can continue to use this token until it expires, or until your access is revoked. The token has the exact same set of permissions as the user that generated it.
Use a token with the PE API endpoints
The example below shows how to use a token in an API request. In this example, you'll use the /users/current
endpoint of the RBAC v1 API to get information about the current authenticated user.
export TOKEN=<PASTE THE TOKEN HERE>
.curl -k -X GET https://<HOSTNAME>:4433/rbac-api/v1/users/current -H "X-Authentication:$TOKEN"
The command 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 specifying the request as follows: curl -k -X GET https://<HOSTNAME>:4433/rbac-api/v1/users/current?token=$TOKEN
-k
insecure SSL connection option, keep in mind that you are vulnerable to a person-in-the-middle attack.Change the token's default lifetime
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.
Setting a token-specific lifetime
Tokens have a default lifetime of five minutes, but you can set a different lifetime for your token when you generate it. This allows you to keep one token for multiple sessions.
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.
Use the --lifetime
parameter if using puppet-access
to generate your token. For example: puppet-access login --lifetime 1h
.
Use the lifetime
value if using the RBAC v1 API to generate your token. For example: {"login": "<YOUR PE USER NAME>", "password": "<YOUR PE PASSWORD>", "lifetime": "1h"}
.
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 allow you to more readily refer to your token when working with RBAC API endpoints, or when revoking your own token.
Token labels are assigned on a per-user basis: two users can each 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.
token
endpoint of the RBAC API, using the label
value to specify the name of your token.{"login": "<YOUR PE USER NAME>", "password": "<YOUR PE PASSWORD>", "label": "Ava's token"}
Revoking a token
Revoke tokens by username, label, or full token 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 by username, label, or full token, and may also revoke any other full 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.
Delete a token file
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.
Deleting the token file prevents other users from using your authentication token, but does not actually revoke the token. Once the token has expired, there's no risk of obtaining the contents of the 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 <YOUR TOKEN PATH>
.
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.
- In the console, click Access control > Users. Click the full name of the user you are interested in.
- Click the Activity tab.