External User Management API
This feature is only available in Incredibuild's Enterprise Plan.
You can create new users with our External User Management API. This requires an API Key and an Enterprise license.
Request Endpoint
POST https://{IB Coordinator IP Address/Hostname}:{Web Access Port}/api/autheticationSystem?version=1.5.0
For example:
https://coordinatorPC:8000/api/autheticationSystem?version=1.5.0
The APi request must include a key called client-api-key and the value of your API key as a string. All APIs are case sensitive.
Request Format – Setting or Updating Active Directory
Send a PUT request, with a JSON document in the following structure, as part of the request body, similar to the following:
{
"externalSystem": "LDAP", "configuration" : {
"protocol": "LDAPS",
"url": "ldaps://domain-controller-ip:636",
"rootCertificate" : "BLAH",
"bindDN": "CN=IBAdminUser,CN=Users,DC=example,DC=local",
"bindPassword": "HasambaHasambaHasamba",
"groupDN": "DC=example,DC=local",
"userDN": "CN=Users,DC=example,DC=local",
"userIdAttribute": "uid",
"groupRoles": [
{"group" : "Administrators",
"role" : " GridAdmin "} ]
}
}| Field | Description | Required |
|---|---|---|
| externalSystem |
The type of system to use Always LDAP |
yes |
| protocol |
The LDAP protocol Either LDAP or LDAPS |
yes |
| url |
The URL of the Domain Controller ldaps://domain-controller-ip:port or ldap://domain-controller-ip:port |
yes |
| bindDN |
The DN for the user to use when connecting to LDAP e.g. CN=IBAdminUser,CN=Users,DC=example,DC=local |
yes |
| bindPassword | The password for the user references in bindDN | yes |
|
groupDN |
The DN for the folder where groups are defined e.g. DC=example,DC=local |
yes |
|
userDN |
The DN for the folder where users are define e.g. CN=Users,DC=example,DC=local |
yes |
|
rootCertificate |
The certificate for the LDAPS connection The root certificate in PEM format, with \n for new-lines, e.g. Copy
|
Yes, if the protocol is LDAPS |
|
userIdAttribute |
The attribute where the user’s UID is stored, by default uid e.g. uid |
no |
|
group |
The name of a group, whose users are given a role in Incredibuild e.g. Administrators |
no
|
|
role |
The role assign to users of the above group Either GridAdmin, GroupManager, or Viewer |
no |
Note:
-
Once set, the protocol, url and bindDN cannot be modified. Instead, disconnect from the external user management system and set it up again.
Request Format – Setting or Updating Entra ID (Azure Active Directory)
Send a PUT request, with a JSON document in the following structure, as part of the request body, similar to the following:
{ "externalSystem" : "AZUREAD",
"configuration": {
"tenantId": "1234",
"azureAdApplicationid": "5678",
"clientSecret": "BLAH"},
"groupRoles": [
{"group": "Administrators",
"role" : " GridAdmin "}
]
}
}| Field | Description | Required |
|---|---|---|
| externalSystem |
The type of system to use Always AZUREAD |
yes |
| tenantId |
The tenant ID from Azure |
yes |
| azureAdApplicationid |
The applicationID from Azure |
yes |
| clientSecret |
The name of a group, whose users are given a role in Incredibuild e.g. Administrators |
yes |
|
role |
The role assign to users of the above group Either GridAdmin, GroupManager, or Viewer |
yes |
Request Format – Disconnect from External User Management System
Send a PUT request, with a JSON document in the following structure, as part of the request body, similar to the following:
{ "externalSystem": "NONE" }
Request Format – Show Current External User Management System
Send a GET request, with no body. The response is in the format above, depending on the current system configured.
Note:
-
Passwords and secrets will not appear in a GET response.