Request a Zone Role
Centrify's hierarchical zoning mechanism, tied to Active Directory, can grant cross platform roles (i.e. roles that can contain privileges for different platforms).
This page describes the API workflow for programmatically requesting a zone role.
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 Queries
The first step is to get the queries for finding server objects. Invoke the /Collection/GetObjectCollectionsAndFilters endpoint and set the ObjectType parameter to Server:
POST /Collection/GetObjectCollectionsAndFilters
{
"ObjectType":"Server",
"Args":{
"PageNumber":1,
"PageSize":100000,
"Limit":100000,
"SortBy":"",
"direction":"False",
"Caching":-1
}
}
The Results field of the response contains the queries for various types of systems:
{
"success":true,
"Result":{
"IsAggregate":false,
"Count":11,
"Columns":[
{
"Name":"ID",
"IsHidden":false,
"DDName":null,
"Title":"ID",
"DDTitle":null,
"Description":null,
"Type":12,
"Format":null,
"Width":25,
"TableKey":null,
"ForeignKey":null,
"TableName":null
},
...
],
"FullCount":11,
"Results":[
{
"Entities":[
{
"Type":"Collection",
"Key":"@Unix Servers",
"IsForeignKey":false
}
],
"Row":{
"Rank":20,
"CollectionType":"SqlDynamic",
"Filters":"SELECT * FROM (Select Server.ID, Server.AgentVersion, Server.ComputerClass, Server.Description, Server.FQDN, Server.LastState, Server.HealthStatus, Server.IsFavorite, Server.IPAddress, Server.Joined, Server.OperatingSystem, Server.Name, Server.UserID, Server.SessionType, Server.Port, Server.ProxyUser, Server.AllowRemote, Server.DefaultCheckoutTime, Server.AllowMultipleCheckouts, Server.ProxyUserIsManaged, Server.ManagementMode, Server.ManagementPort, Server.JoinedBy, Server.PasswordProfileID, Server.JoinedDate, Server.AllowHealthCheck, Server.HealthCheckInterval, Server.AllowPasswordRotation, Server.MinimumPasswordAge, Server.PasswordRotateDuration, Server.AllowPasswordHistoryCleanUp, Server.PasswordHistoryCleanUpDuration, Server.ProxyCollectionList, Server.TimeZoneID,Server.LmiEnabled, Server.DiscoveredTime as ServerDiscoveredTime from Server ORDER BY Name COLLATE NOCASE) WHERE ComputerClass = \"Unix\"",
"Name":"Unix Systems",
"Description":"Unix Systems",
"ID":"@Unix Servers",
"ObjectType":"Server",
"Builtin":true
}
},
{
"Entities":[
{
"Type":"Collection",
"Key":"@Windows Servers",
"IsForeignKey":false
}
],
"Row":{
"Rank":20,
"CollectionType":"SqlDynamic",
"Filters":"SELECT * FROM (Select Server.ID, Server.AgentVersion, Server.ComputerClass, Server.Description, Server.FQDN, Server.LastState, Server.HealthStatus, Server.IsFavorite, Server.IPAddress, Server.Joined, Server.OperatingSystem, Server.Name, Server.UserID, Server.SessionType, Server.Port, Server.ProxyUser, Server.AllowRemote, Server.DefaultCheckoutTime, Server.AllowMultipleCheckouts, Server.ProxyUserIsManaged, Server.ManagementMode, Server.ManagementPort, Server.JoinedBy, Server.PasswordProfileID, Server.JoinedDate, Server.AllowHealthCheck, Server.HealthCheckInterval, Server.AllowPasswordRotation, Server.MinimumPasswordAge, Server.PasswordRotateDuration, Server.AllowPasswordHistoryCleanUp, Server.PasswordHistoryCleanUpDuration, Server.ProxyCollectionList, Server.TimeZoneID,Server.LmiEnabled, Server.DiscoveredTime as ServerDiscoveredTime from Server ORDER BY Name COLLATE NOCASE) WHERE ComputerClass = \"Windows\"",
"Name":"Windows Systems",
"Description":"Windows Systems",
"ID":"@Windows Servers",
"ObjectType":"Server",
"Builtin":true
}
}
...
],
"ReturnID":""
},
...
}
Step 2. Use a Query to Get all Servers
Choose a query from the previous response, invoke the /RedRock/query endpoint, and pass the query via the Script parameter:
POST /RedRock/query
{
"Script":"SELECT * FROM (Select Server.ID, Server.AgentVersion, Server.ComputerClass, Server.Description, Server.FQDN, Server.LastState, Server.HealthStatus, Server.IsFavorite, Server.IPAddress, Server.Joined, Server.OperatingSystem, Server.Name, Server.UserID, Server.SessionType, Server.Port, Server.ProxyUser, Server.AllowRemote, Server.DefaultCheckoutTime, Server.AllowMultipleCheckouts, Server.ProxyUserIsManaged, Server.ManagementMode, Server.ManagementPort, Server.JoinedBy, Server.PasswordProfileID, Server.JoinedDate, Server.AllowHealthCheck, Server.HealthCheckInterval, Server.AllowPasswordRotation, Server.MinimumPasswordAge, Server.PasswordRotateDuration, Server.AllowPasswordHistoryCleanUp, Server.PasswordHistoryCleanUpDuration, Server.ProxyCollectionList, Server.TimeZoneID,Server.LmiEnabled, Server.DiscoveredTime as ServerDiscoveredTime from Server ORDER BY Name COLLATE NOCASE)",
"Args":{
"PageNumber":1,
"PageSize":100,
"Limit":100000,
"SortBy":"",
"direction":"False",
"Caching":-1
}
}
The Results field in the response contains information for each system found by the query:
{
"success":true,
"Result":{
"IsAggregate":false,
"Count":13,
"Columns":[
{
"Name":"ID",
"IsHidden":false,
"DDName":"_ID",
"Title":"ID",
"DDTitle":"ID",
"Description":"Row Identifier (primary key)",
"Type":12,
"Format":null,
"Width":0,
"TableKey":"Primary",
"ForeignKey":null,
"TableName":"Server"
},
...
],
"FullCount":13,
"Results":[
{
"Entities":[
{
"Type":"Server",
"Key":"be123456-4d31-4052-97cb-47456d7347f0",
"IsForeignKey":false
}
],
"Row":{
"ID":"be123456-4d31-4052-97cb-47456d7347f0",
"AllowMultipleCheckouts":null,
"DefaultCheckoutTime":null,
"JoinedBy":null,
"MinimumPasswordAge":null,
"LmiEnabled":null,
"ProxyUser":"",
"UserID":null,
"PasswordHistoryCleanUpDuration":null,
"ManagementMode":null,
"AllowHealthCheck":null,
"JoinedDate":null,
"Joined":null,
"LastState":"OK",
"SessionType":"Ssh",
"PasswordProfileID":null,
"ProxyUserIsManaged":null,
"IPAddress":"172.27.9.224",
"PasswordRotateDuration":null,
"ManagementPort":null,
"AgentVersion":null,
"Description":"",
"ProxyCollectionList":null,
"FQDN":"csssup-suse11.centrify.com",
"Name":"csssup-suse11",
"AllowRemote":null,
"HealthCheckInterval":null,
"ComputerClass":"Unix",
"ServerDiscoveredTime":"\/Date(1516060926011)\/",
"OperatingSystem":"SUSE Linux",
"AllowPasswordHistoryCleanUp":null,
"Port":null,
"HealthStatus":"OK",
"AllowPasswordRotation":null,
"IsFavorite":false,
"TimeZoneID":null
}
},
...
],
"ReturnID":""
},
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
Step 3. Run a Query to get Information for a Specific Server
Identify the server for which a zone role is to be requested, and invoke the RedRock/Query endpoint passing in the system ID as part of the Script query parameter:
POST /RedRock/query
{
"Script":"select * from Server where ID = 'be123456-4d31-4052-97cb-47456d7347f0'",
"Args":{
"PageNumber":1,
"PageSize":100000,
"Limit":100000,
"SortBy":"",
"direction":"False",
"Caching":-1
}
}
The response contains information about that particular system:
{
"success":true,
"Result":{
"IsAggregate":false,
"Count":1,
"Columns":[
{
"Name":"LastState",
"IsHidden":false,
"DDName":"LastState",
"Title":"LastState",
"DDTitle":"LastState",
"Description":null,
"Type":12,
"Format":null,
"Width":0,
"TableKey":"NotAKey",
"ForeignKey":null,
"TableName":"Server"
},
...
],
"FullCount":1,
"Results":[
{
"Entities":[
{
"Type":"Server",
"Key":"be123456-4d31-4052-97cb-47456d7347f0",
"IsForeignKey":false
}
],
"Row":{
"AgentVersion":null,
"NumBrokenAccounts":3,
"ProxyUserIsManaged":null,
"LmiEnabled":null,
"UseDomainWorkflowApprovers":true,
"JoinedDate":null,
"AgentFeatures":null,
"ManagementMode":null,
"Name":"csssup-suse11",
"HealthCheckInterval":null,
"IsFavorite":false,
"ProxyCollectionList":null,
"UseDomainWorkflowRoles":true,
"AdministrativeAccountID":null,
"DefaultHome":null,
"AllowRemote":null,
"PasswordHistoryCleanUpDuration":null,
"ID":"be6c9890-4d31-4052-97cb-47456d7347f0",
"MinimumPasswordAge":null,
"ServiceAccountID":null,
"OperatingSystem":"SUSE Linux",
"JoinedBy":null,
"DomainName":"resource.centrify.lab",
"ZoneRoleWorkflowRoles":"[{\"Description\":\"Predefined system role for multi-factor authentication of users during login. Users must be enrolled in the Centrify Identity Platform.\",\"ParentZoneDn\":\"CN=Global,CN=Zones,OU=Centrify,DC=resource,DC=centrify,DC=lab\",\"ZoneDn\":\"CN=Solaris,CN=Global,CN=Zones,OU=Centrify,DC=resource,DC=centrify,DC=lab\",\"Windows\":true,\"ZoneCanonicalName\":\...",
"Description":"",
"ZoneStatus":"Joined",
"ActiveSessions":1,
"HealthStatus":"OK",
"IPAddress":"172.27.9.224",
"PasswordProfileID":null,
"ActiveCheckouts":0,
"UniqueId":"be41b6c5-d515-4853-9970-4726f6c39ba0",
"ShowCpsOnMobile":null,
"ComputerClass":"Unix",
"FQDN":"csssup-suse11.resource.centrify.lab",
"UserID":null,
"DomainId":"4d9a79c7-401b-4684-bdc1-90c443150142",
"Rights":"ManageSession, Edit, Delete, Grant, AgentAuth, RequestZoneRole, View",
"DefaultCheckoutTime":null,
"ZoneRoleWorkflowApprovers":"[{\"Type-generated-field...",
"AllowPasswordRotation":null,
"ReachableError":null,
"NumGoodAccounts":1,
"ZoneJoined":null,
"AllowPasswordHistoryCleanUp":null,
"AllowHealthCheck":null,
"TimeZoneID":null,
"Joined":null,
"LastState":"OK",
"PasswordRotateDuration":null,
"ProxyUserKmipId":null,
"DiscoveredTime":"\/Date(1516060926011)\/",
"HealthStatusError":null,
"ManagementPort":null,
"CredentialKmipMode":null,
"ProxyUser":"",
"SessionType":"Ssh",
"Reachable":true,
"DomainOperationsEnabled":true,
"ZoneRoleWorkflowApproversList":"[{\"Type-generated-field\":...",
"AllowMultipleCheckouts":null,
"Accounts":null,
"DefaultShell":null,
"ZoneRoleWorkflowEnabled":true,
"_MatchFilter":null,
"Port":null
}
}
],
"ReturnID":""
},
...
}
Step 4. Get the Effective Row Rights
Get the effective row rights for the system by invoking the /Acl/GetEffectiveRowRights endpoint and passing the ID via the RowKey parameter:
POST /Acl/GetEffectiveRowRights
{
"Rows":[
{
"Table":"Server",
"RowKey":"be123456-4d31-4052-97cb-47456d7347f0",
"ReduceSysadmin":true
}
]
}
The response contains the GrantStr value:
{
"success":true,
"Result":[
{
"GrantStr":"0000000000000000000000000000000000000000000000110000000011111111",
"RowKey":"be123456-4d31-4052-97cb-47456d7347f0",
"Table":"Server"
}
],
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
Step 5. Get the Zone Role Workflow
Invoke the /ZoneRoleWorkflow/GetRoles endpoint passing the system ID via the ResourceID field:
POST /ZoneRoleWorkflow/GetRoles
{
"ResourceId":"be123456-4d31-4052-97cb-47456d7347f0",
"Args":{
"PageNumber":1,
"PageSize":100000,
"Limit":100000,
"SortBy":"",
"direction":"False",
"Caching":-1
}
}
The Roles field in the response provides information about the roles available on that system:
{
"success":true,
"Result":{
"Roles":[
{
"Name":"AAAA - Unix Admin/AIX",
"ZoneCanonicalName":"centrify.com/Centrify/Zones/Global/AIX",
"Description":"Role ofr root equivalent. Custom Role by Bob. Unix Admin",
"ParentZoneDn":"CN=Global,CN=Zones,OU=Centrify,DC=resource,DC=centrify,DC=lab",
"Unix":true,
"ZoneDn":"CN=AIX,CN=Global,CN=Zones,OU=Centrify,DC=resource,DC=centrify,DC=lab"
},
...
]
},
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
Step 6. Start the Job
Using the role information returned from the previous response, invoke the /jobflow/startjob endpoint, passing the system ID via the ResourceId parameter and the role information via the RoleZoneDn parameter:
POST /jobflow/startjob
{
"script":"/lib/jobs/cps_assign_computer_role.js",
"args":{
"ScopeType":"Computer",
"ResourceId":"be123456-4d31-4052-97cb-47456d7347f0",
"RoleName":"AAAA - Unix Admin/AIX",
"RoleDescription":"Role ofr root equivalent. Custom Role by Bob. Unix Admin",
"RoleZoneDn":"CN=AIX,CN=Global,CN=Zones,OU=Centrify,DC=resource,DC=centrify,DC=lab",
"RoleZoneCanonicalName":"centrify.com/Centrify/Zones/Global/AIX",
"RequestedOptions":{
"AssignmentType":"temp",
"StartGrantValue":60,
"StartTimeInterval":1,
"EndGrantValue":60,
"EndTimeInterval":1
},
"Reason":null
}
}
The Result field of the response contains the ID of the job:
{
"success":true,
"Result":"62abb05e-b589-4d7e-b837-8d1e7c117c59",
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
Once the request for the zone role has been approved by an administrator, the user will then have access to the privileges associated with the role on the system.
Try the API in Postman:
.
Click here for help with using our sample Postman collection.
Updated over 4 years ago