Skip to main content

REST APIs for 24.2.20 and 24.2.10

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]"
	}
]
See also: