Password endpoints

When local users forget passwords or lock themselves out of Puppet Enterprise (PE) by attempting to log in with incorrect credentials too many times, you must generate a password reset token for them. The password endpoints enable you to generate password reset tokens for a specific local user or get a single-use token that has a temporary password in the body.

Tip: You can also reset the PE console admin password using a password reset script available on the PE console node.
Tip: By default, users can make 10 login attempts before being locked out. You can change the allowed number of attempts by configuring the failed-attempts-lockout parameter.

POST /users/<id>/password/reset

Generates a single-use, time-limited password reset token for the specified local user. Authentication is required.

Request format

Example curl request:
curl -k -X POST \
-H "X-Authentication: $(puppet access show)" \
"https://$(puppet config print server):4433/rbac-api/v1/users/297f1d72-d96e-4d61-9519-e44465e00319/password/reset"

Response format

Returns 200 OK with the new token, such as AOsATK53e_M2Ltfy_qum5mAjlO-GAXs3c82k7P1kf1_y. Give this token to the appropriate user to use with POST /auth/reset.
Note: Password reset tokens can only be used once, and tokens have a limited lifetime. The lifetime is based on the value of puppet_enterprise::profile::console::rbac_password_reset_expiration, where the value indicates the number of hours tokens are valid. The default value is 24 hours.

Error responses

Returns 403 Forbidden if the user does not have permissions to create a reset path for the specified user or if the specified user is a remote user.

Returns 404 Not Found if a user with the given identifier does not exist.

POST /auth/reset

Resets a local user's password using a single-use token, obtained from POST /users/<id>/password/reset, with the new password in the body. Authentication is not required.

Request format

You must provide the token obtained from POST /users/<id>/password/reset and the desired new password. For example:
{"token": "<token from POST /users/<id>/password/reset>",
 "password":"yournewpassword"}
You do not need to identify the user, because the user is identified in the token's payload. This endpoint does not establish a valid logged-in session for the user.
Example curl request:
curl -k -X POST -H 'Content-Type: application/json' \
-H "X-Authentication: $(puppet access show)" \
-d '{ "token": "0FlAtJ-84LMswcyzC8h9c2Hkreq1l4W6UeWKJJScYUUk", "password": "puppetlabs" }' \
"https://$(puppet config print server):4433/rbac-api/v1/auth/reset"

Response format

Returns 200 OK if the token is valid and the password was successfully changed.

Error responses

Returns 403 Forbidden if the token was already used or is no longer active. Password reset tokens can only be used once, and tokens have a limited lifetime. The lifetime is based on the value of puppet_enterprise::profile::console::rbac_password_reset_expiration, where the value indicates the number of hours tokens are valid. The default value is 24 hours.

PUT /users/current/password

Changes the current local user's password. You must provide the current password in the request. Authentication is required.

Request format

Your request must include both the current password and the desired new password. For example:
{"current_password": "somepassword",
 "password": "somenewpassword"}
Example curl request:
curl -k -X PUT -H 'Content-Type: application/json' \
-H "X-Authentication: $(puppet access show)" \
-d '{ "current_password": "puppetlabs", "password": "password" }' \
"https://$(puppet config print server):4433/rbac-api/v1/users/current/password"

Response format

Returns 204 No Content if the password was successfully changed.

Error response

Returns 403 Forbidden if the user is a remote user or if current_password doesn't match the current password stored for the user. The message in the response body specifies the cause of the failure.

POST /command/validate-password

Check whether a password is valid. Authentication is required.

Request format

You must provide a password to validate for compliance. Optionally, when using certificate authentication, you can provide a password reset-token to identify the user for password validation. Both keys must be strings.

Requests with authentication tokens in the headers, such as x-authentication, must use this format:
{ "password": <password here>}
Requests with a certificate on the allowlist and a password reset token must use this format:
{
   "password": <password here>,
   "reset-token": <reset token> 
}
Example curl request:
curl -k -X POST -H 'Content-Type: application/json' \
-H "X-Authentication: $(puppet access show)" \
-d '{ "password": "password" }' \
"https://$(puppet config print server):4433/rbac-api/v1/command/validate-password"

Response format

If the password is valid, the endpoint returns 200 OK and { "valid": true }.

If the password isn’t valid, the endpoint returns 200 OK and information about why the password is not valid. For example:
{
  "valid": false,
  "failures": [
    {
      "rule-identifier": "letters-required", 
      "friendly-error": "Passwords must have at least 2 letters."
    }
  ]
}

If the request has formatting issues, the endpoint returns 400 Bad Request.

POST /command/validate-login

Check whether a username (login) is valid. Authentication is required.

Request format

You must provide a login (username), as a string, to validate for compliance.

Example curl request:
curl -k -X POST -H 'Content-Type: application/json' \
-H "X-Authentication: $(puppet access show)" \
-d '{ "login": "1" }' \
"https://$(puppet config print server):4433/rbac-api/v1/command/validate-login"

Response format

If the login is valid, the endpoint returns 200 OK and { "valid": true }.

If the login is invalid, the endpoint returns 200 OK and information about why the username is not valid. For example: 
{
  "valid": false,
  "failures": [
    {
      "rule-identifier": "login-minimum-length",
      "friendly-error": "The login for the user must be a minimum of 3 characters."
    }
  ]
}

If the request has formatting issues, the endpoint returns 400 Bad Request.