Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Managing access Grey arrow pointing right RBAC API Grey arrow pointing right RBAC API v1 Grey arrow pointing right LDAP endpoints Grey arrow pointing right

LDAP endpoints

Sections

ExpandCollapse

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

To connect to the directory service anonymously, specify null for the lookup user and lookup password or leave these fields 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

Example curl request:
curl GET 'https://$(puppet config print server):4433/rbac-api/v1/ds' \
-H "X-Authentication: 0F4DITVB7HP3z8YnD95kx1W1jY0z5Pnc3ixB5uGAXzLY"Copied!

Response format

Returns 200 OK with an object representing the connection. 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
}Copied!

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

GET /ds/test

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

Request format

Example curl request:
curl GET 'https://$(puppet config print server):4433/rbac-api/v1/ds/test' \
-H "X-Authentication: 0F4DITVB7HP3z8YnD95kx1W1jY0z5Pnc3ixB5uGAXzLY"Copied!

Response format

Returns 200 OK with information about the test run if the connection test is successful. 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
}Copied!

Error responses

Returns 400 Bad Request if the request is malformed.

Returns 401 Unauthorized if no user is logged in.

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

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

PUT /ds/test

Performs a connection test with the submitted settings. Authentication is required.

Request format

Accepts the full set of directory settings keys with values defined.

Example curl request:
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}Copied!

Response format

Returns information about the test run if the connection test is successful, such as {"elapsed": 10}.

Error responses

Returns information about the test run if the request times out or encounters an error, such as {"elapsed": 20, "error": "..."}.

PUT /ds

Replaces current directory service connection settings. Authentication is required.

Request format

The request accepts directory service connection settings. For example:
{"hostname": "ds.somehost.com",
"name"
"port": 10389,
"login": "frances", ...}Copied!
Important: When changing any directory service settings, you must specify all required directory service settings in the PUT request, including required settings you aren't changing. You do not need to specify optional settings unless you are changing them.

All fields 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. help-link only appears on the login page when users have difficulty logging in.

Example curl request:
curl PUT 'https://$(puppet config print server):4433/rbac-api/v1/ds' \
-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}Copied!

To "disconnect" the DS, format your request as either an empty object ({}) or with all required settings set to null.

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, specify the search_nested_groups field and give it a value of true.

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. 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, change the search_nested_groups field to false. This disables nested group searches so RBAC only searches the groups it is configured to use for user roles.

Using StartTLS connections

You can specify "start_tls": true in your PUT request to use StartTLS to secure your 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 specify start_tls, make sure you don't also have SSL set to true.

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 specifying "disable_ldap_matching_rule_in_chain": true in your PUT request. 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
}Copied!