LDAP endpoints

Use the LDAP ds (directory service) endpoints to get information about your LDAP directory service, test your LDAP directory service connection, and replace LDAP directory service connection settings.

Tip: To connect to the directory service anonymously, set the Lookup user and Lookup password fields to null or leave them blank.

GET /ds (deprecated)

Get the connected directory service information. Authentication is required.

Important: The GET /v1/ds endpoint is deprecated. Instead, use the GET /v2/ds endpoint.

Request format

When Forming RBAC API requests to this endpoint, the request is a basic call with authentication, such as:
curl GET 'https://$(puppet config print server):4433/rbac-api/v1/ds' \
-H "X-Authentication:$(puppet-access show)"

Response format

Returns 200 OK with a JSON object representing the connection settings. For example:
{
  "help_link": "https://help.example.com",
  "ssl": true,
  "group_name_attr": "name",
  "password": <password>,
  "group_rdn": null,
  "connect_timeout": 15,
  "user_display_name_attr": "cn",
  "disable_ldap_matching_rule_in_chain": false,
  "ssl_hostname_validation": true,
  "hostname": "ldap.example.com",
  "base_dn": "dc=example,dc=com",
  "user_lookup_attr": "uid",
  "port": 636,
  "login": "cn=ldapuser,ou=service,ou=users,dc=example,dc=com",
  "group_lookup_attr": "cn",
  "group_member_attr": "uniqueMember",
  "ssl_wildcard_validation": false,
  "user_email_attr": "mail",
  "user_rdn": "ou=users",
  "group_object_class": "groupOfUniqueNames",
  "display_name": "Acme Corp Ldap server",
  "search_nested_groups": true,
  "start_tls": false
}

Returns 200 OK with an empty JSON object ({ }) if the connection settings are not specified.

For information about each setting, refer to External directory settings.

For errors, refer to RBAC service errors.

GET /ds/test

Test the connection to the connected directory service. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the request is a basic call with authentication, such as:
curl GET 'https://$(puppet config print server):4433/rbac-api/v1/ds/test' \
-H "X-Authentication:$(puppet-access show)"

Response format

If the test is successful, the response is 200 OK and a JSON object containing the directory service connection settings. For example:
{
  "help_link": "https://help.example.com",
  "ssl": true,
  "group_name_attr": "name",
  "password": <password>,
  "group_rdn": null,
  "connect_timeout": 15,
  "user_display_name_attr": "cn",
  "disable_ldap_matching_rule_in_chain": false,
  "ssl_hostname_validation": true,
  "hostname": "ldap.example.com",
  "base_dn": "dc=example,dc=com",
  "user_lookup_attr": "uid",
  "port": 636,
  "login": "cn=ldapuser,ou=service,ou=users,dc=example,dc=com",
  "group_lookup_attr": "cn",
  "group_member_attr": "uniqueMember",
  "ssl_wildcard_validation": false,
  "user_email_attr": "mail",
  "user_rdn": "ou=users",
  "group_object_class": "groupOfUniqueNames",
  "display_name": "Acme Corp Ldap server",
  "search_nested_groups": true,
  "start_tls": false
}

For information about each setting, refer to External directory settings.

For errors, refer to RBAC service errors.

Error responses

Returns 400 Bad Request if the request is malformed.

Returns 401 Unauthorized if no user is authenticated.

Returns 403 Forbidden if the current user lacks permission to test the directory settings.

The error response also includes the elapsed time, such as {"elapsed": 20, "error": "..."}.

For other errors, refer to RBAC service errors.

PUT /ds/test

Tests a directory service connection based on supplied settings, rather than stored settings. 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 all directory service setting keys. For example:
curl PUT 'https://$(puppet config print server):4433/rbac-api/v1/ds/test' \
-H "X-Authentication: 0F4DITVB7HP3z8YnD95kx1W1jY0z5Pnc3ixB5uGAXzLY" \
-H "Content-type: application/json" \
-d '{"help_link": "https://help.example.com",
     "ssl": true,
     "group_name_attr": "name",
     "password": <password>,
     "group_rdn": null,
     "connect_timeout": 15,
     "user_display_name_attr": "cn",
     "disable_ldap_matching_rule_in_chain": false,
     "ssl_hostname_validation": true,
     "hostname": "ldap.example.com",
     "base_dn": "dc=example,dc=com",
     "user_lookup_attr": "uid",
     "port": 636,
     "login": "cn=ldapuser,ou=service,ou=users,dc=example,dc=com",
     "group_lookup_attr": "cn",
     "group_member_attr": "uniqueMember",
     "ssl_wildcard_validation": false,
     "user_email_attr": "mail",
     "user_rdn": "ou=users",
     "group_object_class": "groupOfUniqueNames",
     "display_name": "Acme Corp Ldap server",
     "search_nested_groups": true,
     "start_tls": false}
