Token endpoints
Sections
Authentication tokens can control a user's access to PE services. Users can generate
their own authentication tokens using the token
endpoint.
Token keys
The following keys are used with the token
endpoint.
Key | Explanation |
---|---|
login |
The user's login for the PE console (required). |
password |
The user's password for the PE console (required). |
lifetime |
The length of time the token is active before expiration (optional). |
description |
Additional metadata about the requested token (optional). |
client |
Additional metadata about the client making the token request (optional). |
label |
A user-defined label for the token (optional). |
The lifetime key
When setting a token's lifetime, specify
a numeric value followed by y
(years), d
(days), h
(hours), m
(minutes), or s
(seconds). For example, a value of 12h
is 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. If
you do not want the token to expire, set the lifetime to 0
. Setting it to zero gives the token a lifetime of
approximately 10 years.
The label key
You can choose a label for the token that can be used with other RBAC token endpoints. Labels:
- Must be no longer than 200 characters.
- Must not contain commas.
- Must contain something other than whitespace. (Whitespace is trimmed from the beginning and end of the label, though it is allowed elsewhere.)
- Must not be the same as a label for another token for the same user.
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.
POST /auth/token
Generates an access token for the user whose login information is posted. This token
can then be used to authenticate requests to Puppet Enterprise (PE)
services using either the X-Authentication
header or the
token
query parameter.
This route is intended to require zero authentication. While HTTPS is still required (unless PE is explicitly configured to permit HTTP), neither an allowed cert nor a session cookie is needed to post to this endpoint.
Request format
Accepts a JSON object or curl command with the user's login and password information. You can include the token's lifetime, a user-specified label, and additional metadata, but these are not required.
{"login": "jeanjackson@example.com",
"password": "1234",
"lifetime": "4m",
"label": "personal workstation token"}
Copied!
type_header='Content-Type: application/json'
cacert="$(puppet config print cacert)"
uri="https://$(puppet config print server):4433/rbac-api/v1/auth/token"
data='{"login": "<USER>",
"password": "<PASSWORD>",
"lifetime": "4h",
"label": "four-hour token"}'
curl --header "$type_header" –cacert "$cacert" --request POST "$uri" --data "$data"
Copied!
See Usage notes for curl examples for information about forming curl commands.
-
--header 'Content-Type: application/json'
: sets theContent-Type
header toapplication/json
, which indicates to RBAC that the data being sent is in JSON format. -
--cacert [FILE]
: Specifies a CA certificate as described in Forming requests for the node classifier. Alternatively, you could use the--insecure
flag to turn off SSL verification of the RBAC server so that you can use the HTTPS protocol without providing a CA cert. 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: We used the--insecure
flag only as an example. Use your own discretion when choosing the appropriate server verification method for the tool you are using. -
--request POST
: This is an HTTP POST request to provide your login information to the RBAC service. -
https://<HOSTNAME>:<PORT>/rbac-api/v1/auth/token
: Sends the request to thetoken
endpoint. ForHOSTNAME
, 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." ForPORT
, provide the port that the PE services (node classifier service, RBAC service, and activity service) listen on. The default port is4433
. -
--data '{"login": "<USER>", "password": "<PASSWORD>", "lifetime": "4h", "label": "four-hour token"}'
: Provide the user name and password that you use to log in to the PE console. Optionally, set the token's lifetime and label.
curl POST 'https://$(puppet config print server):4433/rbac-api/v1/auth/token' \
-H "X-Authentication: 0F4DITVB7HP3z8YnD95kx1W1jY0z5Pnc3ixB5uGAXzLY" \
-H "Content-type: application/json" \
-d '{"login": "test",
"password": "Test123!",
"lifetime": "4m",
"label": "personal workstation token"}'
Copied!
Response format
If the credentials are good and the user is not revoked, the endpoint returns 200
OK and a token, such as {"token":"0QX-WR3kgP0R9C2dA0I2nfnp0QgAT95_xH3iylBhqroA"}
.
Error responses
Returns 401 Unauthenticated if the credentials are bad or the user is revoked.
Returns 400 Malformed if something is wrong with the request body.
POST /tokens
Create a new token with a custom lifetime, client specification, and description. Cannot be used with certificate authentication.
Request format
Key | Definition |
---|---|
lifetime |
Required string specifying the lifetime of the token in the
<whole-number> form, with
one of (s ,m ,d ,y ). Use s for seconds, m
for minutes, d for days, and
y for years. for example,
5m is 5 minutes. |
client |
Required string specifying a human readable description of
the creator of the token. For example, PE
console . |
description |
Optional string specifying a human readable description of the token. |
curl POST 'https://$(puppet config print server):4433/rbac-api/v1/tokens' \
-H "X-Authentication: 0F4DITVB7HP3z8YnD95kx1W1jY0z5Pnc3ixB5uGAXzLY" \
-H "Content-type: application/json" \
-d '{"lifetime": "1y",
"description": "A token to be used with joy and care.",
"client": "PE console"}'
Copied!
Response format
If the authentication token is valid, not expired, and the user is not revoked, the
endpoint returns 200 OK and the token, such as {"token":"0BlGnGHqZKb1Rwh3rcLoHr-Ghnw_PG-l7VD1LvK8obZ4"}
.
Returns standard RBAC errors when the user doesn't exist, is revoked, and so on.