User Repository for LDAP REST API
The Repository/Ldap endpoint allows binding and managing an LDAP user repository to ActivID AS.
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 |
|
GET ALL |
|
CREATE |
|
REPLACE |
|
DELETE |
|
TEST CONNECTION |
|
Get All LDAP User Repositories
GET /User/Repository/Ldap
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}
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
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"
}
]
}
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}
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").
Sample Request
{
"id": "DS_1101",
"userAttributesMapping": [ {
"activIdAttribute": "FIRSTNAME",
"ldapAttribute": "GIVENNAME"
}, {
"activIdAttribute": "LASTNAME",
"ldapAttribute": "SURNAME"
}]
}
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).
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"
}
]
}
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
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"
}
]
}
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
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"
}
}
]
}
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:
SearchUsers is called to find all users provisioned by the datasource and they are deleted (progressively to avoid impacting the service).
When all the users are deleted, the security groups bound to this datasource are deleted.
Then the datasource itself is 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’:
CopySample 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"
}
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’:
CopySample 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"
}
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"
}
]
}
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": []
}