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":"jn@centrify.com",
   "ComputerOUs":[  
      "DC=centrify,DC=lab"
   ],
   "Domains":[  
      {  
         "Name":"centrify.aws",
         "DomainId":"11111111-5254-495d-b4d4-22fc0f993899",
         "UserName":"jn@centrify.com",
         "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":"jn@centrify.com"
            },
            ...
         ],
         "ApplicationType":"WindowsService,ScheduledTask,IISApplicationPool",
         "ID":"9abcdefg-533e-4d11-a92b-15401c65bb40",
         "DefaultUserName":"jn@centrify.com",
         "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
}

Discover Resources