LDAP Authentication

This Public Experimental API provides user authentication with the PCE using LDAP with OpenLDAP and Active Directory.

LDAP authentication comes in addition to the two previously available methods:

API Keys, which provide persistent authentication, and
Session credentials, which provide temporary authentication.

Prerequisites and Limitations

Before configuring LDAP for authentication with the PCE, it is important to provide the required prerequisites and review any limitations.

Determine Your User Base DN

Before you map your LDAP settings to PCE settings, determine your user base Distinguished Name (DN). The DN is the location in the directory where authentication information is stored.

If you don't have this information, contact your LDAP administrator for assistance.

When configuring the PCE to work with LDAP, be aware of the following:

PCE uses LDAP protocol version 3 ("v3").
Supported LDAP distributions include OpenLDAP 2.4 and Active Directory.
Supported LDAP protocols include LDAP, LDAPS, or LDAP with STARTTLS.

Limitations

These are the current limitations for LDAP authentication:

Any locally created user has precedence over an LDAP user of the same name. For example, if the LDAP server has a user with a username attribute (such as cn or uid) of johndoe and the default PCE user of the same name is present, the PCE user takes precedence. Only the local password is accepted. On login, the roles mapped to the local user will be in effect. To work around this limitation, you must delete the specific local user.

LDAP and SAML single sign-on authentication methods cannot be used together. In this release of the PCE, an organization can either use LDAP or SAML single sign-on for authenticating external users.

This release enables LDAP configuration via REST APIs only.

LDAP Authentication for the PCE

The PCE supports user and role configuration for LDAP users and groups. You can configure up to three LDAP servers and map users and user groups from your LDAP servers to PCE roles.

For information about configuring multiple LDAP servers, see How the PCE Works with Multiple LDAP Servers.

Before you configure LDAP, review the LDAP prerequisites and considerations topic in this document.

Authentication Precedence

PCE local authentication takes precedence over any external systems. The PCE authenticates a user in the following order:

The PCE first attempts local authentication. If the account is expired or otherwise fails, the PCE does not try to log in by using LDAP authentication.
If the local user does not exist, the PCE attempts LDAP login (if enabled).

Configuration Steps

To configure the PCE to work with LDAP, perform these steps:

Enable the PCE to use LDAP authentication. See Enable LDAP Authentication.
Set up an LDAP configuration. See Configure LDAP Authentication.
When searching for LDAP users, the PCE follows the order in which the servers were configured. The configurable request timeout is 5 seconds by default. Once the request time expires, the PCE attempts to connect to the next server in the configuration.
For example, assume that you configure three LDAP servers in this order: A, B, and C. The PCE will search the servers in that same order. If it finds a user on server A, it stops even if the same user also exists on servers B and C. The PCE will try to use A's credentials for that user, but if it fails to connect to A, it searches the remaining servers: first B, The search proceeds following the expiration of the connection timeout.
Map your LDAP groups to one or more PCE roles. See Mapping LDAP Group Membership to PCE User Roles.

Mapping Group Membership to User Roles

First, configure the PCE to use LDAP authentication. Second, map PCE roles to that server's groups.

When a user attempts to log in, the PCE queries the server(s) to find that user. It grants the user permissions based on any roles associated with the LDAP groups to which the user belongs.

You have the following options for changing user permissions:

For a group of users, remap the LDAP group to a different PCE role.
For an individual user, move the user to an LDAP group mapped to a different PCE role using the LDAP server.

You can also perform these user management activities:

Add a user to a PCE role:
- On the PCE, map the PCE role to an LDAP group.
- On your LDAP server, add the user to that LDAP group.
Remove a user from a PCE role by removing it from the corresponding LDAP group on your LDAP server.

Users can have memberships in several roles. In that case, they have access to all the capabilities available for any of these roles. For example, a user is a member of both the docs and eng groups and docs group is mapped to "Ruleset Manager" while the eng group is mapped to "Ruleset Provisioner." In this case, the user obtains all permissions assigned both to the "Ruleset Manager" and "Ruleset Provisioner" roles.

