Forming RBAC API requests


Token-based authentication is required to access the RBAC API. You can authenticate requests by using either user authentication tokens or whitelisted certificates.

By default, the RBAC service listens on port 4433. All endpoints are relative to the /rbac-api/ path. So, for example, the full URL for the /v1/users endpoint on localhost is https://localhost:4433/rbac-api/v1/users.

Authentication using tokens

Insert a user authentication token in an RBAC API request.

  1. Generate a token: puppet-access login
  2. Print the token and copy it: puppet-access show

  3. Save the token as an environment variable: export TOKEN=<PASTE THE TOKEN HERE>
  4. Include the token variable in your API request:
auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/rbac-api/v1/users/current"

curl --insecure --header "$auth_header" "$uri"

The example above uses the X-Authentication header to supply the token information. In some cases, such as GitHub webhooks, you might need to supply the token in a token parameter. To supply the token in a token parameter, specify the request as follows:

uri="https://$(puppet config print server):4433/rbac-api/v1/users/current?token=$(puppet-access show)"

curl --insecure "$uri"
CAUTION: Be aware when using the token parameter method that the token parameter might be recorded in server access logs.

Authentication using whitelisted certificate

You can also authenticate requests using a certificate listed in RBAC's certificate whitelist, located at /etc/puppetlabs/console-services/rbac-certificate-whitelist. Note that if you edit this file, you must reload the pe-console-services service (run sudo service pe-console-services reload) for your changes to take effect.

Attach the certificate using the command line, as demonstrated in the example curl query below. You must have the whitelisted certificate name (which must match a name in the /etc/puppetlabs/console-services/rbac-certificate-whitelist file) and the private key to run the script.

cert="$(puppet config print hostcert)"
cacert="$(puppet config print localcacert)"
key="$(puppet config print hostprivkey)"
uri="https://$(puppet config print server):4433/rbac-api/v1/users/current"

curl --cert "$cert" --cacert "$cacert" --key "$key" "$uri"

You do not need to use an agent certificate for authentication. You can use puppet cert generate to create a new certificate specifically for use with the API.

Content-type headers in the RBAC API

RBAC accepts only JSON payloads in PUT and POST requests.

If a payload is provided, it is important to specify that the content is in JSON format. Thus, all PUT and POST requests with non-empty bodies should have the Content-Type header set to application/json.

How helpful was this page?

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.