User Repository for LDAP REST API

The Repository/Ldap endpoint allows binding and managing an LDAP user repository to HID Authentication Service.

Note: The API version supported by HID Authentication Service is 10.1.0.

To use the version-specific parameters/attributes, you must add api-version=N to the query parameter.

Previous versions of the API are also supported with the corresponding functionality. For details of the version updates, see SCIM API Revision History.

Method Details

HTTPS Method Entity Action Request URI Description

GET

Read

/configuration/{tenant}/v2/User/Repository/Ldap

Retrieve the list of all LDAP user repositories

GET

Read

/configuration/{tenant}/v2/User/Repository/Ldap/{uid}

Retrieve an LDAP user repository

POST

Create

/configuration/{tenant}/v2/User/Repository/Ldap

Create an LDAP user repository

PUT

Replace

/configuration/{tenant}/v2/User/Repository/Ldap/{uid}

Replace an LDAP user repository

DELETE

Delete

/configuration/{tenant}/v2/User/Repository/Ldap/{uid}

Delete an LDAP user repository

Required Permissions

Function Required Permissions

GET

  • Read reference data

GET ALL

  • Read reference data

CREATE

  • Read reference data

  • LDAP Configuration

REPLACE

  • Read reference data

  • LDAP Configuration

DELETE

  • Read reference data

  • LDAP Configuration

TEST CONNECTION

  • Read reference data

  • LDAP Configuration

Get All LDAP User Repositories

GET /User/Repository/Ldap

Copy

Sample Request URI

GET /configuration/{tenant}/v2/User/Repository/Ldap
Copy

Sample Response

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
   "totalResults": 2,
   "resources":    [
            {
      "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
      "id": "DS_1101",
      "meta":       {
         "resourceType": "UserRepository",
         "location": "https://[base-server-url]/configuration/tenant/v2/User/Repository/Ldap/DS_1101",
         "version": "1"
      },
      "name": "MyUserRepository",
      "type": "LDAP",
      "host":       {
         "address": "host.company.com",
         "port": "636",
         "baseNodeDn": "DC=Domain,DC=Company,DC=com",
         "loginCredentials": {"userDn": "CN=Administrator,CN=Users,DC=Domain,DC=Company,DC=com"}
      },
      "mappingConfiguration":       {
         "userClass": "Person",
         "ldapGroupClass": "group",
         "userIdAttribute": "sAMAccountName",
         "groupMemberAttribute": "memberOf",
         "accountStatusAttribute": "UserAccountControl",
         "guidAttributeName": "objectguid"
      },
      "userAttributesMapping":       [
                  {
            "activIdAttribute": "LASTNAME",
            "ldapAttribute": "SURNAME"
         },
                  {
            "activIdAttribute": "FIRSTNAME",
            "ldapAttribute": "GIVENNAME"
         }
      ],
      "referralStrategy": "followNone",
      "referrals": [],
      "userTypeAssignments": [      {
         "groupId": "UT_EMP",
         "rootNodeDn": "DC=Domain,DC=Company,DC=com"
      }],
      "userGroupAssignments": [      {
         "groupId": "USG_FTEMP",
         "rootNodeDn": "DC=Domain,DC=Company,DC=com"
      }],
      "roleAssignments":       [
                  {
            "roleId": "RL_CMSADM",
            "mappingType": "OU",
            "groupDnOrOu": "OU=OUBASE,DC=Domain,DC=Company,DC=com"
         },
                  {
            "roleId": "RL_AUDITV",
            "mappingType": "GROUP",
            "groupDnOrOu": "CN=admGR1,OU=OUGROUPS,DC=Domain,DC=Company,DC=com"
         }
      ]
   },
            {
         "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
         "id": "DS_1102",
    <-------- truncated ---------->
   ]
}}

Get LDAP User Repository

GET /User/Repository/Ldap/{uid}

Copy

Sample Request URI

GET /configuration/{tenant}/v2/User/Repository/Ldap/DS_1102
Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
   "id": "DS_1102",
   "meta":    {
      "resourceType": "UserRepository",
      "location":"https://[base-server-url]/configuration/tenant/v2/User/Repository/Ldap/DS_1102",
      "version": "1"
   },
   "name": "MyUserRepository",
   "type": "LDAP",
   "host":    {
      "address": "host.company.com",
      "port": "636",
      "baseNodeDn": "DC=Domain,DC=Company,DC=com",
      "ldapsRootCaCertificate": "MIIDrTCCApWgAwIBAgIQGDt7HU <-- truncated --> kDkIk",
      "loginCredentials": {"userDn": "CN=Administrator,CN=Users,DC=Domain,DC=Company,DC=com"}
   },
   "mappingConfiguration":    {
      "userClass": "Person",
      "ldapGroupClass": "group",
      "userIdAttribute": "sAMAccountName",
      "groupMemberAttribute": "memberOf",
      "accountStatusAttribute": "UserAccountControl",
      "guidAttributeName": "objectguid"
   },
   "userAttributesMapping": [   {
      "activIdAttribute": "FIRSTNAME",
      "ldapAttribute": "GIVENNAME"
   }],
   "referralStrategy": "followNone"
   "referrals": [],
   "userTypeAssignments": [],
   "userGroupAssignments": [],
   "roleAssignments": []
}

