PUT /ds (deprecated)

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

PUT /v1/ds is deprecated. Instead, use POST /command/ldap/create, POST /command/ldap/update, and POST /command/ldap/delete. The information on this page reflects conditions and behavior prior to this endpoint's deprecation. Requirements are different in newer endpoints.

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.

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 -X 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.

If you have an LDAP connection configured, you can use the GET /ds (deprecated) 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.

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.

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 .