LDAP Connection

General Information

Connection Type

ldap

UI Documentation

📖 For detailed information: [UI Documentation Link - Link will be added here]

Description

LDAP (Lightweight Directory Access Protocol) connection for authenticating users and querying directory services. Supports SSL/TLS encryption, certificate validation, and various search scopes. Used by authentication policies and connectors to integrate with LDAP-compatible directory services like Active Directory, OpenLDAP, and others.

Endpoints

List Connections

GET /apiops/projects/{projectName}/connections/?type=ldap

Get Connection

GET /apiops/projects/{projectName}/connections/{connectionName}/

Create Connection

POST /apiops/projects/{projectName}/connections/{connectionName}/

Update Connection

PUT /apiops/projects/{projectName}/connections/{connectionName}/

Delete Connection

DELETE /apiops/projects/{projectName}/connections/{connectionName}/

List Connections

Endpoint

GET /apiops/projects/{projectName}/connections/?type=ldap

Request

Headers

Header	Value
Authorization	Bearer {token}

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name

Note: The type query parameter is required to filter connections by type.

cURL Example

curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/connections/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Connection

Endpoint

GET /apiops/projects/{projectName}/connections/{connectionName}/

Request

Headers

Header	Value
Authorization	Bearer {token}

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
connectionName	string	Yes	Connection name

Response

Success Response (200 OK)

{
  "success": true,
  "resultList": [
    {
      "type": "ldap",
      "name": "my-ldap-connection",
      "description": "LDAP connection for authentication",
      "deployToWorker": true,
      "enabled": true,
      "serverAddress": "ldap://ldap.example.com:389",
      "requireCertificateType": "NOT_REQUIRED",
      "username": "cn=admin,dc=example,dc=com",
      "password": null,
      "customFilter": "(uid={0})",
      "searchScope": "SUBTREE",
      "baseDn": "dc=example,dc=com",
      "certificateId": null,
      "certificateName": null,
      "useSsl": false,
      "selectedEnvironmentId": null
    }
  ],
  "resultCount": 1
}

Note: Password is masked in get operations.

cURL Example

curl -X GET \
  "https://demo.apinizer.com/apiops/projects/MyProject/connections/my-ldap-connection/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Connection

Endpoint

POST /apiops/projects/{projectName}/connections/{connectionName}/

Request

Headers

Header	Value
Authorization	Bearer {token}
Content-Type	application/json

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
connectionName	string	Yes	Connection name

Request Body

Full JSON Body Example - Basic LDAP Connection

{
  "type": "ldap",
  "name": "my-ldap-connection",
  "description": "LDAP connection for authentication",
  "deployToWorker": true,
  "enabled": true,
  "serverAddress": "ldap://ldap.example.com:389",
  "requireCertificateType": "NOT_REQUIRED",
  "username": "cn=admin,dc=example,dc=com",
  "password": "adminpassword",
  "customFilter": "(uid={0})",
  "searchScope": "SUBTREE",
  "baseDn": "dc=example,dc=com",
  "certificateId": null,
  "certificateName": null,
  "useSsl": false,
  "selectedEnvironmentId": null
}

Full JSON Body Example - LDAP with SSL

{
  "type": "ldap",
  "name": "my-ldap-ssl",
  "description": "LDAP connection with SSL",
  "deployToWorker": true,
  "enabled": true,
  "serverAddress": "ldaps://ldap.example.com:636",
  "requireCertificateType": "REQUIRED_CN",
  "username": "cn=admin,dc=example,dc=com",
  "password": "adminpassword",
  "customFilter": "(uid={0})",
  "searchScope": "SUBTREE",
  "baseDn": "dc=example,dc=com",
  "certificateId": "cert-id-123",
  "certificateName": "ldap-server-cert",
  "useSsl": true,
  "selectedEnvironmentId": null
}

Full JSON Body Example - Active Directory

{
  "type": "ldap",
  "name": "my-ad-connection",
  "description": "Active Directory LDAP connection",
  "deployToWorker": true,
  "enabled": true,
  "serverAddress": "ldap://ad.example.com:389",
  "requireCertificateType": "NOT_REQUIRED",
  "username": "CN=ServiceAccount,CN=Users,DC=example,DC=com",
  "password": "servicepassword",
  "customFilter": "(sAMAccountName={0})",
  "searchScope": "SUBTREE",
  "baseDn": "DC=example,DC=com",
  "certificateId": null,
  "certificateName": null,
  "useSsl": false,
  "selectedEnvironmentId": null
}

Full JSON Body Example - LDAP with Certificate Validation