Create LDAP User Repository

POST /User/Repository/Ldap

Copy

Sample Request URI

POST /configuration/{tenant}/v2/User/Repository/Ldap
Copy

Sample Request

{
    "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
    "id": "DS_1101",
    "name": " MyUserRepository",
    "type": "LDAP",
    "host": {
        "address": "host.company.com",
        "port": "636",
        "baseNodeDn": "DC=Domain,DC=Company,DC=com",
        "ldapsRootCaCertificate": "MIIDrTCCApWgAwIBAgIQGDt7HU <-- truncated --> kDkIk",
        "loginCredentials": {
            "userDn": "CN=Administrator,CN=Users,DC=Domain,DC=Company,DC=com",
            "userPassword": "MyUserPassword"
        }
    },
    "userAttributesMapping": [{
            "activIdAttribute": "FIRSTNAME",
            "ldapAttribute": "GIVENNAME"
        }
    ]
}
Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
   "id": "DS_1101",
   "meta":    {
      "resourceType": "UserRepository",
      "location": "https://[base-server-url]/configuration/tenant/v2/User/Repository/Ldap/DS_1102",
      "version": "1"
   },
   "name": "MyUserRepository",
   "type": "LDAP",
   "host":    {
      "address": "host.company.com",
      "port": "636",
      "baseNodeDn": "DC=Domain,DC=Company,DC=com",
      "ldapsRootCaCertificate": "MIIDrTCCApWgAwIBAgIQGDt7HU <-- truncated --> kDkIk",
      "loginCredentials": {"userDn": "CN=Administrator,CN=Users,DC=Domain,DC=Company,DC=com"}
   },
   "mappingConfiguration":    {
      "userClass": "Person",
      "ldapGroupClass": "group",
      "userIdAttribute": "sAMAccountName",
      "groupMemberAttribute": "memberOf",
      "accountStatusAttribute": "UserAccountControl",
      "guidAttributeName": "objectguid"
   },
   "userAttributesMapping": [   {
      "activIdAttribute": "FIRSTNAME",
      "ldapAttribute": "GIVENNAME"
   }],
   "referralStrategy": "followNone"
   "referrals": [],
   "userTypeAssignments": [],
   "userGroupAssignments": [],
   "roleAssignments": []
}

Replace LDAP User Repository

PUT /User/Repository/Ldap/{uid}

Note: As a best practice, use GET to retrieve the current data for the resource before using PUT.
Important:  

  • id can NOT be changed. All other parameters can be updated.

  • id in the request body is not mandatory but if it is specified in the request body, it must be the same as the one in URL

  • For all array parameters (that is, userTypeAssignments, userGroupAssignments and roleAssignments), PUT is a replace operation.

    • For example (see the sample request below), by indicating userAttributesMapping: [ ] in the request, any mapping will be removed. In addition, if the binding is not included, FIRSTNAME will be removed as well.

User Attributes Mapping

