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. The roles mapped to the local user will take effect upon login. 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 to authenticate 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.

Before configuring 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 expires or fails, the PCE will not try to log in using LDAP authentication.
If the local user does not exist, the PCE attempts to log in to LDAP (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.
When searching for LDAP users, the PCE follows the order in which the servers were configured. By default, the configurable request timeout is 5 seconds. Once the request time expires, the PCE attempts to connect to the next server in the configuration.
For example, assume you configure three LDAP servers in the following 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.

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 available to configure the PCE for LDAP Authentication. For information about the parameters for these REST APIs, see LDAP Authentication Reference.

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`

Enable LDAP Authentication

This section explains how to use the API to enable the PCE for LDAP authentication. Before invoking this API, you must enable the LDAP preview feature in the PCE. For instructions on enabling this preview feature, see LDAP Authentication.

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

LDAP Authentication Reference

This topic covers properties and examples for LDAP authentication.

LDAP Properties

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 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; the attribute will not be returned for GET instance or collection APIs.
`is_bind_password_set`	boolean	No	Flag to indicate whether the 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	An attribute on a user object that contains the username. For example, uid, sAMAccountName, userPrincipalName
`full_name_attribute`	String	No	An attribute on a user object that contains the full name. For example, cn, commonName, displayName
`user_memberof_attribute`	String	No	An 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 is false

Request body for a multi-node cluster for LDAP authentication

{
	"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

REST API Schema Files

The following schema files for LDAP configuration are available starting with release 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.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]"
	} 
    },
]

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]"
	}
]

REST APIs 25.3