{
  "type": "ldap",
  "name": "my-ldap-secure",
  "description": "LDAP with certificate validation",
  "deployToWorker": true,
  "enabled": true,
  "serverAddress": "ldaps://ldap.example.com:636",
  "requireCertificateType": "REQUIRED_AN_PN",
  "username": "cn=admin,dc=example,dc=com",
  "password": "adminpassword",
  "customFilter": "(uid={0})",
  "searchScope": "SUBTREE",
  "baseDn": "dc=example,dc=com",
  "certificateId": "cert-id-456",
  "certificateName": "ldap-ca-cert",
  "useSsl": true,
  "selectedEnvironmentId": null
}

Request Body Fields

Common Fields

Field	Type	Required	Default	Description
type	string	Yes	-	Connection type discriminator field. Identifies the connection type in API requests/responses.
name	string	Yes	-	Connection name (must match path parameter)
description	string	No	-	Connection description
deployToWorker	boolean	No	true	Whether to deploy to worker
enabled	boolean	No	true	Whether connection is enabled

LDAP-Specific Fields

Field	Type	Required	Default	Description
serverAddress	string	Yes	-	LDAP server address (format: `ldap://host:port` or `ldaps://host:port`)
requireCertificateType	string	No	NOT_REQUIRED	Certificate requirement type. See EnumLdapRequireCertificateType
username	string	Yes	-	LDAP bind DN (Distinguished Name) for authentication
password	string	Yes	-	LDAP password for bind DN (secret field)
customFilter	string	No	-	Custom LDAP search filter (use `{0}` as placeholder for username)
searchScope	string	No	SUBTREE	Search scope. See EnumSearchScope
baseDn	string	Yes	-	Base Distinguished Name for searches
certificateId	string	No	null	Certificate ID for SSL/TLS (required if useSsl=true and certificate validation enabled)
certificateName	string	No	null	Certificate name (for reference)
useSsl	boolean	No	false	Enable SSL/TLS encryption (use `ldaps://` in serverAddress)
selectedEnvironmentId	string	No	null	Selected environment ID

EnumLdapRequireCertificateType (requireCertificateType)

NOT_REQUIRED - No certificate validation (default)
REQUIRED_CN - Certificate Common Name (CN) must match server hostname
REQUIRED_AN_PN - Certificate Alternative Name or Principal Name must match

EnumSearchScope (searchScope)

OBJECT - Search only the base object itself
ONE_LEVEL - Search immediate children of base object
SUBTREE - Search base object and all descendants (default, most common)

Server Address Format

LDAP: ldap://hostname:389 (standard port 389)
LDAPS: ldaps://hostname:636 (secure port 636)
Can include additional connection parameters

LDAP Filter Examples

(uid={0}) - Search by UID attribute (OpenLDAP)
(sAMAccountName={0}) - Search by sAMAccountName (Active Directory)
(cn={0}) - Search by Common Name
(&(objectClass=person)(uid={0})) - Combined filter with object class

Notes

serverAddress, username, password, and baseDn are required.
serverAddress format: ldap://host:port or ldaps://host:port
username is the bind DN (Distinguished Name) for LDAP authentication.
password is the password for the bind DN.
customFilter uses {0} as placeholder for the username being searched.
searchScope defaults to SUBTREE (searches entire subtree).
useSsl: true enables SSL/TLS encryption (use ldaps:// in serverAddress).
certificateId is required if useSsl: true and certificate validation is enabled.
baseDn is the root DN for LDAP searches (e.g., dc=example,dc=com).

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [
      {
        "environmentName": "production",
        "success": true,
        "message": "Deployment successful"
      }
    ]
  }
}

cURL Example

curl -X POST \
  "https://demo.apinizer.com/apiops/projects/MyProject/connections/my-ldap-connection/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ldap",
    "name": "my-ldap-connection",
    "description": "LDAP connection for authentication",
    "deployToWorker": true,
    "enabled": true,
    "serverAddress": "ldap://ldap.example.com:389",
    "requireCertificateType": "NOT_REQUIRED",
    "username": "cn=admin,dc=example,dc=com",
    "password": "adminpassword",
    "customFilter": "(uid={0})",
    "searchScope": "SUBTREE",
    "baseDn": "dc=example,dc=com",
    "useSsl": false
  }'

Update Connection

Endpoint

PUT /apiops/projects/{projectName}/connections/{connectionName}/

Request

Headers

Header	Value
Authorization	Bearer {token}
Content-Type	application/json

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
connectionName	string	Yes	Connection name (must match name in body)

Request Body

Full JSON Body Example