In this example, DS_1101 (see Create LDAP User Repository) is updated to add a new user attribute mapping (bind LDAP attribute SURNAME to ActivID attribute LASTNAME").

Copy

Sample request URI

PUT /configuration/{tenant}/v2/User/Repository/Ldap/DS_1101
Copy

Sample Request

{
   "id": "DS_1101",
   "userAttributesMapping": [   {
      "activIdAttribute": "FIRSTNAME",
      "ldapAttribute": "GIVENNAME"
   }, {
      "activIdAttribute": "LASTNAME",
      "ldapAttribute": "SURNAME"
   }]
}
Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
   "id": "DS_1101",
   "meta":    {
      "resourceType": "UserRepository",
      "location": "https://[base-server-url]/configuration/tenant/v2/User/Repository/Ldap/DS_1101",
      "version": "1"
   },
   "name": "MyUserRepository",
   "type": "LDAP",
   "host":    {
      "address": "host.company.com",
      "port": "636",
      "baseNodeDn": "DC=Domain,DC=Company,DC=com",
      "ldapsRootCaCertificate": "MIIDrTCCApWgAwIBAgIQGDt7HU <-- truncated --> kDkIk",
      "loginCredentials": {"userDn": "CN=Administrator,CN=Users,DC=Domain,DC=Company,DC=com"}
   },
   "mappingConfiguration":    {
      "userClass": "Person",
      "ldapGroupClass": "group",
      "userIdAttribute": "sAMAccountName",
      "groupMemberAttribute": "memberOf",
      "accountStatusAttribute": "UserAccountControl",
      "guidAttributeName": "objectguid"
   },
   "userAttributesMapping":    [
            {
         "activIdAttribute": "LASTNAME",
         "ldapAttribute": "SURNAME"
      },
            {
         "activIdAttribute": "FIRSTNAME",
         "ldapAttribute": "GIVENNAME"
      }
   ],
   "referralStrategy": "followNone",
   "referrals": [],
   "userTypeAssignments": [],
   "userGroupAssignments": [],
   "roleAssignments": []
}

User Groups Mapping

In this example, DS_1101 (see User Attributes Mapping) is updated to bind the users in the node "DC=Domain,DC=Company,DC=com" to the user group "Full Time Employee" (USG_FTEMP).

A root node DN is also assigned to the corresponding User Type "Employee" (UT_EMP).

Copy

Sample request URI

PUT /configuration/{tenant}/v2/User/Repository/Ldap/DS_1101
Copy

Sample Request

{
    "id": "DS_1101",
    "userTypeAssignments": [{
            "groupId": "UT_EMP",
            "rootNodeDn": "DC=Domain,DC=Company,DC=com"
        }
    ],
    "userGroupAssignments": [{
            "groupId": "USG_FTEMP",
            "rootNodeDn": "DC=Domain,DC=Company,DC=com"
        }
    ]
}
Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
   "id": "DS_1101",
   "meta":    {
      "resourceType": "UserRepository",
      "location": "https://[base-server-url]/configuration/tenant/v2/User/Repository/Ldap/DS_1101",
      "version": "1"
   },
   "name": "MyUserRepository",
   "type": "LDAP",
   "host":    {
      "address": "host.company.com",
      "port": "636",
      "baseNodeDn": "DC=Domain,DC=Company,DC=com",
      "ldapsRootCaCertificate": "MIIDrTCCApWgAwIBAgIQGDt7HU <-- truncated --> kDkIk",
      "loginCredentials": {"userDn": "CN=Administrator,CN=Users,DC=Domain,DC=Company,DC=com"}
   },
   "mappingConfiguration":    {
      "userClass": "Person",
      "ldapGroupClass": "group",
      "userIdAttribute": "sAMAccountName",
      "groupMemberAttribute": "memberOf",
      "accountStatusAttribute": "UserAccountControl",
      "guidAttributeName": "objectguid"
   },
   "userAttributesMapping":    [
            {
         "activIdAttribute": "LASTNAME",
         "ldapAttribute": "SURNAME"
      },
            {
         "activIdAttribute": "FIRSTNAME",
         "ldapAttribute": "GIVENNAME"
      }
   ],
   "referralStrategy": "followNone",
   "referrals": [],
   "userTypeAssignments": [   {
      "groupId": "UT_EMP",
      "rootNodeDn": "DC=Domain,DC=Company,DC=com"
   }],
   "userGroupAssignments": [   {
      "groupId": "USG_FTEMP",
      "rootNodeDn": "DC=Domain,DC=Company,DC=com"
   }],
   "roleAssignments": []
}

Role Assignment

In this example, DS_1101 (see User Groups Mapping) is updated to assign the following roles:

  • The RL_CMSADM role is assigned to the users in the OU: "OU=OUBASE,DC=Domain,DC=Company,DC=com"

  • RL_AUDITV role is assigned to the users in the "CN=admGR1,OU=OUGROUPS,DC=Domain,DC=Company,DC=com" group

Copy

Sample request URI

PUT /configuration/{tenant}/v2/User/Repository/Ldap/DS_1101
Copy

Sample Request

