Passwords endpoints
When local users forget their Puppet Enterprise (PE) passwords
or lock themselves out of PE by attempting to log in with
incorrect credentials too many times, you must generate a password reset token for them. Use
the password endpoints to generate password reset tokens, use tokens to
reset passwords, change the authenticated user's password, and validate potential user names
and passwords.
password endpoints are for
managing local user accounts within PE. You can't use
these endpoints to modify user information in SAML or LDAP.failed-attempts-lockout parameter.You can reset the PE console admin password with a password reset script available on the PE console node.
POST /users/<uuid>/password/reset
Generate a single-use, limited-lifetime password reset token for a specific local user. Authentication is required.
Request format
curl -X POST "https://$(puppet config print server):4433/rbac-api/v1/users/297f1d72-d96e/password/reset" \
-H "X-Authentication:$(puppet-access show)"Response format
rbac_password_reset_expiration parameter. The
default is 24 hours. For more information, refer to Configure RBAC and token-based authentication settings.Error responses
- The requesting user does not have permission to create a reset token for the specified user.
- The specified user is a remote user. You must manage remote user information within the relevant remote system, such as SAML or LDAP.
Returns 404 Not Found if there is no user with the given UUID.
For other error responses, refer to RBAC service errors.
POST /auth/reset
Use a password reset token to change a local user's password. Authentication is not required.
Request format
application/json. The body must be a JSON object using the
following keys:-
token: A password reset token obtained from the POST /users/<uuid>/password/reset endpoint. -
password: A new password to assign to the user attached to the password reset token.
Authentication is not required.
curl -X POST "https://$(puppet config print server):4433/rbac-api/v1/auth/reset" \
-H "Content-type: application/json" \
-d '{"token": "0FlAtJ-84LMswcyzC8h9c2Hkreq1l4W6UeWKJJScYUUk",
"password":"W3lcome!"}'The body doesn't explicitly identify the user, because the user is identified through the password reset token.
Response format
Returns 200 OK if the password reset token is valid and the password was successfully changed. The user can now log in with the new password.
This endpoint only resets the password; it does not establish a valid log-in session for the user.
Error responses
rbac_password_reset_expiration parameter. The default is 24
hours. For more information, refer to Configure RBAC and token-based authentication settings.For other errors, refer to RBAC service errors.
PUT /users/current/password
Changes the current authenticated local user's password. You must provide the current password in the request. Authentication is required.
Request format
application/json. The body must be a JSON object using the
following keys:-
current_password: The authenticated user's current password. -
password: A new password to assign to the authenticated user.
Authentication is required.
curl -X POST "https://$(puppet config print server):4433/rbac-api/v1/users/current/password" \
-H "Content-type: application/json" \
-H "X-Authentication: $(puppet access show)" \
-d '{"current_password": "old_password",
"password": "new_password"}'The body doesn't explicitly identify the user, because the user is identified through authentication.
Response format
Returns 204 No Content if the password was successfully changed. You can now log in with the new password.
This endpoint only resets the password; it does not establish a valid log-in session.
Error response
Returns 403 Forbidden if the authenticated user is a remote user or if
current_password doesn't match the user's stored password.
For other errors, refer to RBAC service errors.
POST /command/validate-password
Check whether a password is valid. Authentication is required.
Request format
application/json. The body must be a JSON object
using one or both of these keys:-
password: A password string to validate for compliance with password format and complexity requirements. -
reset-token: If your request uses certificate authentication, you can provide a password reset token to identify the user for password validation. You can get password reset tokens from the POST /users/<uuid>/password/reset endpoint. Otherwise you can use token-based authentication (as an X-Authentication header) to identify the relevant user.
{ "password": <password>}{
"password": <password>,
"reset-token": <reset_token>
}curl -X POST "https://$(puppet config print server):4433/rbac-api/v1/command/validate-password" \
-H 'Content-Type: application/json' \
-H "X-Authentication: $(puppet access show)" \
-d '{ "password": "password" }'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."
}
]
}If the request has formatting issues, the endpoint returns 400 Bad Request.
For other errors, refer to RBAC service errors.
POST /command/validate-login
Check whether a user name (login) is valid.
Authentication is required.
Request format
application/json. The body must be a JSON object
containing the login key, which specifies the user
name to validate. For
example:curl -X POST "https://$(puppet config print server):4433/rbac-api/v1/command/validate-login" \
-H 'Content-Type: application/json' \
-H "X-Authentication: $(puppet-access show)" \
-d '{ "login": "1" }'Response format
If the user name 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."
}
]
}If the request has formatting issues, the endpoint returns 400 Bad Request.
For other errors, refer to RBAC service errors.