{
  "type": "ldap",
  "name": "my-ldap-connection",
  "description": "Updated LDAP connection for authentication",
  "deployToWorker": true,
  "enabled": true,
  "serverAddress": "ldaps://ldap-new.example.com:636",
  "requireCertificateType": "REQUIRED_CN",
  "username": "cn=admin,dc=newdomain,dc=com",
  "password": "newadminpassword",
  "customFilter": "(mail={0})",
  "searchScope": "ONE_LEVEL",
  "baseDn": "ou=users,dc=newdomain,dc=com",
  "certificateId": "certificate-id-123",
  "certificateName": "ldap-server-cert.crt",
  "useSsl": true,
  "selectedEnvironmentId": null
}

Note: Request body structure is the same as Create Connection. All fields should be provided for update.

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [...]
  }
}

Delete Connection

Endpoint

DELETE /apiops/projects/{projectName}/connections/{connectionName}/

Request

Headers

Header	Value
Authorization	Bearer {token}

Path Parameters

Parameter	Type	Required	Description
projectName	string	Yes	Project name
connectionName	string	Yes	Connection name

Response

Success Response (200 OK)

{
  "success": true,
  "deploymentResult": {
    "success": true,
    "deploymentResults": [...]
  }
}

Notes and Warnings

LDAP Protocol:
- LDAP (Lightweight Directory Access Protocol) for directory services
- Standard port: 389 (LDAP), 636 (LDAPS)
- Supports both LDAP and LDAPS (LDAP over SSL/TLS)
Server Address:
- Format: ldap://hostname:port or ldaps://hostname:port
- Use ldaps:// for SSL/TLS encrypted connections
- Standard ports: 389 (LDAP), 636 (LDAPS)
Authentication:
- username is the bind DN (Distinguished Name) for LDAP authentication
- password is the password for the bind DN
- Bind DN format: cn=username,dc=example,dc=com
- Use service account with appropriate permissions
Search Filter:
- customFilter uses {0} as placeholder for username
- Common filters:
  - OpenLDAP: (uid={0})
  - Active Directory: (sAMAccountName={0})
  - Generic: (cn={0})
Search Scope:
- OBJECT - Search only base object
- ONE_LEVEL - Search immediate children
- SUBTREE - Search entire subtree (default, most common)
Base DN:
- baseDn is the root DN for LDAP searches
- Format: dc=example,dc=com or DC=example,DC=com
- Should match your LDAP directory structure
SSL/TLS:
- useSsl: true enables SSL/TLS encryption
- Use ldaps:// in serverAddress when SSL is enabled
- Certificate validation options:
  - NOT_REQUIRED - No validation (not recommended for production)
  - REQUIRED_CN - CN must match hostname
  - REQUIRED_AN_PN - Alternative Name or Principal Name must match
Certificate:
- certificateId is required if certificate validation is enabled
- Upload certificate to Apinizer certificate store first
- certificateName is for reference only
Active Directory:
- Use sAMAccountName filter for Active Directory
- Bind DN format: CN=ServiceAccount,CN=Users,DC=example,DC=com
- Base DN format: DC=example,DC=com
Performance:
- Use appropriate search scope (SUBTREE is most flexible but slower)
- Optimize custom filter for your directory structure
- Consider connection pooling for high-throughput scenarios
Security:
- Use SSL/TLS in production (ldaps://)
- Enable certificate validation
- Use strong passwords for bind DN
- Restrict bind DN permissions
- Consider using service accounts with minimal privileges
Deployment: Connection changes require deployment to take effect. Set deployToWorker: true or deploy manually.

List Connections - List all connections
Get Connection - Get a specific connection
Create Connection - General connection creation guide
Update Connection - General connection update guide
Delete Connection - General connection deletion guide

LDAP Connection

General Information

Connection Type

UI Documentation

Description

Endpoints

List Connections

Get Connection

Create Connection

Update Connection

Delete Connection

List Connections

Endpoint

Request

Headers

Path Parameters

cURL Example

Get Connection

Endpoint

Request

Headers

Path Parameters

Response

Success Response (200 OK)

cURL Example

Create Connection

Endpoint

Request

Headers

Path Parameters

Request Body

Full JSON Body Example - Basic LDAP Connection

Full JSON Body Example - LDAP with SSL

Full JSON Body Example - Active Directory

Full JSON Body Example - LDAP with Certificate Validation

Request Body Fields

Common Fields

LDAP-Specific Fields

EnumLdapRequireCertificateType (requireCertificateType)

EnumSearchScope (searchScope)

Server Address Format

LDAP Filter Examples

Notes

Response

Success Response (200 OK)

cURL Example

Update Connection

Endpoint

Request

Headers

Path Parameters

Request Body

Full JSON Body Example

Response

Success Response (200 OK)

Delete Connection

Endpoint

Request

Headers

Path Parameters

Response

Success Response (200 OK)

Notes and Warnings

Related Documentation