{
    "id": "DS_1101",
    "roleAssignments": [{
            "roleId": "RL_CMSADM",
            "mappingType": "OU",
            "groupDnOrOu": "OU=OUBASE,DC=Domain,DC=Company,DC=com"
        }, {
            "roleId": "RL_AUDITV",
            "mappingType": "GROUP",
            "groupDnOrOu": "CN=admGR1,OU=OUGROUPS,DC=Domain,DC=Company,DC=com"
        }
    ]
}
Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
   "id": "DS_1101",
   "meta":    {
      "resourceType": "UserRepository",
      "location": "https://[base-server-url]/configuration/tenant/v2/User/Repository/Ldap/DS_1101",
      "version": "1"
   },
   "name": "MyUserRepository",
   "type": "LDAP",
   "host":    {
      "address": "host.company.com",
      "port": "636",
      "baseNodeDn": "DC=Domain,DC=Company,DC=com",
      "ldapsRootCaCertificate": "MIIDrTCCApWgAwIBAgIQGDt7HU <-- truncated --> kDkIk",
      "loginCredentials": {"userDn": "CN=Administrator,CN=Users,DC=Domain,DC=Company,DC=com"}
   },
   "mappingConfiguration":    {
      "userClass": "Person",
      "ldapGroupClass": "group",
      "userIdAttribute": "sAMAccountName",
      "groupMemberAttribute": "memberOf",
      "accountStatusAttribute": "UserAccountControl",
      "guidAttributeName": "objectguid"
   },
   "userAttributesMapping":    [
            {
         "activIdAttribute": "LASTNAME",
         "ldapAttribute": "SURNAME"
      },
            {
         "activIdAttribute": "FIRSTNAME",
         "ldapAttribute": "GIVENNAME"
      }
   ],
   "referralStrategy": "followNone",
   "referrals": [],
   "userTypeAssignments": [   {
      "groupId": "UT_EMP",
      "rootNodeDn": "DC=Domain,DC=Company,DC=com"
   }],
   "userGroupAssignments": [   {
      "groupId": "USG_FTEMP",
      "rootNodeDn": "DC=Domain,DC=Company,DC=com"
   }],
   "roleAssignments":    [
            {
         "roleId": "RL_CMSADM",
         "mappingType": "OU",
         "groupDnOrOu": "OU=OUBASE,DC=Domain,DC=Company,DC=com"
      },
            {
         "roleId": "RL_AUDITV",
         "mappingType": "GROUP",
         "groupDnOrOu": "CN=admGR1,OU=OUGROUPS,DC=Domain,DC=Company,DC=com"
      }
   ]
}

Add Referral

In this example, DS_1101 (see Role Assignment) is updated to add a new referral to follow.

referralStrategy can be set to:

  • followAll – follow all referrals (not compatible with Microsoft® Active Directory)

  • followNone – no referral to follow

  • followListed – follow the referral(s) listed in referrals object

Copy

Sample request URI

PUT /configuration/{tenant}/v2/User/Repository/Ldap/DS_1101
Copy

Sample Request

{
    "id": "DS_1101",
    "referralStrategy": "followListed",
    "referrals": [{
            "address": "host2.company.com",
            "port": "636",
            "loginCredentials": {
                "userDn": "CN=Administrator,CN=Users,DC=Domain,DC=Company,DC=com,DC=ref",
                "userPassword": "referralServerPwd"
            }
        }
    ]
}
Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
   "id": "DS_1101",
   "meta":    {
      "resourceType": "UserRepository",
      "location": "https://[base-server-url]/configuration/tenant/v2/User/Repository/Ldap/DS_1101",
      "version": "1"
   },
   "name": "MyUserRepository",
   "type": "LDAP",
   "host":    {
      "address": "host.company.com",
      "port": "636",
      "baseNodeDn": "DC=Domain,DC=Company,DC=com",
      "ldapsRootCaCertificate": "MIIDrTCCApWgAwIBAgIQGDt7HU <-- truncated --> kDkIk",
      "loginCredentials": {"userDn": "CN=Administrator,CN=Users,DC=Domain,DC=Company,DC=com"}
   },
   "mappingConfiguration":    {
      "userClass": "Person",
      "ldapGroupClass": "group",
      "userIdAttribute": "sAMAccountName",
      "groupMemberAttribute": "memberOf",
      "accountStatusAttribute": "UserAccountControl",
      "guidAttributeName": "objectguid"
   },
   "userAttributesMapping":    [
            {
         "activIdAttribute": "LASTNAME",
         "ldapAttribute": "SURNAME"
      },
            {
         "activIdAttribute": "FIRSTNAME",
         "ldapAttribute": "GIVENNAME"
      }
   ],
   "referralStrategy": "followListed",
   "referrals": [   {
      "address": "host2.company.com",
      "port": "636",
      "loginCredentials": {"userDn": "CN=Administrator,CN=Users,DC=Domain,DC=Company,DC=com,DC=ref"}
   }],
   "userTypeAssignments": [   {
      "groupId": "UT_EMP",
      "rootNodeDn": "DC=Domain,DC=Company,DC=com"
   }],
   "userGroupAssignments": [   {
      "groupId": "USG_FTEMP",
      "rootNodeDn": "DC=Domain,DC=Company,DC=com"
   }],
   "roleAssignments":    [
            {
         "roleId": "RL_CMSADM",
         "mappingType": "OU",
         "groupDnOrOu": "OU=OUBASE,DC=Domain,DC=Company,DC=com"
      },
            {
         "roleId": "RL_AUDITV",
         "mappingType": "GROUP",
         "groupDnOrOu": "CN=admGR1,OU=OUGROUPS,DC=Domain,DC=Company,DC=com"
      }
   ]
}