Note

The PCE checks LDAP membership information when a user attempts to log in. You do not need to reload the authentication configuration when adding or removing users.

See the PCE Web Console Guide for information about the mapping from external groups to PCE user roles.

Set up the PCE for LDAP Authentication

The PCE supports LDAPS and LDAP with STARTTLS. To use the PCE with secure LDAP with SSL/TLS certificates, add the certificate chain to the local certificate store on the PCE.

Using REST APIs for LDAP Configuration in the PCE

The following table provides an overview of the REST APIs you have available to configure the PCE for LDAP Authentication. For information about the parameters for these REST APIs, see Overview of LDAP Configuration Parameters and REST API Schema Files.

APIs for LDAP Configuration

PCE APIs	HTTP \| URI
Retrieve the PCE authentication settings	`GET [api_version]/authentication_settings`
Update the PCE authentication settings	`PUT [api_version]/authentication_settings`
Retrieve the LDAP configuration	`GET [api_version]/authentication_settings/ldap_configs`
Get instance	`GET [api_version]/authentication_settings/ldap_configs/:uuid`
Create an LDAP configuration	`POST [api_version]/authentication_settings/ldap_configs`
Update an LDAP configuration	`PUT [api_version]/authentication_settings/ldap_configs/:uuid`
Delete an LDAP configuration	`DELETE [api_version]/authentication_settings/ldap_configs/:uuid`
Verify the connection to the LDAP server	`POST [api_version]/authentication_settings/ldap_configs/:uuid/verify_connection`

LDAP Configuration Parameters

API Property Name	Type	Required	Description
`pce_fqdn`	String	No	Regional PCE member FQDN for Supercluster. For non-supercluster deployment, it is the FQDN of the PCE cluster.
`name`	String	No	Friendly name of the LDAP server
`address`	String. Format: hostname or ipv4	Yes	IP address or hostname of the LDAP server
`port`	Integer	Yes	Port number of the LDAP server - 636 for LDAPS or 389 for STARTTLS
`authentication_ method`	Enum	Yes	`LDAP`: Clear text connection `LDAPS`: LDAP over SSL/TLS Protocol `STARTTLS`: LDAP over SSL/TLS Protocol with handshake establishment before Secure connection:
`request_timeout_ seconds`	Integer	No	Number of seconds to wait for a response; default 5 seconds. Possible values: 1-60
`bind_distinguished_ name`	String	No	Distinguished name (DN) used to bind to the LDAP server
`bind_password`	String	No	Bind DN password. Only applicable for POST or PUT operations; attribute will not be returned for GET instance or collection APIs.
`is_bind_password_ set`	boolean	No	Flag to indicate whether Bind DN password is configured. Adding this flag because the API does not return the bind password and there is a need to indicate if the password has been set for the bind_distinguished_name. Only applicable for GET operation
`user_base_ distinguished_name`	String	Yes	Base DN to search for users
`user_distinguished_ name_pattern`	String	No	Pattern used to create a DN string for a user during login; for example, uid=,ou=people, where will be replaced with the username
`user_base_filter`	String	No	Search filter used to query the LDAP tree for users
`username_attribute`	String	Yes	Attribute on a user object that contains the username; for example, uid, sAMAccountName, userPrincipalName
`full_name_attribute`	String	No	Attribute on a user object that contains the full name; for example, cn, commonName, displayName
`user_memberof_ attribute`	String	No	Attribute on a user object containing group membership information; for example, memberOf, isMemberOf
`insecure_disable_ tls_certificate_ verification`	boolean	No	Specifies whether to verify the server certificate when establishing an SSL connection to the LDAP server; default false

Enable LDAP Authentication

This section explains how to use API to enable the PCE for LDAP authentication. You must enable the LDAP preview feature in the PCE before invoking this API. For the steps to enable this preview feature, see Enabling the LDAP Authentication Preview.

URI

PUT /api/v2/authentication_settings

Request Body

Property	Data Type	Required	Description
authentication_type	enum	Yes	The type of authentication

Enum Item	Purpose
Local	Local DB authentication
SAML	SAML authentication enabled
RADIUS	RADIUS authentication enabled
LDAP	LDAP authentication enabled

Example Payload to Configure LDAP Authentication

{
"authentication_type": "LDAP",
}

Response Code

The following response codes can be returned:

200 indicates success
403 indicates the user is not an org owner
406 indicates invalid parameters

Configure LDAP Authentication

This API creates the configuration for an LDAP server in the PCE. For information about the request parameters, see LDAP Configuration Parameters.

URI

POST /api/v2/authentication_settings/ldap_configs

Request body for a multi-node cluster

{
	"name" :  "ldap 1" ,
	"address" :  "ldap-1.mycompany.com " ,
	"port" :  "10636" ,
	"authentication_method" :  "LDAPS" ,
	"request_timeout_seconds" : 4,
	"bind_distinguished_name" :  
		'CN=admin,CN=Users,DC=mycompany,DC=com' ,
	"bind_password" :  'test1234' ,
	"user_base_distinguished_name" :  'DC=mycompany,DC=com' ,
	"username_attribute" :  'sAMAccountName' ,
	"full_name_attribute" :  'cn' ,
	"user_memberof_attribute" :  'memberof',
}

Request body for a supercluster

{
	"pce_fqdn" :  "devmr01" ,
	"name" :  "ldap 1" ,
	"address" :  "ldap-1.mycompany.com" ,
	"port" :  "10636" ,
	"authentication_method" :  "LDAPS" ,
	"request_timeout_seconds" : 4,
	"bind_distinguished_name" :  'CN=admin,CN=Users,DC=mycompany,DC=com' ,
	"bind_password" :  'test1234' ,
	"user_base_distinguished_name" :  'DC=mycompany,DC=com' ,
	"username_attribute" :  'sAMAccountName' ,
	"full_name_attribute" :  'cn' ,
	"user_memberof_attribute" :  'memberof' ,
}

Response Code

The following response codes can be returned:

204 indicates success
403 indicates the user is not an org owner
406 indicates invalid parameters

Configure Secure LDAP

In the process of configuring an LDAP server in the PCE, you need to configure LDAP for SSL authentication.

You can Secure LDAP with SSL/TLS Certificates using these three methods:

Use PCE Web UI to Configure Secure LDAP.
Install LDAP TLS Certificates to the PCE System CA Store from the PCE Command-Line.
Configure LDAP for SSL authentication using REST APIs

Configure LDAP for SSL authentication

The following APIs are used to configure LDAP for SSL:

GET /authentication_settings/ldap_configs
GET /authentication_settings/ldap_configs/:uuid
POST /authentication_settings/ldap_configs
PUT /authentication_settings/ldap_configs/:uuid

The required property is tls_ca_bundle.

To manage TLS CA bundle for LDAP authentication use these APIs:

GET /login_proxy_ldap_configs
POST /login_proxy_ldap_configs
PUT /login_proxy_ldap_configs/update

Update LDAP configuration

This section outlines how to update the LDAP server configuration in the PCE. For information about the request parameters, see Overview of LDAP Configuration Parameters.

PUT /api/v2/authentication_settings/ldap_configs/:uuid

(uuid indicates the LDAP server configuration uui)

Request Body

{
        "address" :  "ldap-1.mycompany.com" ,
        "bind_password" :  "qw3r!y123!!" ,
       "full_name_attribute" :  "displayName" ,
        "port" : 636,
        "insecure_disable_tls_certificate_verification": true
}

Response Code

The following response codes can be returned:

204 indicates success
403 indicates the user is not an org owner
404 indicates LDAP configuration not found or an attempt to update LDAP configuration in another domain
406 indicates invalid parameters

Delete LDAP Server Configuration

