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 almost 5 years ago