Access Control (REST) API - LDAP Servers

This section includes REST APIs for working with Access Control LDAP Server tasks.

Test LDAP Server Connection – POST /LDAPServers/TestConnection

Test LDAP Server connection.

Notice

The ‘Manage Authentication Providers’ permission is required to execute this API.

Usage:

GET /LDAPServers/{id} and get details of an LDAP Server
POST /LDAPServers/TestConnection and test the LDAP Server connection

URL

/cxrestapi/auth/LDAPServers/TestConnection

Method:

POST

Media Type (header):

Authorization: Bearer <access token value>

Content-Type: application/json;v=1.0

Parameters

ldapServerViewModel=[body]: Specifies the details of LDAP Server to test

host=[integer] - LDAP Server host name

port=[integer] - LDAP Server Port

username=[string] - Username of the binding user

password=[integer] - Password of the binding user

useSsl=[boolean] - Whether to use SSL when connecting to this LDAP Server (false/true)

verifySslCertificate=[boolean] - Whether to verify SSL certificate (false/true)

baseDn=[string] - LDAP Server base DN

userObjectFilter=[string] - User object filter

userObjectClass=[string] - User object class

usernameAttribute=[string] – User name attribute

firstNameAttribute=[string] - First name attribute

lastNameAttribute=[string] - Last name attribute

emailAttribute=[string] - Email attribute

synchronizationEnabled=[boolean] - Whether synchronization is enabled for this LDAP Server (false/true)

advancedTeamAndRoleMappingEnabled=[boolean] - Whether to enable advanced team and role mapping (false/true)

additionalGroupDn=[string] - Additional group Dn. Limit groups search to specified DN

groupObjectClass=[string] - Group object class

groupObjectFilter=[string] - Group object filter

groupNameAttribute=[string] - Group name attribute

groupMembersAttribute=[string] - Group members attribute

userMembershipAttribute=[string] - User membership attribute

Success Response:

Code: 200 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Sample Response:

{
  "isSuccessful": true,
  "message": "Successfully connected to the LDAP Server, validated user schema settings and attributes"
}

Notes:

Tests LDAP Server connection. If the request fails, it returns an error response.

Get User Entries by Search Criteria - GET /LDAPServers/{id}/UserEntries

Get LDAP Server user entries according to specific search criteria.

Usage:

GET /LDAPServers/{id}/UserEntries and get LDAP Server user entries according to specific search criteria
POST /Users and create a new user

URL

/cxrestapi/auth/LDAPServers/{id}/UserEntries

Method:

GET

Media Type (header):

Authorization: Bearer <access token value>

Accept: application/json;v=1.0

Parameters

Required:

id=[integer] - Unique Id of the LDAP Server. LDAP Server Id (id) is retrieved using the LDAP Servers API.

userNameContainsPattern=[string] – User name contains pattern (e.g., cn=admin,dc=example,dc=com)

Success Response:

Code: 200 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Not Found

Sample Response:

[
  {
    "username": "admin1",
    "firstName": "James",
    "lastName": "Smith",
    "email": admin@cx.org
  }
]

Notes:

Retrieves LDAP Server user entries according to the specified search criteria. If the request fails, it returns an error response.

Get Group Entries by Search Criteria - GET /LDAPServers/{id}/GroupEntries

Get LDAP Server group entries according to specific search criteria.

Notice

The ‘Manage Authentication Providers’ permission is required to execute this API.

Usage:

GET /LDAPServers/{id}/GroupEntries and get LDAP Server group entries according to specific search criteria
PUT /LDAPServers/{id}/RoleMappings and update LDAP role mapping details.
PUT /LDAPServers/{id}/TeamMappings and update LDAP team mapping details.

URL

/cxrestapi/auth/LDAPServers/{id}/GroupEntries

Method:

GET

Media Type (header):

Authorization: Bearer <access token value>

Accept: application/json;v=1.0

Parameters

Required:

id=[integer] - Unique Id of the LDAP Server

