NOTE: The Okta Identity Governance(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:

1. The user raises a request in Access Requests.
2. This generates the Access Request Created event in the Okta System Log.
3. A workflow is triggered based on that event, which does some checking of the event and goes off to get the additional data (from the Okta User Profile, in this case).
4. 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.
 

Example Request with Additional Information

Let us start by looking at an example access request flow where additional 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 is an additional section showing additional information about the employee.
 
 

Whilst this is not 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 almost anything can be done 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

This section 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 to build the integration.

New Requests API Call

The new API Call is called Create a Message for a Request. Please see Create a Message for a Request for more details.

The POST URL requires a single argument, the {requestId}. It has the following format:

/governance/api/v1/requests/{requestId}/messages

The 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, a workflow will be triggered 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 user's ID (to do a user lookup)

Depending on the scenario, some of the other fields may be of benefit. Note that it is not possible to 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:

1. Process the event – trigger off the event in the Okta system log, extract the relevant DebugDate fields, and proceed if it is one of the expected request types.
2. Go get the additional data – read the user in Okta to get the additional attributes and format it into a message.
3. Setup and run the API – get the authorization header, build the URL, format the message into an object, and call the API.

NOTE: 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. Any logic can be used here to obtain additional data for the reviewer. For example, to obtain more details from the request and perform an SoD check.
 

Part 3 – Setup and Run the API

This part of the flow will:

1. Build the Authorization header needed for the API call in a helper flow.
2. Get the Okta domain name from a workflow table via a helper flow (it could be coded into the flow).
3. Construct the API URL with the Okta domain name and requestID passed from the event.
4. Build an object with the message body built above.
5. POST the API with the URL, authorization header, and message body.

This is a fairly standard approach to calling an API.

That is it, three main pieces in the integration (API, Event, and Workflow), and no changes are 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 set up and test), but it provides the basics to build a more complex flow off of. This is a simple mechanism that could be used to great benefit.

Related References

• Okta Access Request - Create a Message for a Request

Looking for Okta Identity Governance help? Visit the Okta Identity Governance Product Hub or schedule Office Hours with the Okta Identity Governance team.