Okta Automation Triggers
Start an automation when Okta creates, activates, suspends, locks, or deactivates a user account, and assign the Okta role the setup needs
Okta automation triggers start an automation when an account event happens in your Okta organization. Risotto receives the events through an Okta event hook that it registers for you. You turn the events on from the Admin API card on Settings > Integrations > Okta.
How it works
- You turn on Automation triggers on the Okta connection. Risotto registers an event hook in your Okta organization, or adds the account events to the hook it already uses for Okta Identity Governance.
- Okta sends each account event to Risotto.
- Risotto starts every enabled automation whose trigger matches the event, with the event data in the run's prompt. The agent follows the automation's instructions, for example to open a ticket for the locked-out person.
Prerequisites
- An Okta connection that uses an API Services app (OAuth). A connection that uses an API token has no Automation triggers switch.
- The
okta.eventHooks.managescope granted on the Risotto API Services app. The base Okta setup does not include this scope. Okta refuses every event hook call without it. - The Super Administrator role on the Risotto API Services app while you turn the events on or off. Okta requires it to change what the event hook sends. You can remove the role as soon as the change succeeds.
Grant the scope and assign the role
Open the Risotto app in Okta
In the Okta Admin Console, go to Applications > Applications and open the API Services app you created for Risotto.
Grant the event hook scope
On the Okta API Scopes tab, grant
okta.eventHooks.manage. Keep this scope after setup. If the app already has it for Okta Identity Governance, skip this step.Add the role
On the Admin roles tab, click Edit assignments, choose Super Administrator, and click Save Changes. Okta asks you to sign in again.
Remove the role after the change
After the switch in Risotto confirms You can remove the "Super Administrator" role, remove the role again. Keep the scope. The other roles the connection needs stay as described in the Okta integration guide.
Turn on the events
Open the Okta connection
Go to Settings > Integrations and click the Okta card. Find the Admin API card.
Turn on Automation triggers
Turn on the Automation triggers switch. The Turn on Okta automation triggers dialog opens. It lists the Okta events Risotto will subscribe to and reminds you that the change needs the
okta.eventHooks.managescope and the Super Administrator role.Confirm
Click Register and turn on. When Okta accepts the change, a banner tells you that you can remove the Super Administrator role. Under the switch, the connection now lists the events it receives.
If Okta rejects the change, the dialog says Okta refused the request and nothing changes in your tenant. See Troubleshooting.
Update the subscription after a new event ships
When Risotto adds an Okta trigger that your connection does not receive yet, the connection card shows Subscribe to new events. Click Update subscriptions, then Update events in the dialog. This needs the Super Administrator role again for the moment of the change. Until you update, the new event appears in the trigger picker under Needs setup.
Events
| Trigger | Okta event | Fires when |
|---|---|---|
| Account created | user.lifecycle.create | An account is created in Okta, before the person can sign in (a staged account) |
| Account activated | user.lifecycle.activate | An account is activated, so the person can sign in. Often the last step of a provisioning run |
| Account suspended | user.lifecycle.suspend | An administrator suspends a user's account. The account keeps its groups, apps, and factors |
| Account locked | user.account.lock | Okta locks a user's account after too many failed sign-ins |
| Account deactivated | user.lifecycle.deactivate | An administrator, a lifecycle rule, or a provisioning run deactivates a user's account |
Creation and activation are two triggers because an account can stay staged for a long time between them. Use Account created for work before the first day, for example to open the onboarding ticket. Use Account activated for work the person can use, for example a welcome message. Suspension and deactivation are two triggers because a suspension is a hold that Okta expects an administrator to lift. An automation that revokes access on a deactivation does not run on a suspension.
Every Okta event records the same fields for the run:
| Field | Meaning |
|---|---|
user_email | The Okta login of the person the event happened to |
user_name | That person's display name, empty when Okta sent none |
okta_user_id | That person's Okta user ID |
actor_email | The login of whoever caused the event: the same person for a lockout, the administrator for a change made in the console. Empty or a service login when a provisioning run or a lifecycle rule did it |
reason | Okta's message for the event, for example "Max sign in attempts exceeded" |
event_time | When Okta recorded the event |
Risotto skips an event when Okta reports that it did not happen, when the subject is not a user, or when the Okta login is not an email address. Okta can deliver the same event twice. Risotto remembers each event for 24 hours and starts one run for it.
Create an automation from an Okta event
Pick the trigger
In the automation editor, click Add trigger, open Okta, and choose one of the account events, for example Account locked. The trigger takes no settings: there is no department filter, because an account event carries no department.
Write the instructions
Tell the agent what to do with the event. Type
@and pick a field from the trigger's data section, for example Okta account locked data, to name it in the text, for exampleuser_email.Set the requestor of any ticket
A ticket the automation opens has no requestor unless you name one. Pin the Create Ticket argument
requestor_emailto{trigger:/user_email}so the ticket belongs to the affected person, or tell the agent to use the event's email. See Referencing trigger fields.Test it
Click Run Now. The dialog fills the event with sample data. The sample event happens to
sample.user@example.com. For a lockout, the actor is the same person. For every other event, the actor issample.admin@example.com. Change the values to test another case, then click Run Now in the dialog. See Running an automation manually.
If Okta in the picker shows the events under Needs setup, the connection does not receive them yet. The section says whether you need to turn the switch on or update the subscription, and Open connection settings takes you to the Okta card.
Limits
- One automation can start at most 75 event runs in a rolling hour. At the limit, Risotto disables the automation until you turn it back on.
- The events are the five in the table above. Risotto has no trigger for other Okta events, for example
user.lifecycle.unsuspend.
Turn the events off
Turn off the Automation triggers switch and click Turn off. Automations that start from an Okta event stop running. They keep their configuration and start again when you turn the switch back on. The change does not touch what Identity Governance subscribed to, and it needs the Super Administrator role for the moment of the change.
If you disconnect Okta, Risotto asks Okta to remove the event hook. If Okta refuses, Risotto stops reading what the hook sends, and you can delete the hook yourself under Workflow > Event Hooks in the Okta Admin Console.
Troubleshooting
The dialog says Okta refused the request
Okta returns the same refusal when the app lacks the okta.eventHooks.manage scope and when it lacks the Super Administrator role. Risotto reads the scopes on the token Okta issued for the request to tell the two apart, and the dialog names the one it found missing:
- "was not granted
okta.eventHooks.manage": on the Okta API Scopes tab of the Risotto API Services app, grant the scope. - "does not hold Super Administrator": on the Admin roles tab, make sure the standard Super Administrator role is assigned to the app. A role on your own admin account does not count. If Okta did not report the token's scopes, the dialog names the role even when the scope is the cause, so check the scope too.
Then click Try again in the dialog. Risotto gets a new token from Okta on the retry, so a scope you grant applies at once.
The Okta card has no Automation triggers switch
The connection uses an Okta API token. Only a connection that uses an API Services app has the switch. Reconnect Okta with an API Services app.
The trigger picker lists the Okta events under Needs setup
The connection does not receive the events yet. The section says whether you need to turn the switch on or update the subscription. Click Open Okta to open the Okta integration page in a new tab.
Related
Something wrong or missing? Report an issue · View as Markdown