nameContainsPattern=[string] – Group name contains pattern (e.g., cn)

Success Response:

Code: 200 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Not Found

Sample Response:

[
  {
    "name": "string",
    "dn": "string"
  }
]

Notes:

Retrieves LDAP Server group entries according to the specified search criteria. If the request fails, it returns an error response.

Get All LDAP Servers - GET /LDAPServers

Get details of all LDAP Servers.

Notice

The ‘Manage Authentication Providers’ permission is required to execute this API.

Usage:

GET /LDAPServers and get details of all LDAP Servers
PUT /LDAPServers/{id} and update the LDAP Server details

URL

/cxrestapi/auth/LDAPServers

Method:

GET

Media Type (header):

Authorization: Bearer <access token value>

Accept: application/json;v=1.0

Parameters

None

Success Response:

Code: 200 Success

Error Response:

Code: 401 Unauthorized

Code: 403 Forbidden

Sample Response:

[
  {
    "id": 2,
    "active": true,
    "name": "microsoft.ldap",
    "host": "0.0.0.0",
    "port": 389,
    "username": "cn=admin,dc=example,dc=com",
    "useSsl": false,
    "verifySslCertificate": false,
    "ldapDirectoryType": "ActiveDirectory",
    "ssoEnabled": false,
    "mappedDomainId": null,
    "baseDn": "ou=automation,dc=example,dc=com",
    "additionalUserDn": "ou=people",
    "userObjectFilter": "(&(objectClass=inetOrgPerson)(uid=*))",
    "userObjectClass": "inetOrgPerson",
    "usernameAttribute": "uid",
    "firstNameAttribute": "givenName",
    "lastNameAttribute": "sn",
    "emailAttribute": "mail",
    "synchronizationEnabled": true,
    "defaultTeamId": 1,
    "defaultRoleId": 1,
    "updateTeamAndRoleUponLoginEnabled": false,
    "periodicalSynchronizationEnabled": true,
    "advancedTeamAndRoleMappingEnabled": false,
    "additionalGroupDn": "ou=groups",
    "groupObjectClass": "groupOfUniqueNames",
    "groupObjectFilter": "(objectClass=groupOfUniqueNames)",
    "groupNameAttribute": "cn",
    "groupMembersAttribute": "uniqueMember",
    "userMembershipAttribute": "memberOf"
  }
]

Notes:

Retrieves details of all LDAP Servers. If the request fails, it returns an error response.

Create New LDAP Server - POST /LDAPServers

Create a new LDAP Server.

Notice

The ‘Manage Authentication Providers’ permission is required to execute this API.

Usage:

POST /LDAPServers and create a new LDAP Server
POST /LDAPServers/TestConnection and test LDAP Server connection

URL

/cxrestapi/auth/LDAPServers

Method:

POST

Media Type (header):

Authorization: Bearer <access token value>

Content-Type: application/json;v=1.0

Parameters

createLdapServerModel=[body]: Specifies the LDAP Server details

password=[string] - Password of the binding user

active=[boolean] - Whether this LDAP Server setting is active (true/false)

name=[string] - Ldap Server display name in Checkmarx (Open LDAP)

host=[string] - LDAP Server host

port=[integer] - LDAP Server Port

username=[string] - Username of the binding user (cn=admin,dc=example,dc=com)

useSsl=[boolean] - Whether to use SSL when connecting to this LDAP Server (false/true)

verifySslCertificate=[boolean] - Whether to verify SSL certificate (false/true)

baseDn=[string] - LDAP Server base DN (ou=testing,dc=example,dc=com)

additionalUserDn=[string] - Additional user DN (ou=people). This will limits users search to specified DN.

userObjectFilter=[string] - User object filter (objectclass=inetorgperson)

userObjectClass=[string] - User object class (inetorgperson)

usernameAttribute=[string] - User name attribute (uid)

