LDAP endpoints

Use the v1 LDAP endpoints to test and configure LDAP directory service connections.

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

Use the v2 LDAP endpoints to get information about your LDAP connections.

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.

Important: 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.

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 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.
Remember: 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.

For other errors, refer to RBAC service errors.

POST /command/ldap/update

Replace an existing directory service connection's settings. Authentication and appropriate permissions are required.

This endpoint updates an existing LDAP connection. To create a connection, use POST /command/ldap/create. To test a connection, use POST /command/ldap/test. To remove a connection, use POST /command/ldap/delete.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object containing the ID of the directory service connection you want to modify and the connection's settings.

Important: Your request body must contain the connection's ID, all required settings, and any previously-configured optional settings, including settings you aren't changing. Omitting a setting resets it to the default value (if any) or assigns a null value. For information about required and optional values refer to External directory settings and POST /command/ldap/create.
Tip: Use GET /ldap or GET /ldap/<id> to retrieve the connection's complete settings object and use it as a template for your POST /command/ldap/update request. This helps avoid accidentally omitting a setting.
Request example:
curl -X POST "https://$(puppet config print server):4433/rbac-api/v1/command/ldap/update" \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"id": "e97188aa-9573-413b-945e-07f5f261613e",
    "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",
    "password": "somepassword",
    "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}'

Response format

A successful request returns 200 OK with an object showing the updated connection settings. For example:
{
  "id": "e97188aa-9573-413b-945e-07f5f261613e",
  "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
}

If there is no match for the given ID, the response is 404 Not Found.

If you don't have permission to modify LDAP connection settings, the response is 403 Not Permitted.

A malformed request, such as omitting a required setting, returns 400 with a schema failure.

For other errors, refer to RBAC service errors.

POST /command/ldap/delete

Delete an existing directory service connection. Requires authentication and appropriate permissions.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object containing the ID of the LDAP connection that you want to remove. For example:
curl -X POST "https://$(puppet config print server):4433/rbac-api/v1/command/ldap/delete" \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"id": "e97188aa-9573-413b-945e-07f5f261613e"}'
Tip: Use GET /ldap to get the LDAP connection ID.

Response format

Returns 204 No Content if you have appropriate permissions and the request was well-formed. If a connection with the given ID exists, then this response means the connection was successfully removed. However, this response is returned for ANY well-formed, permitted request, even if there is no match for the given ID.

When you disconnect an LDAP directory that has imported groups, all users and groups associated with that directory are removed from PE RBAC.

Error responses

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

For other errors, refer to RBAC service errors.

POST /command/ldap/test

Test a directory service connection based on supplied settings. Authentication and appropriate permissions are 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 information about each setting, refer to External directory settings.

Tip: If an LDAP connection already exists, use GET /ldap or GET /ldap/<id> to retrieve the current settings object and use it as a template for your POST /command/ldap/test request. The id key is ignored if you include it in your request.
Request example:
curl -X POST "https://$(puppet config print server):4433/rbac-api/v1/command/ldap/test" \
-H "X-Authentication: 0F4DITVB7HP3z8YnD95kx1W1jY0z5Pnc3ixB5uGAXzLY" \
-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}'

Response format

If the test succeeds, the endpoint returns 200 OK and a JSON object containing the elapsed time in seconds, for example: {"elapsed": 10}.

If the test fails, the endpoints returns 200 OK and a body containing the elapsed time and an error key, for example: {"elapsed": 20, "error": "..."}.

If you're satisfied with the test results, you can use POST /command/ldap/create or POST /command/ldap/update to apply these settings to an actual LDAP connection.

If the test can't run, the endpoint returns:
  • 403 Not Permitted if you don't have appropriate permissions.
  • 400 if the request is malformed.
  • Other errors as described in RBAC service errors.

GET /ds/test (deprecated)

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

Important: GET /ds/test is deprecated. Instead, use POST /command/ldap/test. 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 request is a basic call with authentication, such as:
curl "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.

If the request was well-formed and valid, but the test failed, response body contains the elapsed time and the reason the test failed. For example, {"elapsed": 20, "error": "..."}.

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.

For other errors, refer to RBAC service errors.

PUT /ds/test (deprecated)

Tests a directory service connection based on supplied settings, rather than stored settings. Authentication is required.

Important: PUT /ds/test is deprecated. Instead, use POST /command/ldap/test. 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. The body must be a JSON object using all directory service setting keys. For example:
curl -X 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 (deprecated) 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 (deprecated)

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

Important: 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.

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

Tip: 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.

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.