Delete LDAP User Repository

DELETE /User/Repository/Ldap/{uid}

  • If there are no users or groups bound to it, the datasource is deleted directly and the sessions for the provisioning agent are removed.
  • If the datasource does have bound users and groups, it is marked "to be deleted" and as a background process:

    1. SearchUsers is called to find all users provisioned by the datasource and they are deleted (progressively to avoid impacting the service).

    2. When all the users are deleted, the security groups bound to this datasource are deleted.

    3. Then the datasource itself is deleted.

Important: As soon as a datasource is marked 'to be deleted':

  • You can no longer provision users with the associated provisioning agent.

  • All authentications are blocked for the users provisioned with this datasource and will return the failure response ‘REASON_USER_REPO_DELETED’:

    Copy

    Sample Response

    HTTP/1.1 400 Bad Request
    {
       "hid_failure":    {
          "reason": 60,
          "authType": "AT_LDAP"
       },
       "error_description": "Invalid grant: Resource owner username or password is invalid (User repository is deleted):Resource owner username or password is invalid",
       "error": "invalid_grant"
    }
Important: As soon as a datasource is marked 'to be deleted':

  • You can no longer provision users with the associated provisioning agent.

  • All authentications are blocked for the users provisioned with this datasource and will return the failure response ‘REASON_USER_REPO_DELETED’:

    Copy

    Sample Response

    HTTP/1.1 400 Bad Request
    {
       "hid_failure":    {
          "reason": 60,
          "authType": "AT_LDAP"
       },
       "error_description": "Invalid grant: Resource owner username or password is invalid (User repository is deleted):Resource owner username or password is invalid",
       "error": "invalid_grant"
    }
Copy

Sample Request URI

DELETE /configuration/{tenant}/v2/User/Repository/Ldap/DS_1101
Copy

Sample Request

{
    "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
    "id": "DS_1101",
    "name": " MyUserRepository",
    "type": "LDAP",
    "host": {
        "address": "host.company.com",
        "port": "636",
        "baseNodeDn": "DC=Domain,DC=Company,DC=com",
        "ldapsRootCaCertificate": "MIIDrTCCApWgAwIBAgIQGDt7HU <-- truncated --> kDkIk",
        "loginCredentials": {
            "userDn": "CN=Administrator,CN=Users,DC=Domain,DC=Company,DC=com",
            "userPassword": "MyUserPassword"
        }
    },
    "userAttributesMapping": [{
            "activIdAttribute": "FIRSTNAME",
            "ldapAttribute": "GIVENNAME"
        }
    ]
}
Copy

Sample Response

{
   "schemas": ["urn:hid:scim:api:idp:2.0:User:Repository"],
   "id": "DS_1101",
   "meta":    {
      "resourceType": "UserRepository",
      "location": "https://[base-server-url]/configuration/tenant/v2/User/Repository/Ldap/DS_1102",
      "version": "1"
   },
   "name": "MyUserRepository",
    "type": "LDAP",
   "host":    {
      "address": "host.company.com",
      "port": "636",
      "baseNodeDn": "DC=Domain,DC=Company,DC=com",
      "ldapsRootCaCertificate": "MIIDrTCCApWgAwIBAgIQGDt7HU <-- truncated --> kDkIk",
      "loginCredentials": {"userDn": "CN=Administrator,CN=Users,DC=Domain,DC=Company,DC=com"}
   },
   "mappingConfiguration":    {
      "userClass": "Person",
      "ldapGroupClass": "group",
      "userIdAttribute": "sAMAccountName",
      "groupMemberAttribute": "memberOf",
      "accountStatusAttribute": "UserAccountControl",
      "guidAttributeName": "objectguid"
   },
   "userAttributesMapping": [   {
      "activIdAttribute": "FIRSTNAME",
      "ldapAttribute": "GIVENNAME"
   }],
   "referralStrategy": "followNone"
   "referrals": [],
   "userTypeAssignments": [],
   "userGroupAssignments": [],
   "roleAssignments": []
}