This article looks at a recent addition to the Okta Identity Governance (OIG) Access Request API that allows updating of in-flight access requests and can be used to add additional data to help reviewers review requests.
Note that the OIG APIs are still in beta but can be used against preview and production Okta orgs.
Overview of the Integration
This integration is based around a new OIG Requests API call (details below) that adds a new message to an existing Request in OIG Access Requests. This call could be made from any bit of code, Okta Workflows or any API execution environment (like Postman).
For this scenario it made sense to use an Okta workflow triggered off the Access Request Created event in the System Log as the event is generated as soon as the request is raised (and likely before a reviewer goes into review the request) and the event contains the Request ID which is needed by the API call.
The flow is shown below:
The flow is:
- The user raises a request in Access Requests
- This generates the Access Request Created event in the Okta System Log
- A workflow is triggered based off that event that does some checking of the event, goes off to get the additional data (from the Okta User Profile in this case)
- It then formats that data into a message and uses the new API to update that Request with the message
The next section will show the results of this and then we’ll dig into the mechanics of the integration.
An Example Request With Additional Information
Let’s start by looking at an example access request flow where addiitonal information is provided. A user raises an access request (in this case via the WebUI but it could be via Slack/Teams).
As always they are taken to the request messages view. But notice that there’s an additional section showing additional information about the employee.
Whilst this isn’t very useful to the requester, it is useful to the manager who needs to approve the request.
This information has been gathered by an Okta Workflow and put into the request to help the manager make the decision on whether to approve the access request or not.
This is a trivial example to show the mechanism, but you could do almost anything in Workflows such as checking whether this request breaks a Separation of Duties policy (and then letting the manager decide whether to allow the access or not).
The Mechanics of the Integration
In this section we will explore the building blocks of the integration shown above. The most important part is the new API call, but the others are included to show how you could build the integration yourself.
New Requests API Call
The new API Call is called Create a Message for a Request and it’s documented here: https://developer.okta.com/docs/api/iga/openapi/governance.api/tag/Requests/#tag/Requests/operation/createRequestMessage.
The POST URL requires a single argument, the {requestId}. It has the following format:
/governance/api/v1/requests/{requestId}/messagesThe request body contains a single object with a message value:
{
"message": "Contact admin@atko.com for any additional assistance needed with this request."
}The workflow below implements this based on the requestId being passed in the event.
Access Request Created Event in Okta System Log
For this integration we are triggering a workflow off the access.request.create event that is generated every time a new access is requested in Okta Access Requests. All events in the System Log have the same overall structure. The details needed are stored in the DebugData section of the event.
The key fields we use in this integration are:
- AccessRequestId – the id of the request instance that is used in the API URL
- AccessRequestSubject – the name of the Request Type used
- RequesterId – the Okta users ID (so we can do a user lookup)
Depending on your scenario, some of the other fields may be of benefit. Note that you can’t add additional fields to this, the set of fields is fixed.
Workflow to Get Additional Data
A single workflow was built to implement the needed functionality. It had the following flow:
- Process the event – trigger off the event in the Okta system log, extract the relevant DebugDate fields and proceed if it’s one of the expected request types
- Go get the additional data – read the user in Okta to get the additional attributes and format into a message
- Setup and run the API – get the authorization header, build the URL, format the message into an object and call the API.
Note that as the APIs are beta and not built into the Okta connector yet, the call uses the generic API card which requires the authorization header to be set up.
The following sections show the flow in more detail.
Part 1 – Process the Event
The trigger for the flow is the Access Request Created event on the Okta connector. It will get all of the event details, including the Debug Data object (the card will strip this object out).
It then strips out the three fields we need, and checks to see if the Request Type is one we want to process (and stops if not).
Part 2 – Go Get the Additional Data
Using the Okta User ID (the RequesterId from the event), an Okta Read User card is used to get some attributes from the user profile.
These attributes are formatted into a message using a Text Compose card. Note that the carriage returns (“/n”) in the Compose card carry to the final message in Access Requests (see the results above are split across five lines).
This is the flexible part of the flow. You could put any logic in here to go get additional data for the reviewer. For example, you could implement logic to get more details from the request and perform a SoD check.
Part 3 – Setup and Run the API
This part of the flow will:
- Build the Authorization header needed for the API call in a helper flow
- Get the Okta domain name from a workflow table via a helper flow (it could be coded into the flow)
- Construct the API URL with the Okta domain name and requestID passed from the event
- Build an object with the message body built above, and
- POST the API with the URL, authorization header and message body.
This is a fairly standard approach to calling an API.
That’s it, three main pieces in the integration (API, Event and Workflow) and no changes required in Access Requests.
Conclusion
This article has shown how the new Requests API call to put a message on a request can be used to provide additional information to the reviewer in the request messages. The example used here was to trigger a workflow off the Access Request Create event in the Okta System Log, collect some additional information about the requester from their Okta User Profile and put this back into the request. The example is almost trivial (it took me less than an hour to setup and test), but provides the basics to build more complex flow off of. This is a simple mechanism that could be used to great benefit.
2 thoughts on “OIG Access Requests – Posting Additional Information into a Request”