User Repository for LDAP REST API

The Repository/Ldap endpoint allows binding and managing an LDAP user repository to ActivID Appliance.

Note: The API version supported by ActivID Appliance 8.7 is 3.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.

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