Trelica synchronizes with Okta on a daily basis, but you may want to run workflows as soon as events occur in Okta.
This example shows you how to trigger a workflow in Trelica as soon as someone is suspended in Okta.
You could for example use this to send a message in Slack to the IT operations channel to ask if the person should be offboarded immediately using Trelica.
Creating the Trelica workflow
In Trelica under Admin > Workflows, create an API webhook workflow trigger:
Ensure that Verify request is ticked.
Choose Secret for the verification method, and enter a header name, e.g. x-secret
Trelica can generate a secure secret for you - just click Generate, copy the value to the clipboard and choose Use Secret.
You will also need to provide Okta with the Trelica webhook URL.
We're going to do a test first, so click Test Webhook in Trelica and this dialog will show you the test URL that you'll need for Okta shortly.
Configuring the Okta Event Hook
In a separate tab, login in to Okta and go to Workflow > Event Hooks and click Create Event Hook:
- Give the hook a name.
- Paste in the Trelica test URL.
- Enter the header name for the secret (we chose
x-secret
as an example above). - Paste in the secret generated by Trelica for you.
- Choose User suspended for the event to subscribe to (the internal Okta name is
users.lifecycle.suspended
. - Click Save & Continue.
Okta will now prompt you to verify the URL. Trelica knows about this process, so you can just go ahead and click Verify.
Testing the Event Hook
Okta will now help you with the testing by letting you pick a recent event from your logs.
If the testing page isn't shown, you can get to it from the Event Hook list:
Assuming you've suspended a user recently, you can choose User suspended for the Event type and then pick one of the events to test with in the System Log Event dropdown:
If no logs are available Okta will provide some sample JSON but this won't work well for testing as the 'target' field is probably null, so you may need to edit this.
Go ahead and click Deliver Request:
You should see a message in Okta confirming successful delivery:
Over in Trelica, you will see that the data has been successfully received:
Linking the Okta Event target to a person in Trelica
The next step is to set the Trelica workflow context to the email of the user who was suspended.
- Close the Test webhook window in Trelica.
- Okta can send multiple events in a single webhook, so it is critical that you check Multiple entries in one request or events may get missed (without this Trelica would take the first match in an array).
- Enter
data.events
as as the JSON path to array value. This matches the events array in the Okta data structure. - Set the Context to Person and the Type to Email.
- For the JSON path, enter
target.alternateId
This is the path to the email in the Okta data that gets sent.
- Click Save Draft (or Update if the workflow is already enabled) to save your Trelica workflow after this change.
- Click Test webhook in Trelica again.
- Back in Okta, click Deliver Request to re-post the data.
- You should now see that Trelica has linked this back to a Trelica person entity:
Adding other attributes to the Trelica workflow
You might want to bring across the 'actor' who initiated the event in Okta. To do this we can define input fields, and then link these to data from Okta.
Click the Add field dropdown and choose Add new field...
Enter a Name for the field.
An ID is automatically generated but replace this with a JSON path, e.g. actor.displayName
You could use this new field in a Slack message to the suspended person's line manager:
You could also add actor.alternateId
and map to an email Input field. Then add a Field condition step to the workflow to check whether the action was initiated by a human or by an Okta system process (e.g. a synchronization from an HR system):
Enabling the workflow
Now we're happy with our testing, we need to get Okta to use the 'normal' Trelica webhook URL.
Copy the URL from Trelica:
Edit the Okta webhook:
Paste in the new URL:
Click Save & Continue and click Verify again.
Okta will now post to trigger the Trelica workflow.
Don't forget to enable the workflow in Trelica or posts from Okta won't be accepted.
If the workflow isn't enabled, Okta will get an HTTP 404 response from Trelica, e.g.
Hook "Trelica" execution failed. Remote server responded with client error,
responseCode=404 message=Not Found
Events triggered from Okta will now run the workflow.
When you view the workflow runs in Trelica you will see details of the fields carried over, and the actual JSON that was posted.
Comments
0 comments
Please sign in to leave a comment.