firstNameAttribute=[string - First name attribute (givenName)

lastNameAttribute=[string] - Last name attribute (sn)

emailAttribute=[string] - Email attribute (mail)

ldapDirectoryType=[string] - Directory type. Possible values are CustomLDAPServer, ActiveDirectory, OpenLDAP.

ssoEnabled=[boolean] - Whether SSO is enabled for this LDAP Server (true/false)

synchronizationEnabled=[boolean] - Whether synchronization is enabled for this LDAP Server (false/true)

defaultTeamEnabled=[boolean] – Whether to enable default team(false/true)

defaultRoleEnabled=[boolean] – Whether to enable default role(false/true)

defaultTeamId=[integer] - Default team Id

defaultRoleId=[integer] - Default role Id

updateTeamAndRoleUponLoginEnabled=[boolean] - Whether to update user’s role and team upon login (true/false)

periodicalSynchronizationEnabled=[boolean] - Whether to enable periodical synchronization (true/false)

advancedTeamAndRoleMappingEnabled=[boolean] - Whether to enable advanced team and role mapping (false/true)

additionalGroupDn=[string] - Additional group DN (ou=groups). This will limit groups search to specified DN.

groupObjectClass=[string] - Group object class (groupOfUniqueNames)

groupObjectFilter=[string] - Group object filter (objectClass=groupOfUniqueNames)

groupNameAttribute=[string] - Group name attribute (cn)

groupMembersAttribute=[string] - Group members attribute (uniqueMember)

userMembershipAttribute=[string] - User membership attribute (memberOf)

Success Response:

Code: 201 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Sample Response:

no content

Notes:

Returns the location of the created LDAP Server in the response header. Once the request is successful, it does not return any additional content. If the request fails, it returns an error response.

Get LDAP Server by Id - GET /LDAPServers/{id}

Get details of an LDAP Server according to LDAP Server Id.

Notice

The ‘Manage Authentication Providers’ permission is required to execute this API.

Usage:

GET /LDAPServers/{id} and get details of an LDAP Server
PUT /LDAPServers/{id} and update LDAP Server details

URL

/cxrestapi/auth/LDAPServers/{id}

Method:

GET

Media Type (header):

Authorization: Bearer <access token value>

Accept: application/json;v=1.0

Parameters

Required:

id=[integer] - Unique Id of the LDAP Server. LDAP Server Id (id) is retrieved using the LDAP Servers API.

Success Response:

Code: 200 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Not Found

Sample Response:

[
  {
    "id": 2,
    "active": true,
    "name": "microsoft.ldap",
    "host": "0.0.0.0",
    "port": 389,
    "username": "cn=admin,dc=example,dc=com",
    "useSsl": false,
    "verifySslCertificate": false,
    "ldapDirectoryType": "ActiveDirectory",
    "ssoEnabled": false,
    "mappedDomainId": null,
    "baseDn": "ou=automation,dc=example,dc=com",
    "additionalUserDn": "ou=people",
    "userObjectFilter": "(&(objectClass=inetOrgPerson)(uid=*))",
    "userObjectClass": "inetOrgPerson",
    "usernameAttribute": "uid",
    "firstNameAttribute": "givenName",
    "lastNameAttribute": "sn",
    "emailAttribute": "mail",
    "synchronizationEnabled": true,
    "defaultTeamId": 1,
    "defaultRoleId": 1,
    "updateTeamAndRoleUponLoginEnabled": false,
    "periodicalSynchronizationEnabled": true,
    "advancedTeamAndRoleMappingEnabled": false,
    "additionalGroupDn": "ou=groups",
    "groupObjectClass": "groupOfUniqueNames",
    "groupObjectFilter": "(objectClass=groupOfUniqueNames)",
    "groupNameAttribute": "cn",
    "groupMembersAttribute": "uniqueMember",
    "userMembershipAttribute": "memberOf"
  }
]

Notes:

Retrieves details of an LDAP Server according to the defined LDAP Server Id. If the request fails, it returns an error response.

Update LDAP Server - PUT /LDAPServers/{id}

Update LDAP Server details according to LDAP Server Id.

Notice

The ‘Manage Authentication Providers’ permission is required to execute this API.

Usage:

GET /LDAPServers/{id} and get details of an LDAP Server
POST /LDAPServers/TestConnection and test LDAP Server connection
PUT /LDAPServers/{id} and update LDAP Server details

URL

/cxrestapi/auth/LDAPServers/{id}

Method:

PUT

Media Type (header):

Authorization: Bearer <access token value>

Content-Type: application/json;v=1.0

Parameters

Required:

id=[integer] - Unique Id of the LDAP Server. LDAP Server Id (id) is retrieved using the LDAP Servers API.

updateLdapServerModel=[body]: Specifies the LDAP Server details to update

password=[string] - Password of the binding user

active=[boolean] - Whether this LDAP Server setting is active (true/false)

name=[string] - Ldap Server display name in Checkmarx

host=[string] - LDAP Server host name

port=[integer] - LDAP Server Port

username=[string] - Username of the binding user

useSsl=[boolean] - Whether to use SSL when connecting to this LDAP Server (false/true)

verifySslCertificate=[boolean] - Whether to verify SSL certificate (false/true)

baseDn=[string] - LDAP Server base DN

additionalUserDn=[string] - Additional user DN. This will limits users search to specified DN.

userObjectFilter=[string] - User object filter

userObjectClass=[string] - User object class

usernameAttribute=[string] - User name attribute

firstNameAttribute=[string - First name attribute

lastNameAttribute=[string] - Last name attribute

emailAttribute=[string] - Email attribute

ldapDirectoryType=[string] - Directory type. Possible values are CustomLDAPServer, ActiveDirectory, OpenLDAP.

ssoEnabled=[boolean] - Whether SSO is enabled for this LDAP Server (true/false)

synchronizationEnabled=[boolean] - Whether synchronization is enabled for this LDAP Server (false/true)

defaultTeamId=[integer] - Default team Id

defaultRoleId=[integer] - Default role Id

defaultTeamEnabled=[boolean] – Whether to enable default team(false/true)

defaultRoleEnabled=[boolean] – Whether to enable default role(false/true)

updateTeamAndRoleUponLoginEnabled=[boolean] - Whether to update user’s role and team upon login (true/false)

periodicalSynchronizationEnabled=[boolean] - Whether to enable periodical synchronization (true/false)

advancedTeamAndRoleMappingEnabled=[boolean] - Whether to enable advanced team and role mapping (false/true)

additionalGroupDn=[string] - Additional group Dn. This will limit groups search to specified DN.

groupObjectClass=[string] - Group object class

groupObjectFilter=[string] - Group object filter

groupNameAttribute=[string] - Group name attribute

groupMembersAttribute=[string] - Group members attribute

userMembershipAttribute=[string] - User membership attribute

Success Response:

Code: 204 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Not found

Sample Response:

no content

Notes:

Updates an LDAP Server according to the LDAP Server Id and the defined parameters. Once the request is successful, it does not return any content. If the request fails, it returns an error response.

Delete LDAP Server – DELETE /LDAPServers/{id}

Delete an LDAP Server according to LDAP Server Id. Note that this action permanently deletes all related users.

Notice

The ‘Manage Authentication Providers’ permission is required to execute this API.

Usage:

GET /LDAPServers and get details of all LDAP Servers
DELETE /LDAPServers/{id} and delete an LDAP Server

URL

/cxrestapi/auth/LDAPServers/{id}

Method:

DELETE

Media Type (header):

Authorization: Bearer <access token value>

Content-Type: application/json;v=1.0

Parameters

Required:

id=[integer] - Unique Id of the LDAP Server. LDAP Server Id (id) is retrieved using the LDAP Servers API.

Success Response:

Code: 204 Success

Error Response:

Code: 400 Bad Request

Code: 401 Unauthorized

Code: 403 Forbidden

Code: 404 Not found

Sample Response:

no content

Notes:

Deletes the LDAP Server according to the LDAP Server Id. Once the request is successful, it does not return any content. If the request fails, it returns an error response.

In this section: