Request and Approve Privileged Access
Users can request access to resources, such as login accounts for systems, while other users (e.g. admins) can approve or deny such requests.
This document describes the API workflow for requests and approvals using an example use case where one user requests access to a system's login account and another user approves the access.
Making a Request for Privileged Access
Before continuing, ensure you are familiar with:
Getting the list of Resources to Request Access for
The first step is to request the list of resources so that you can select one of them to request access for. The following example invokes the /ServerManage/GetAccountsForLogin endpoint to get all of the login accounts available for a system with host ID `abcabcab-1234-4052-97cb-47456d7347f0':
POST /ServerManage/GetAccountsForLogin
{
"domainOnly":"false",
"filter":"",
"host":"abcabcab-1234-4052-97cb-47456d7347f0",
"Args":{
"PageNumber":1,
"PageSize":100000,
"Limit":100000,
"SortBy":"",
"direction":"False",
"Caching":-1
}
}
The response contains the list of login accounts for that system:
{
"success":true,
"Result":[
{
"accountId":"98765432-1118-4326-815a-d33abd18da26",
"name":"jtest",
"authority":"csssup-suse11",
"authorityType":"Local",
"requestRequired":true
},
{
"accountId":"12345678-984c-492b-a7c7-e91132d13a5d",
"name":"root",
"authority":"csssup-suse11",
"authorityType":"Local",
"requestRequired":true
}
],
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
Sending the Access Request
The next step is to send a request for approval by invoking the /JobFlow/StartJob endpoint. Some of the key body parameters to include are:
- script: the name of the script that executes the request logic.
- PVID: specifies the ID of the resource for which approval is being requested.
Note: the required body parameters vary depending on the type of resource for which a request is being made.
The following example sends a request for access to the first account returned in the previous call:
POST /JobFlow/StartJob
{
"script":"/lib/jobs/server_account_access.js",
"args":{
"PVID":"98765432-1118-4326-815a-d33abd18da26",
"Reason":null,
"AccessType":"Login",
"RequestedOptions":{
"AssignmentType":"window",
"StartTime":"Fri, 02 Feb 2018 20:11:00 GMT",
"EndTime":"Fri, 02 Feb 2018 21:11:00 GMT"
}
}
}
The success field in the response indicates if a job was successfully created, and the results field indicates the job's unique ID.
{
"success":true,
"Result":"aaaabbcc-efgh-4c15-8dbd-e337e1db7d98",
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
You can then poll for the results of that job by repeatedly invoking the /JobFlow/GetJob endpoint and passing the job's unique ID via jobid:
POST /JobFlow/GetJob
{
"jobid" : "aaaabbcc-efgh-4c15-8dbd-e337e1db7d98"
}
The response contains resource-specific job results in the Result field:
{
"success":true,
"Result":{
... <- resource specific results will appear here
},
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
Approving the Request
A user with the right privileges (e.g. an admin) can approve the request.
Getting a list of Requests
Since a request is created as a job, the first step is to get a list of all jobs. Invoke the /jobflow/getmyjobs endpoint and set type to all in the body:
POST /jobflow/getmyjobs
{
"type":"all",
"Args":{
"PageNumber":1,
"PageSize":100000,
"Limit":100000,
"SortBy":"",
"direction":"False",
"Caching":-1
}
}
The Result.Results field in the response lists all jobs currently assigned:
{
"success":true,
"Result":{
"IsAggregate":false,
"Count":4,
"Columns":[
{
"Name":"TargetPrincipalType",
"IsHidden":false,
"DDName":null,
"Title":"TargetPrincipalType",
"DDTitle":null,
"Description":null,
"Type":12,
"Format":null,
"Width":4,
"TableKey":null,
"ForeignKey":null,
"TableName":null
},
...
],
"FullCount":4,
"Results":[
{
"Entities":[
{
"Type":"WorkFlowJob",
"Key":"aaaabbcc-efgh-4c15-8dbd-e337e1db7d98",
"IsForeignKey":false
}
],
"Row":{
"TargetPrincipalType":"User",
"_entitycontext":"*",
"MobileNotificationData":"{\"NotificationIds\":{}}",
"_metadata":{
"Version":1,
"IndexingVersion":1
},
"ACL":"true",
"InitiatorID":"98798778-cbef-48d0-9296-9c16247bf320",
"_PartitionKey":"AAU0350",
"_Timestamp":"\/Date(1517602281361)\/",
"StepNum":1,
"_encryptkeyid":"AAU0350",
"ID":"aaaabbcc-efgh-4c15-8dbd-e337e1db7d98",
"StateUpdatedDate":"\/Date(1517602280989)\/",
"Description":"Login request for account jamestest on csssup-suse11",
"TargetPrincipalName":"[email protected]",
"BlessAs":"sysadmin",
"DefaultOptions":"{\"GrantMin\":60}",
"Context":{
"RequestorUserName":"[email protected]",
"Authority":"csssup-suse11",
"RequestorMail":"[email protected]",
"RequestorDisplayName":"Req",
"EventPrincipalUUID":"66554411-cbef-48d0-9296-9c16247bf320",
"EventPrincipalUserName":"[email protected]",
"AccessType":"Login",
"EventPrincipalMail":"[email protected]",
"PVID":"2bd9ae7c-1118-4326-815a-d33abd18da26",
"AccountName":"jtst",
"RequestedOptions":{
"EndTime":"Fri, 02 Feb 2018 21:11:00 GMT",
"AssignmentType":"window",
"StartTime":"Fri, 02 Feb 2018 20:11:00 GMT"
},
"HostID":"abcabcab-1234-4052-97cb-47456d7347f0",
"Bookmarks":"AccountDetails:VaultAccount:abdd9999-1111-2222-815a-d33abd18da26",
"DefaultGrantMinutes":60,
"RequestorUUID":"32112354-c998-48d0-9296-9c16247bf320"
},
"StepArgs":"{\"expires\":\"2018-02-02T21:11:00+00:00\",...,
"Initiator":"[email protected]",
"LastHistoryEntry":"([email protected])Request submitted",
"TargetPrincipalID":"88998877-0000-1111-8894-bb9f749515f4",
"CreatedDate":"\/Date(1517602275818)\/",
"TraceFile":"/Traces/Workflow/2018020220111581823113.txt",
"_TableName":"workjob",
"History":"[{\"message\":\"Request submitted\",\"from\":\"[email protected]\",\"date\":\"Fri, 02 Feb 2018 20:11:16 UTC\"}]",
"CanReadLogs":true,
"TotalStepNum":2,
"OptionsSelector":1,
"State":"Ask",
"JS":"/lib/jobs/server_account_access.js"
}
},
...
],
"ReturnID":""
},
"Message":null,
"MessageID":null,
"Exception":null,
"ErrorID":null,
"ErrorCode":null,
"InnerExceptions":null
}
Approving the Request
Once you identify the job in the response above that represents a request to approve, you can then invoke the /JobFlow/Event endpoint to perform the approval.
Set jobid to the ID of the approval job, and set event to approve. Additional, request-specific body parameters may also need to be included depending on the resource being approved.
The following example shows an approval being executed for the system login account request from above:
POST /JobFlow/Event
Formatted JSON Data
{
"jobid":"aaaabbcc-efgh-4c15-8dbd-e337e1db7d98",
"event":"approve",
"sync":true,
"args":{
"AssignmentType":"window",
"StartTime":"Fri, 02 Feb 2018 20:11:00 GMT",
"EndTime":"Fri, 02 Feb 2018 21:11:00 GMT"
}
}
The response contains request-specific information for the request.
For example, in the following response, Result.Context.PVID contains the account ID for which access was requested, Result.Context.HostID contains the system on which the account exists, etc.:
{
"success":true,
"Result":{
"TotalStepNum":2,
"WorkflowSettings":"{\"WorkflowApprover\":[{\"ServiceInstance\": ...,
"Context":{
"RequestorUserName":"[email protected]",
"Authority":"csssup-suse11",
"RequestorDisplayName":"Re",
"RequestorMail":"[email protected]",
"EventPrincipalUUID":"12332187-0f5c-4834-8894-bb9f749515f4",
"AccessType":"Login",
"EventPrincipalUserName":"[email protected]",
"PVID":"98765432-1118-4326-815a-d33abd18da26",
"EventPrincipalMail":"[email protected]",
"AccountName":"jt",
"RequestedOptions":{
"EndTime":"Fri, 02 Feb 2018 21:11:00 GMT",
"AssignmentType":"window",
"StartTime":"Fri, 02 Feb 2018 20:11:00 GMT"
},
"HostID":"abcabcab-1234-dddc-97cb-47456d7347f0",
"Bookmarks":"AccountDetails:VaultAccount:32165498-1118-4326-815a-d33abd18da26",
"DefaultGrantMinutes":60,
"RequestorUUID":"98778932-cccd-48d0-9296-9c16247bf320"
},
"InitiatorID":"7863c282-cb3f-48d0-9296-9c16247bf320",
"DefaultOptions":"{\"GrantMin\":60}",
"ErrorMessage":"approve failed: User J ([email protected]) has no email address",
"_entitycontext":"W/\"datetime'2018-02-02T20%3A12%3A12.9494403Z'\"",
"MobileNotificationData":"{\"NotificationIds\":{}}",
"JS":"/lib/jobs/server_account_access.js",
"_TableName":"workjob",
"TraceFile":"/Traces/Workflow/2018020220111581823113.txt",
"State":"Failed",
"TargetPrincipalID":"77ae972e-c1db-406e-8096-008196f6569b",
"_RowKey":"e8c76ea4-70f8-4c15-8dbd-e337e1db7d98",
"SelectedOptions":"{\"EndTime\":\"Fri, 02 Feb 2018 21:11:00 GMT\",\"AssignmentType\":\"window\",\"StartTime\":\"Fri, 02 Feb 2018 20:11:00 GMT\"}",
"_encryptkeyid":"AAU0350",
"_PartitionKey":"AAU0350",
"TargetPrincipalType":"User",
"StepArgs":"{\"expires\":\"2018-02-02T21:11:00+00:00\", ...,
"_metadata":{
"Version":1,
"IndexingVersion":1
},
"History":"[{\"message\":\"Request submitted\",\"from\":\"[email protected]\",\"date\":\"Fri, 02 Feb 2018 20:11:16 UTC\"}]",
"Description":"Login request for account jt on csssup-suse11",
"DescriptionJson":"{\"format\":\"_I18N_WorkflowRequestServerLoginAccountAccess\",\"args\":[\"jt\",\"csssup-suse11\"]}",
"OptionsSelector":1,
"BlessAs":"sysadmin",
"StateUpdatedDate":"\/Date(1517602332517)\/",
"StepNum":2,
"_Timestamp":"\/Date(1517602276282)\/",
"Initiator":"[email protected]",
"EndTime":"\/Date(1517605860000+0000)\/",
"ACL":"true",
"CreatedDate":"\/Date(1517602275818)\/",
"StartTime":"\/Date(1517602260000+0000)\/",
"TargetPrincipalName":"[email protected]"
},
"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