Skip to main content

REST APIs 25.1.0

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

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