Discover Resources
Centrify Infrastructure Services provides the ability to discover resources, such as remote systems that can be accessed through the tenant.
This page describes the API workflow for discovering resources.
Before continuing, ensure you are familiar with:
The remainder of this document assumes that you have already authenticated the user and have obtained the authentication token necessary to invoke subsequent endpoints.
Step 1. Get the OU Tree Contents
The first step is to obtain the various domains by invoking the /Core/GetOUTreeContents endpoint:
POST /Core/GetOUTreeContents
The response contains information about each domain including the unique ID for each:
{
"success":true,
"Result":[
{
"directoryServiceUuid":"aaaaaaaa-178e-8b32-4ac7-1fa03001a9b7",
"DistinguishedName":"DC=centrify,DC=aws",
"Name":"centrify.aws",
"Uuid":"11111111-5254-495d-b4d4-22fc0f993899"
},
{
"directoryServiceUuid":"bbbbbbb-0aee-408b-a3dc-bb739ca2e83e",
"DistinguishedName":"DC=centrify,DC=lab",
"Name":"centrify.lab",
"Uuid":"22222222-9621-4663-bd44-5f14f72dc1a6"
},
{
"directoryServiceUuid":"ccccccc-4fd5-e3b1-1a60-a9e04d17276b",
"DistinguishedName":"DC=external,DC=lab",
"Name":"external.lab",
"Uuid":"33333333-7ceb-4700-8a4a-57dfb24e252c"
},
{
"directoryServiceUuid":"dddddddd-0aee-408b-a3dc-bb739ca2e83e",
"DistinguishedName":"DC=resource,DC=centrify,DC=lab",
"Name":"resource.centrify.lab",
"Uuid":"44444444-dc98-43d5-959c-e76eacd19a5e"
}
],
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
Step 2. Create a Discovery Profile
Using one of the Uuid values for the domains returned in the previous response, invoke the /ServerManage/CreateDiscoveryProfile endpoint passing that ID via the DomainId field:
POST /ServerManage/CreateDiscoveryProfile
{
"Name":"Discover new things",
"Description":"A profile to discover new things",
"DefaultUserName":"[email protected]",
"ComputerOUs":[
"DC=centrify,DC=lab"
],
"Domains":[
{
"Name":"centrify.aws",
"DomainId":"11111111-5254-495d-b4d4-22fc0f993899",
"UserName":"[email protected]",
"NamingContext":"DC=centrify,DC=aws",
"Enabled":false,
"UsingDefaultAccount":true
},
...
],
"OSType":"Windows,UnixWithCDC",
"ComputerType":"Server,Workstation",
"SkipDiscovered":true,
"ComputerGroups":null,
"ApplicationType":"WindowsService,ScheduledTask,IISApplicationPool",
"BypassAddAccountCheck":false
}
The success field in the response indicates if the request was successful, and the Result field contains the ID of the newly created profile:
{
"success":true,
"Result":"9abcdefg-533e-4d11-a92b-15401c65bb40",
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
Step 3. Check the Status
Check the discovery status by invoking the /ServerManage/GetDiscoveryStatus endpoint:
POST /ServerManage/GetDiscoveryStatus
The response contains information about the current discovery status:
{
"success":true,
"Result":{
"FullReportFilePath":"/Traces/scheduler/CpsDiscovery/f7212345-b03c-8977-1500-0a24f0f4e15d/Report.zip",
"ComputersScanned":0,
"DomainAccountsAdded":0,
"SubmittedAt":"\/Date(1518631380000)\/",
"Details":"Preparing discovery job. Please wait.\r\ndiscovery started (asdfasdf)\r\nprocessing profile asdfasdf... [completed]\r\ndiscovering computers from domain centrify.com... [completed]\r\nimported computer csssup-dc.centrify.com\r\nscanning csssup-dc.centrify.lab... [failed]\r\n",
"TotalComputersCount":1,
"JobId":"f7212345-b03c-8977-1500-0a24f0f4e15d",
"ApplicationsAdded":0,
"Percent":100,
"IsRunning":false,
"StartedAt":"\/Date(1518631458422)\/",
"LocalAccountsAdded":0,
"ComputersAdded":0,
"FinishedAt":"\/Date(1518631462735)\/",
"ScanningComputerIndex":1,
"JobStatus":"Succeeded",
"DomainsAdded":0,
"ComputersSkipped":1,
"Profiles":[
"asdfasdf"
]
},
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
Step 4. Get the Profiles
Get the discovery profiles by invoking the /ServerManage/GetDiscoveryProfiles endpoint:
POST /ServerManage/GetDiscoveryProfiles
The response contains information about each profile including the _RowKey field which identifies the newly created profile:
{
"success":true,
"Result":[
{
"Description":"A profile to discover new things",
"ScheduleOwnerId":null,
"_RowKey":"9abcdefg-533e-4d11-a92b-15401c65bb40",
"SkipDiscovered":true,
"OSType":"Windows,UnixWithCDC",
"IsSchedulable":false,
"ComputerOUs":[
"DC=centrify,DC=lab"
],
"Name":"Discover new things",
"Domains":[
{
"NamingContext":"DC=centrify,DC=aws",
"Enabled":false,
"Name":"centrify.aws",
"DomainId":"11111111-5254-495d-b4d4-22fc0f993899",
"UsingDefaultAccount":true,
"UserName":"[email protected]"
},
...
],
"ApplicationType":"WindowsService,ScheduledTask,IISApplicationPool",
"ID":"9abcdefg-533e-4d11-a92b-15401c65bb40",
"DefaultUserName":"[email protected]",
"Schedule":null,
"IsScheduleRunning":false,
"ComputerType":"Server,Workstation"
},
...
],
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
Step 5. Run the Discovery Job.
Invoke the /ServerManage/RunDiscovery endpoint to start a discovery job and pass the _RowKey from the previous response via the ID field, and the domain name and password via the Passwords object:
POST /ServerManage/RunDiscovery
{
"Profiles":[
{
"ID":"9abcdefg-533e-4d11-a92b-15401c65bb40",
"Passwords":[
{
"Domain":"centrify.com",
"Password":"MyPassword"
}
]
}
],
"BypassAddAccountCheck":false
}
The success field in the response indicates that the request was successful:
{
"success":true,
"Result":null,
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
Step 6. Check the Status of the Discovery Job
Repeatedly invoke the /ServerManage/GetDiscoveryStatus endpoint until the IsRunning field in the response is false:
POST /ServerManage/GetDiscoveryStatus
The following example shows a response where IsRunning is true, indicating that the discovery job is still in progress:
{
"success":true,
"Result":{
"FullReportFilePath":null,
"ComputersScanned":0,
"DomainAccountsAdded":0,
"SubmittedAt":"\/Date(1518631718721)\/",
"Details":"",
"TotalComputersCount":0,
"JobId":"f7266666-0849-c496-1500-06305426e25d",
"ApplicationsAdded":0,
"Percent":0,
"IsRunning":true,
"LocalAccountsAdded":0,
"ComputersAdded":0,
"ScanningComputerIndex":0,
"JobStatus":"Created",
"DomainsAdded":0,
"ComputersSkipped":0,
"Profiles":[
]
},
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
The following example shows a response where IsRunning is false, indicating that the discovery job is complete. Various other fields in the response contain information about the elements discovered by the job:
{
"success":true,
"Result":{
"FullReportFilePath":"/Traces/scheduler/CpsDiscovery/f7299999-0849-c496-1500-06305426e25d/Report.zip",
"ComputersScanned":0,
"DomainAccountsAdded":0,
"SubmittedAt":"\/Date(1518631680000)\/",
"Details":"Preparing discovery job. Please wait.\r\ndiscovery started (Discover new things)\r\nprocessing profile Discover new things... [completed]\r\ndiscovering computers from domain centrify.lab... [completed]\r\nimported computer csssup-dc.centrify.lab\r\nscanning csssup-dc.centrify.lab... [failed]\r\n",
"TotalComputersCount":1,
"JobId":"f7299999-0849-c496-1500-06305426e25d",
"ApplicationsAdded":0,
"Percent":100,
"IsRunning":false,
"StartedAt":"\/Date(1518631758433)\/",
"LocalAccountsAdded":0,
"ComputersAdded":0,
"FinishedAt":"\/Date(1518631763605)\/",
"ScanningComputerIndex":1,
"JobStatus":"Running",
"DomainsAdded":0,
"ComputersSkipped":1,
"Profiles":[
"Discover new things"
]
},
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
Try the API in Postman:
.
Click here for help with using our sample Postman collection.
Updated about 5 years ago