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.

Important: The password endpoints are for managing local user accounts within PE. You can't use these endpoints to modify user information in SAML or LDAP.
Tip: By default, users can make 10 login attempts before being locked out. You can change the amount of allowed attempts by configuring the 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

When Forming RBAC API requests to this endpoint, provide authentication and specify a user ID, such as:
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

A successful request returns 200 OK and the new token. Use this token with POST /auth/reset to reset the user's password.
Restriction: Password reset tokens can be used only once, and these tokens have a limited lifetime. The lifetime is based on the value of the rbac_password_reset_expiration parameter. The default is 24 hours. For more information, refer to Configure RBAC and token-based authentication settings.

Error responses

Returns 403 Forbidden if:
  • 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

When Forming RBAC API requests to this endpoint, the content type is 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.

For example:
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

Returns 403 Forbidden if the password reset token was already used or has expired.
Remember: Password reset tokens can be used only once, and these tokens have a limited lifetime. The lifetime is based on the value of the 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

When Forming RBAC API requests to this endpoint, the content type is 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.

For example:
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

When Forming RBAC API requests to this endpoint, the content type is 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.
Use this body format for a token-authenticated request:
{ "password": <password>}
Use this body format is for a certificate-authenticated request:
{
 "password": <password>,
 "reset-token": <reset_token> 
}
For example, this request uses token-based authentication to identify a user:
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 }.

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.

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

When Forming RBAC API requests to this endpoint, the content type is 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 }.

If the user name 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.

For other errors, refer to RBAC service errors.