For information about each setting, refer to External directory settings.
Tip: If you have an LDAP connection configured, you can use the GET /ds endpoint to retrieve the current settings object and use it as a template for your PUT /ds/test request.

Response format

If the test succeeds, the endpoint returns a JSON object with information about the test, such as the amount of time the test ran. For example: {"elapsed": 10}

Error responses

If the test fails, the body contains the elapsed time and information about the failure: {"elapsed": 20, "error": "..."}.

For other errors, refer to RBAC service errors.

PUT /ds

Replace current directory service connection settings. You can update the settings or disconnect the service (by removing all settings). Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json.

To change the settings, the body must be a JSON object containing, at minimum, all required directory service setting keys.

Important: When changing any directory service settings, you must specify all required directory service settings in the request body, including required settings that you aren't changing. However, you don't need to specify optional settings unless you are changing them.

If you omit a required setting, the setting is removed or reset to the default value.

All External directory settings are required except help-link, login, password, user_rdn, and group_rdn. However, your specific LDAP configuration might require some of these fields, in which case you must treat those fields as required fields.

Here is an example curl request to change settings:
curl PUT 'https://$(puppet config print server):4433/rbac-api/v1/ds' \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"help_link": "https://help.example.com",
     "ssl": true,
     "group_name_attr": "name",
     "password": <password>,
     "group_rdn": null,
     "connect_timeout": 15,
     "user_display_name_attr": "cn",
     "disable_ldap_matching_rule_in_chain": false,
     "ssl_hostname_validation": true,
     "hostname": "ldap.example.com",
     "base_dn": "dc=example,dc=com",
     "user_lookup_attr": "uid",
     "port": 636,
     "login": "cn=ldapuser,ou=service,ou=users,dc=example,dc=com",
     "group_lookup_attr": "cn",
     "group_member_attr": "uniqueMember",
     "ssl_wildcard_validation": false,
     "user_email_attr": "mail",
     "user_rdn": "ou=users",
     "group_object_class": "groupOfUniqueNames",
     "display_name": "Acme Corp Ldap server",
     "search_nested_groups": true,
     "start_tls": false}

If you want to disconnect the directory service from PE, you can supply an empty object ({}) or set all required settings set to null.

Tip: If you have an LDAP connection configured, you can use the GET /ds endpoint to retrieve the current settings object and use it as a template for your PUT /ds request. This also helps avoid accidentally omitting a setting.

Searching nested groups

When authorizing users, the RBAC service can search nested groups. Nested groups are groups that belong to external directory groups. For example, assume your external directory has a System Administrators group, and you've given that group a Superusers user role in RBAC. In addition to assigning the Superusers role to individual users in the System Administrators group, RBAC looks for other groups in the System Administrators group and assigns the Superusers role to the individual users in those nested groups.

By default, RBAC does not search nested groups. To enable nested group searches, set search_nested_groups to true.

Important: This setting causes RBAC to search the entire group hierarchy when users log in; therefore, you might experience slowdowns in performance if you have a lot of nested groups. To avoid these performance issues, set search_nested_groups to false. This disables nested group searches so RBAC only searches the groups it is configured to use for user roles.
Note: In Puppet Enterprise (PE) versions 2015.3 and earlier, RBAC searched nested groups by default. If you upgrade from one of these earlier versions, this setting is preserved and RBAC continues to search nested groups by default. You'll need to disable it (by setting search_nested_groups to false) if you don't want to use nested searching anymore.

Using StartTLS connections

You can set start_tls to true to use StartTLS to secure the connection to the directory service. Any certificates you configured through the DS trust chain setting are used to verify the identity of the directory service. If you set start_tls to true, make sure ssl is set to false.

Disabling matching rule in chain

When PE detects an Active Directory that supports the LDAP_MATCHING_RULE_IN_CHAIN feature, PE automatically uses it. Under specific circumstances, you might need to disable this setting by setting disable_ldap_matching_rule_in_chain to true. Otherwise, this setting is optional.

Response format

Returns 200 OK with an object showing the updated connection settings. For example:
{
  "help_link": "https://help.example.com",
  "ssl": true,
  "group_name_attr": "name",
  "password": <password>,
  "group_rdn": null,
  "connect_timeout": 15,
  "user_display_name_attr": "cn",
  "disable_ldap_matching_rule_in_chain": false,
  "ssl_hostname_validation": true,
  "hostname": "ldap.example.com",
  "base_dn": "dc=example,dc=com",
  "user_lookup_attr": "uid",
  "port": 636,
  "login": "cn=ldapuser,ou=service,ou=users,dc=example,dc=com",
  "group_lookup_attr": "cn",
  "group_member_attr": "uniqueMember",
  "ssl_wildcard_validation": false,
  "user_email_attr": "mail",
  "user_rdn": "ou=users",
  "group_object_class": "groupOfUniqueNames",
  "display_name": "Acme Corp Ldap server",
  "search_nested_groups": true,
  "start_tls": false
}

For errors, refer to RBAC service errors.