This API deletes the configuration for an LDAP server in the PCE. For information about the request parameters, see LDAP Configuration Parameters Overview.

URI

DELETE /api/v2/authentication_settings/ldap_configs/:uuid

uuid indicates the LDAP server configuration uuid

Request Body

None

Response Code

The following response codes can be returned:

204 indicates success
403 indicates the user is not an org owner
404 indicates LDAP configuration not found or an attempt to update LDAP configuration in another domain
406 indicates invalid parameters

Test LDAP Server Connectivity

This section outlines the use of the API to verify the connectivity for a configured LDAP server in the PCE.

URI

POST /api/v2/authentication_settings/ldap_configs/:uuid/verify_connection

(uuid indicates the LDAP server configuration uuid)

Request Body

none

Response Body

If a server connection is verified successfully:

{
	"verified" :  true
}

If the server connection verification fails:

{
	"verified" :  false ,
	"errors" : [
	{
	"token" :  "ldap_server_verification_failure" ,
	"message" :  "LDAP server verification failure:  LDAP server error message"
	}
]

Response Code

The following response codes can be returned:

200 indicates success
403 indicates the user is not an org owner
404 indicates LDAP configuration not found

Use Cases

Configure LDAP for SSL authentication

Use case 1:

Retrieve all LDAP configurations for the domain.

Request format:GET /api/v2/authentication_settings/ldap_configs
Possible parameters (drawn from REST API conventions):
- Required: none
Request Body: none
Response format: JSON
Response Code: 200 success

Use case 2:

Create LDAP server configuration.

Request format: POST /api/v2/authentication_settings/ldap_configs
Possible parameters (drawn somewhat from REST API Conventions):
- Required: none
- Optional: none

Request Body:

Single-PCE

{
        "name": "ldap 1",
        "address": "ldap-1.ilabs.io",
        "port": "10636",
        "authentication_method": "LDAPS",
        "request_timeout_seconds": 4,
        "bind_distinguished_name": 'CN=admin,CN=Users,DC=ilabs,DC=io',
        "bind_password": 'test1234',
        "user_base_distinguished_name": 'DC=ilabs,DC=io',
        "username_attribute": 'sAMAccountName',
        "full_name_attribute": 'cn',
        "user_memberof_attribute": 'memberof',
        "tls_ca_bundle": "
        -----BEGIN CERTIFICATE-----
        MIIDhTCCAm2gAwIBAgIQYx+dZzQPBLdN6e8uqW2ByDANBgkqhkiG9w0BAQ0FADBJ
        .................................................................
        -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        MIIF7TCCBNWgAwIBAgITEgAAAEg0ToOKIywtOQAAAAAASDANBgkqhkiG9w0BAQ0F
        ................................................................
        -----END CERTIFICATE-----"
       }

Supercluster

{
        "pce_fqdn": "devmr01",
        "name": "ldap 1",
        "address": "ldap-1.ilabs.io",
        "port": "10636",
        "authentication_method": "LDAPS",
        "request_timeout_seconds": 4,
        "bind_distinguished_name": 'CN=admin,CN=Users,DC=ilabs,DC=io',
        "bind_password": 'test1234',
        "user_base_distinguished_name": 'DC=ilabs,DC=io',
        "username_attribute": 'sAMAccountName',
        "full_name_attribute": 'cn',
        "user_memberof_attribute": 'memberof',
        "tls_ca_bundle": "-----BEGIN CERTIFICATE-----
        MIIDhTCCAm2gAwIBAgIQYx+dZzQPBLdN6e8uqW2ByDANBgkqhkiG9w0BAQ0FADBJ
        -----END CERTIFICATE-----
        -----BEGIN CERTIFICATE-----
        MIIF7TCCBNWgAwIBAgITEgAAAEg0ToOKIywtOQAAAAAASDANBgkqhkiG9w0BAQ0F
        -----END CERTIFICATE-----"	
}

Response format: JSON
Response Code:

204 success
403 not an org owner
406 invalid params

Use case 3:

Update LDAP server configuration:

Request format: PUT /api/v2/authentication_settings/ldap_configs/:uuid
Possible parameters (drawn somewhat from REST API Conventions):
- Required: uuid - LDAP server configuration UUID
- Optional: none

Request Body:

{
"tls_ca_bundle":" 
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE------
----END CERTIFICATE-----"
}

Response format: JSON
Response Codes:

204 success
403 not an org owner
404 LDAP config not found or attempt to update LDAP config in another domain
406 invalid params

REST API Schema Files

The following schema files for LDAP configuration are available in 19.3.5:

ldap_config.schema.json
authentication_settings_ldap_configs_get.schema.json
authentication_settings_ldap_configs_post.schema.json
authentication_settings_ldap_configs_put.schema.json
authentication_settings_ldap_configs_verify_connection_post.schema.json
authentication_settings_get.schema.json
authentication_settings_put.schema.json

Sample Responses

GET /authentication_settings

{
	"authentication_type" : "LDAP"
}

Single-PCE: GET /authentication_settings/ldap_configs

[  
	{
	"href":"/authentication_settings/ldap_configs/
		acf577c8-839a-4828-90f6-797bfc1b54d1",
	"pce_fqdn":"test.ilabs.io",
	"name":"mycompany",
	"address":"ldap-1.mycompany.com",
	"port":389,
	"authentication_method":"LDAP",
	"request_timeout_seconds":5,
	"bind_distinguished_name":"[email protected]",
	"is_bind_password_set":true,
	"user_base_distinguished_name":"OU=Users,
		OU=mycompany Employees,DC=mycompany,DC=com",
	"user_distinguished_name_pattern":null,
	"user_base_filter":"(&(objectcategory=person)
		(objectclass=user))",
	"username_attribute":"userPrincipalName",
	"full_name_attribute":"cn",
	"user_memberof_attribute":"memberOf",
	"insecure_disable_tls_certificate_verification":false,
	"created_at":"2019-03-07T23:30:13.046Z",
	"updated_at":"2019-03-07T23:30:13.046Z",
	"created_by":{
		"username":"[email protected]"
	},
	"updated_by":{
		"username":"[email protected]"
	} 
    },
    {
	"href":"/authentication_settings/ldap_configs/
		827b0e34-16ed-4b87-9263-8cc6b9614302",
	"pce_fqdn":"test.ilabs.io",
	"name":"jumpcloud",
	"address":"ldap2.jumpcloud.com",
	"port":636,
	"authentication_method":"LDAPS",
	"request_timeout_seconds":5,
	"bind_distinguished_name":"uid=test,ou=Users,
		o=58b6704846cf383825533989,dc=jumpcloud,dc=com",
	"is_bind_password_set":false,
	"user_base_distinguished_name":"ou=Users,
		o=58b6704846cf383825533989,dc=jumpcloud,dc=com",
	"user_distinguished_name_pattern":"ou=Users,
		o=58b6704846cf383825533989,dc=jumpcloud,dc=com",\
	"user_base_filter":"(objectClass=inetOrgPerson)",
	"username_attribute":"uid",
	"full_name_attribute":"cn",
	"user_memberof_attribute":"memberOf",
	"insecure_disable_tls_certificate_verification":false,
	"created_at":"2019-03-07T23:30:13.046Z",
	"updated_at":"2019-03-07T23:30:13.046Z",
	"created_by":{
		"username":"[email protected]"
	},
	"updated_by":{
		"username":"[email protected]"
	}
    }
]

