POST /command/ldap/create

Configure a new LDAP connection. Authentication and appropriate permissions are required.

To edit existing connections, use POST /command/ldap/update.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object containing directory service settings.

You must specify all required External directory settings in the request body. Specify the following optional settings only if you need to change them from their default values or if they are required by your LDAP configuration:

cert_chain has no default value.
disable_ldap_matching_in_chain defaults to false if omitted.
search_nested_groups defaults to false if omitted.
ssl_hostname_validation defaults to true if omitted.
ssl_wildcard_validation defaults to false if omitted.
start_tls defaults to false if omitted. However, if ssl is false, then start_tls must be true.

Request example:

curl -X POST "https://$(puppet config print server):4433/rbac-api/v1/command/ldap/create" \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"help_link": "https://example.com/login-help.html",
    "ssl": true,
    "group_name_attr": "name",
    "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=pe-orch,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": "ldap.example.com",
    "search_nested_groups": true,
    "start_tls": false}'

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 many nested groups. To avoid these performance issues, set search_nested_groups to false. This disables nested group searches so RBAC searches only 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. When you upgrade from one of these earlier versions, this setting is preserved and RBAC continues to search nested groups by default. If you no longer want to use nested searching, you must disable it by setting search_nested_groups to false.

Using StartTLS connections

To use StartTLS to secure the connection to the directory service, set start_tls to true. 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, then ssl must be false.

Disabling `LDAP_MATCHING_RULE_IN_CHAIN`

By default, disable_ldap_matching_rule_in_chain is set to false, which allows PE to freely use the the LDAP_MATCHING_RULE_IN_CHAIN feature when it detects an Active Directory that supports this feature. Under specific circumstances, you might need to disable this setting by setting disable_ldap_matching_rule_in_chain to true.

Response format

A successful, well-formed request returns 200 OK with the ID of the new connection's configuration object.

If you don't have permission to create LDAP connections, the response is 403 Not Permitted.

A malformed request returns 400 with a schema failure.