Password endpoints
Sections
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.
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
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"
Copied!Response format
AOsATK53e_M2Ltfy_qum5mAjlO-GAXs3c82k7P1kf1_y. Give this token to the
appropriate user to use with POST /auth/reset.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
{"token": "<token from POST /users/<id>/password/reset>",
"password":"yournewpassword"}Copied!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"Copied!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
{"current_password": "somepassword",
"password": "somenewpassword"}Copied!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"Copied!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.
{ "password": <password here>}Copied!{
"password": <password here>,
"reset-token": <reset token>
}Copied!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"Copied!Response format
If the password is valid, the endpoint returns 200 OK and { "valid": true }.
{
"valid": false,
"failures": [
{
"rule-identifier": "letters-required",
"friendly-error": "Passwords must have at least 2 letters."
}
]
}Copied!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.
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"Copied!Response format
If the login is valid, the endpoint returns 200 OK and { "valid": true }.
{
"valid": false,
"failures": [
{
"rule-identifier": "login-minimum-length",
"friendly-error": "The login for the user must be a minimum of 3 characters."
}
]
}Copied!If the request has formatting issues, the endpoint returns 400 Bad Request.