Supercluster: GET /authentication_settings/ldap_configs

[
	{
	"pce_fqdn":"devmr01",
	"href":"/authentication_settings/ldap_configs/
		8501dff7-cd3f-4c01-9057-f2b9b1486348",
	"name":"ldap 1",
	"address":"ldap-1.mycompany.com",
	"port":389,
	"authentication_method":"STARTTLS",
	"is_bind_password_set":false,
	"user_base_distinguished_name":"DC=ilabs,DC=io",
	"user_distinguished_name_pattern":null,
	"username_attribute":"sAMAccountName",
	"full_name_attribute":"cn",
	"user_memberof_attribute":"memberof",
	"insecure_disable_tls_certificate_verification":false,
	"created_at":"2018-11-30T18:38:36.634Z",
	"updated_at":"2018-11-30T18:38:36.634Z",
	"created_by":{ 
		"username":"[email protected]"
	},
	"updated_by":{ 
		"username":"[email protected]"
	}
},
	{
	"pce_fqdn":"devmr01",
	"href":"/authentication_settings/ldap_configs/
		827b0e34-16ed-4b87-9263-8cc6b9614302",
	"name":"ldap 2",
	"address":"ldap-2.mycompany.com",
	"port":389,
	"authentication_method":"STARTTLS",
	"is_bind_password_set":false,
	"user_base_distinguished_name":"DC=ilabs,DC=io",
	"user_distinguished_name_pattern":null,
	"username_attribute":"sAMAccountName",
	"full_name_attribute":"cn",
	"user_memberof_attribute":"memberof",
	"insecure_disable_tls_certificate_verification":false,
	"created_at":"2018-12-01T18:38:36.634Z",
	"updated_at":"2018-12-01T18:38:36.634Z",
	"created_by":{ 
		"username":"[email protected]"
	},
	"updated_by":{ 
		"username":"[email protected]"
	}
},
	{
	"pce_fqdn":"devmr02",
	"href":"/authentication_settings/ldap_configs/
		828ca310-d1f9-4125-b88a-fea8fb0374c5",
	"name":"ldap 1",
	"ldap-1.mycompany.com",
	"port":389,
	"authentication_method":"STARTTLS",
	"user_base_distinguished_name":"DC=ilabs,DC=io",
	"user_distinguished_name_pattern":null,
	"is_bind_password_set":true,
	"username_attribute":"sAMAccountName",
	"full_name_attribute":"cn",
	"user_memberof_attribute":"memberof",
	"insecure_disable_tls_certificate_verification":false,
	"created_at":"2018-12-04T18:38:36.634Z",
	"updated_at":"2018-12-04T18:38:36.634Z",
	"created_by":{ 
		"username":"[email protected]"
	},
	"updated_by":{ 
		"username":"[email protected]"
		}
	},
	{
	"pce_fqdn":"devmr02",
	"href":"/authentication_settings/ldap_configs/
		7fb7e865-1522-4ebd-b614-01bf9180e49d",
	"name":"ldap 2",
	"ldap-2.mycompany.com",
	"port":389,
	"authentication_method":"STARTTLS",
	"user_base_distinguished_name":"DC=ilabs,DC=io",
	"user_distinguished_name_pattern":null,
	"is_bind_password_set":true,  
	"username_attribute":"sAMAccountName",
	"full_name_attribute":"cn",
	"user_memberof_attribute":"memberof",
	"insecure_disable_tls_certificate_verification":false,
	"created_at":"2018-12-04T18:38:36.634Z",
	"updated_at":"2018-12-04T18:38:36.634Z",
	"created_by":{ 
		"username":"[email protected]"
	},
	"updated_by":{ 
		"username":"[email protected]"
	}
}
]

REST APIs for 22.2

LDAP Authentication

Prerequisites and Limitations

Determine Your User Base DN

Limitations

LDAP Authentication for the PCE

Authentication Precedence

Configuration Steps

Mapping Group Membership to User Roles

Note

Set up the PCE for LDAP Authentication

Using REST APIs for LDAP Configuration in the PCE

Enable LDAP Authentication

Configure LDAP Authentication

Configure Secure LDAP

Configure LDAP for SSL authentication

Update LDAP configuration

Delete LDAP Server Configuration

Test LDAP Server Connectivity

Use Cases

Configure LDAP for SSL authentication

Use case 1:

Use case 2:

Use case 3:

REST API Schema Files

Sample Responses

Search results