Endurance
Get started

LDAP

Configuration

Get the LDAP configuration. A stored bind password is masked; with none stored it is empty.

GET /ldap/config

curl
curl -X GET "https://appliance.example.com/api/v1/ldap/config" \
  -H "Authorization: Bearer $TOKEN"
PHP
<?php

$url = 'https://appliance.example.com/api/v1/ldap/config';
$headers = [
    'Authorization: Bearer ' . $token,
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
Python
import requests

headers = {"Authorization": f"Bearer {token}"}

response = requests.get("https://appliance.example.com/api/v1/ldap/config", headers=headers)
response.raise_for_status()
print(response.json())
JavaScript
const response = await fetch('https://appliance.example.com/api/v1/ldap/config', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const data = await response.json();
Bruno
meta {
  name: Get the LDAP settings
  type: http
  seq: 1
}

get {
  url: https://{{node-0}}:{{port}}/api/v1/ldap/config
  body: none
  auth: bearer
}

auth:bearer {
  token: {{token}}
}
Response
{
  "status": "success",
  "message": "LDAP configuration",
  "data": [
    {
      "bindPassword": "********",
      "bindDn": "cn=svc,dc=example,dc=com",
      "baseDn": "dc=example,dc=com",
      "encryption": "none"
    }
  ]
}

Replace the LDAP configuration and group mappings. The body is the whole section: a field it omits is stored at that field’s default rather than left as it was, so send the configuration back in full. A host, a Base DN and a unique-id attribute are required whether or not enabled is set, which is why DELETE is the only way back to an empty section. Refused while a transaction is open. Commit or roll back the transaction first.

PUT /ldap/config

This change is staged. Send PUT /services/apply to apply it.

Body parameters
enabled boolean

Whether LDAP is offered as a login type.

hosts array of string Required

Directory hosts, tried in order for failover.

port integer
encryption none | ssl | starttls
caCertificate string

PEM CA certificate the directory’s TLS is verified against.

bindDn string
bindPassword string

Read back masked, or empty when none is stored. Send the mask or an empty string to keep the stored password; DELETE is what removes it. With none stored the mask is refused, and an empty string is refused when bindDn is set. Leave both empty for an anonymous bind.

baseDn string Required
userSearchFilter string

Must contain the %s placeholder the escaped login value is written into.

uniqueIdAttribute string

The attribute a directory user is provisioned against, so it cannot be sent empty. Omitted, it stays at the default rather than being cleared.

emailAttribute string
firstNameAttribute string
lastNameAttribute string
groupMembershipMode memberOf | searchFilter

How group membership is resolved: from the user’s memberOf attribute, or by searching with groupSearchFilter.

groupSearchFilter string

Must contain the %s placeholder, whichever membership mode is in use.

fallbackGroupId string

Appliance group id assigned when no mapping matches. Empty for none.

mappings array of object

Directory group to appliance group rules. Replaced wholesale.

Fields
groupDn string Required
groupIds array of string

Appliance group ids granted to a member of groupDn.

curl
curl -X PUT "https://appliance.example.com/api/v1/ldap/config" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "enabled": true,
  "hosts": [
    "<hosts>"
  ],
  "port": 0,
  "encryption": "none",
  "caCertificate": "<caCertificate>",
  "bindDn": "<bindDn>",
  "bindPassword": "<bindPassword>",
  "baseDn": "<baseDn>",
  "userSearchFilter": "<userSearchFilter>",
  "uniqueIdAttribute": "<uniqueIdAttribute>",
  "emailAttribute": "<emailAttribute>",
  "firstNameAttribute": "<firstNameAttribute>",
  "lastNameAttribute": "<lastNameAttribute>",
  "groupMembershipMode": "memberOf",
  "groupSearchFilter": "<groupSearchFilter>",
  "fallbackGroupId": "<fallbackGroupId>",
  "mappings": [
    {
      "groupDn": "<groupDn>",
      "groupIds": [
        "<groupIds>"
      ]
    }
  ]
}'
PHP
<?php

$url = 'https://appliance.example.com/api/v1/ldap/config';
$headers = [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json',
];

$payload = [
    'enabled' => true,
    'hosts' => [
        '<hosts>',
    ],
    'port' => 0,
    'encryption' => 'none',
    'caCertificate' => '<caCertificate>',
    'bindDn' => '<bindDn>',
    'bindPassword' => '<bindPassword>',
    'baseDn' => '<baseDn>',
    'userSearchFilter' => '<userSearchFilter>',
    'uniqueIdAttribute' => '<uniqueIdAttribute>',
    'emailAttribute' => '<emailAttribute>',
    'firstNameAttribute' => '<firstNameAttribute>',
    'lastNameAttribute' => '<lastNameAttribute>',
    'groupMembershipMode' => 'memberOf',
    'groupSearchFilter' => '<groupSearchFilter>',
    'fallbackGroupId' => '<fallbackGroupId>',
    'mappings' => [
        [
            'groupDn' => '<groupDn>',
            'groupIds' => [
                '<groupIds>',
            ],
        ],
    ],
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
Python
import requests

headers = {"Authorization": f"Bearer {token}"}
payload = {
    "enabled": true,
    "hosts": [
        "<hosts>"
    ],
    "port": 0,
    "encryption": "none",
    "caCertificate": "<caCertificate>",
    "bindDn": "<bindDn>",
    "bindPassword": "<bindPassword>",
    "baseDn": "<baseDn>",
    "userSearchFilter": "<userSearchFilter>",
    "uniqueIdAttribute": "<uniqueIdAttribute>",
    "emailAttribute": "<emailAttribute>",
    "firstNameAttribute": "<firstNameAttribute>",
    "lastNameAttribute": "<lastNameAttribute>",
    "groupMembershipMode": "memberOf",
    "groupSearchFilter": "<groupSearchFilter>",
    "fallbackGroupId": "<fallbackGroupId>",
    "mappings": [
        {
            "groupDn": "<groupDn>",
            "groupIds": [
                "<groupIds>"
            ]
        }
    ]
}

response = requests.put("https://appliance.example.com/api/v1/ldap/config", headers=headers, json=payload)
response.raise_for_status()
print(response.json())
JavaScript
const response = await fetch('https://appliance.example.com/api/v1/ldap/config', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "enabled": true,
  "hosts": [
    "<hosts>"
  ],
  "port": 0,
  "encryption": "none",
  "caCertificate": "<caCertificate>",
  "bindDn": "<bindDn>",
  "bindPassword": "<bindPassword>",
  "baseDn": "<baseDn>",
  "userSearchFilter": "<userSearchFilter>",
  "uniqueIdAttribute": "<uniqueIdAttribute>",
  "emailAttribute": "<emailAttribute>",
  "firstNameAttribute": "<firstNameAttribute>",
  "lastNameAttribute": "<lastNameAttribute>",
  "groupMembershipMode": "memberOf",
  "groupSearchFilter": "<groupSearchFilter>",
  "fallbackGroupId": "<fallbackGroupId>",
  "mappings": [
    {
      "groupDn": "<groupDn>",
      "groupIds": [
        "<groupIds>"
      ]
    }
  ]
}),
});

const data = await response.json();
Bruno
meta {
  name: Update the LDAP settings
  type: http
  seq: 1
}

put {
  url: https://{{node-0}}:{{port}}/api/v1/ldap/config
  body: json
  auth: bearer
}

headers {
  Content-Type: application/json
}

auth:bearer {
  token: {{token}}
}

body:json {
  {
    "enabled": true,
    "hosts": [
      "<hosts>"
    ],
    "port": 0,
    "encryption": "none",
    "caCertificate": "<caCertificate>",
    "bindDn": "<bindDn>",
    "bindPassword": "<bindPassword>",
    "baseDn": "<baseDn>",
    "userSearchFilter": "<userSearchFilter>",
    "uniqueIdAttribute": "<uniqueIdAttribute>",
    "emailAttribute": "<emailAttribute>",
    "firstNameAttribute": "<firstNameAttribute>",
    "lastNameAttribute": "<lastNameAttribute>",
    "groupMembershipMode": "memberOf",
    "groupSearchFilter": "<groupSearchFilter>",
    "fallbackGroupId": "<fallbackGroupId>",
    "mappings": [
      {
        "groupDn": "<groupDn>",
        "groupIds": [
          "<groupIds>"
        ]
      }
    ]
  }
}
Response
{
  "status": "success",
  "message": "LDAP configuration updated",
  "data": []
}

Return the LDAP configuration to its shipped state: disabled, with no host, no Base DN and no bind password. The required fields are enforced on an update whether or not LDAP is enabled, so this is the only way to empty the section. The JIT-provisioned LDAP users are not affected. Refused while a transaction is open. Commit or roll back the transaction first.

DELETE /ldap/config

This change is staged. Send PUT /services/apply to apply it.

curl
curl -X DELETE "https://appliance.example.com/api/v1/ldap/config" \
  -H "Authorization: Bearer $TOKEN"
PHP
<?php

$url = 'https://appliance.example.com/api/v1/ldap/config';
$headers = [
    'Authorization: Bearer ' . $token,
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
Python
import requests

headers = {"Authorization": f"Bearer {token}"}

response = requests.delete("https://appliance.example.com/api/v1/ldap/config", headers=headers)
response.raise_for_status()
print(response.json())
JavaScript
const response = await fetch('https://appliance.example.com/api/v1/ldap/config', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const data = await response.json();
Bruno
meta {
  name: Clear the LDAP settings
  type: http
  seq: 1
}

delete {
  url: https://{{node-0}}:{{port}}/api/v1/ldap/config
  body: none
  auth: bearer
}

auth:bearer {
  token: {{token}}
}
Response
{
  "status": "success",
  "message": "LDAP configuration cleared",
  "data": []
}

Test the LDAP connection

Test the LDAP connection without saving. A masked or empty bind password tests the stored one. The mask with none stored, and a bind DN with no password, are refused. Refused while a transaction is open. Commit or roll back the transaction first.

POST /ldap/config/test

This change is staged. Send PUT /services/apply to apply it.

curl
curl -X POST "https://appliance.example.com/api/v1/ldap/config/test" \
  -H "Authorization: Bearer $TOKEN"
PHP
<?php

$url = 'https://appliance.example.com/api/v1/ldap/config/test';
$headers = [
    'Authorization: Bearer ' . $token,
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
Python
import requests

headers = {"Authorization": f"Bearer {token}"}

response = requests.post("https://appliance.example.com/api/v1/ldap/config/test", headers=headers)
response.raise_for_status()
print(response.json())
JavaScript
const response = await fetch('https://appliance.example.com/api/v1/ldap/config/test', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const data = await response.json();
Bruno
meta {
  name: Test the LDAP connection
  type: http
  seq: 1
}

post {
  url: https://{{node-0}}:{{port}}/api/v1/ldap/config/test
  body: none
  auth: bearer
}

auth:bearer {
  token: {{token}}
}
Response
{
  "status": "success",
  "message": "Connection test complete",
  "data": {
    "stage": "bind",
    "ok": false
  }
}

List the LDAP users

Get all JIT-provisioned LDAP users

GET /ldap/users

curl
curl -X GET "https://appliance.example.com/api/v1/ldap/users" \
  -H "Authorization: Bearer $TOKEN"
PHP
<?php

$url = 'https://appliance.example.com/api/v1/ldap/users';
$headers = [
    'Authorization: Bearer ' . $token,
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
Python
import requests

headers = {"Authorization": f"Bearer {token}"}

response = requests.get("https://appliance.example.com/api/v1/ldap/users", headers=headers)
response.raise_for_status()
print(response.json())
JavaScript
const response = await fetch('https://appliance.example.com/api/v1/ldap/users', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const data = await response.json();
Bruno
meta {
  name: List the LDAP users
  type: http
  seq: 1
}

get {
  url: https://{{node-0}}:{{port}}/api/v1/ldap/users
  body: none
  auth: bearer
}

auth:bearer {
  token: {{token}}
}
Response
{
  "status": "success",
  "message": "All LDAP users",
  "data": []
}

Users by ID

Get an LDAP user by id

GET /ldap/users/{id}

Path parameters
id string Required
curl
curl -X GET "https://appliance.example.com/api/v1/ldap/users/{id}" \
  -H "Authorization: Bearer $TOKEN"
PHP
<?php

$url = 'https://appliance.example.com/api/v1/ldap/users/{id}';
$headers = [
    'Authorization: Bearer ' . $token,
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
Python
import requests

headers = {"Authorization": f"Bearer {token}"}

response = requests.get("https://appliance.example.com/api/v1/ldap/users/{id}", headers=headers)
response.raise_for_status()
print(response.json())
JavaScript
const response = await fetch('https://appliance.example.com/api/v1/ldap/users/{id}', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const data = await response.json();
Bruno
meta {
  name: Get an LDAP user
  type: http
  seq: 1
}

get {
  url: https://{{node-0}}:{{port}}/api/v1/ldap/users/{id}
  body: none
  auth: bearer
}

auth:bearer {
  token: {{token}}
}
Response
{
  "status": "success",
  "message": "Get LDAP user",
  "data": []
}

Enable or disable an LDAP user Refused while a transaction is open. Commit or roll back the transaction first.

PUT /ldap/users/{id}

This change is staged. Send PUT /services/apply to apply it.

Path parameters
id string Required

.Body parameters

disabled boolean Required
curl
curl -X PUT "https://appliance.example.com/api/v1/ldap/users/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "disabled": true
}'
PHP
<?php

$url = 'https://appliance.example.com/api/v1/ldap/users/{id}';
$headers = [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json',
];

$payload = [
    'disabled' => true,
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
Python
import requests

headers = {"Authorization": f"Bearer {token}"}
payload = {
    "disabled": true
}

response = requests.put("https://appliance.example.com/api/v1/ldap/users/{id}", headers=headers, json=payload)
response.raise_for_status()
print(response.json())
JavaScript
const response = await fetch('https://appliance.example.com/api/v1/ldap/users/{id}', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "disabled": true
}),
});

const data = await response.json();
Bruno
meta {
  name: Enable or disable an LDAP user
  type: http
  seq: 1
}

put {
  url: https://{{node-0}}:{{port}}/api/v1/ldap/users/{id}
  body: json
  auth: bearer
}

headers {
  Content-Type: application/json
}

auth:bearer {
  token: {{token}}
}

body:json {
  {
    "disabled": true
  }
}
Response
{
  "status": "success",
  "message": "LDAP user updated",
  "data": []
}

Delete an LDAP user record Refused while a transaction is open. Commit or roll back the transaction first.

DELETE /ldap/users/{id}

This change is staged. Send PUT /services/apply to apply it.

Path parameters
id string Required
curl
curl -X DELETE "https://appliance.example.com/api/v1/ldap/users/{id}" \
  -H "Authorization: Bearer $TOKEN"
PHP
<?php

$url = 'https://appliance.example.com/api/v1/ldap/users/{id}';
$headers = [
    'Authorization: Bearer ' . $token,
];

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);
Python
import requests

headers = {"Authorization": f"Bearer {token}"}

response = requests.delete("https://appliance.example.com/api/v1/ldap/users/{id}", headers=headers)
response.raise_for_status()
print(response.json())
JavaScript
const response = await fetch('https://appliance.example.com/api/v1/ldap/users/{id}', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const data = await response.json();
Bruno
meta {
  name: Delete an LDAP user
  type: http
  seq: 1
}

delete {
  url: https://{{node-0}}:{{port}}/api/v1/ldap/users/{id}
  body: none
  auth: bearer
}

auth:bearer {
  token: {{token}}
}
Response
{
  "status": "success",
  "message": "LDAP user deleted",
  "data": []
}