Docs

Integrations / Identity / Okta

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

  1. 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.
  2. Okta sends each account event to Risotto.
  3. 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.manage scope 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

  1. 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.

  2. 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.

  3. 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.

  4. 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

  1. Open the Okta connection

    Go to Settings > Integrations and click the Okta card. Find the Admin API card.

  2. 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.manage scope and the Super Administrator role.

  3. 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

TriggerOkta eventFires when
Account createduser.lifecycle.createAn account is created in Okta, before the person can sign in (a staged account)
Account activateduser.lifecycle.activateAn account is activated, so the person can sign in. Often the last step of a provisioning run
Account suspendeduser.lifecycle.suspendAn administrator suspends a user's account. The account keeps its groups, apps, and factors
Account lockeduser.account.lockOkta locks a user's account after too many failed sign-ins
Account deactivateduser.lifecycle.deactivateAn 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:

FieldMeaning
user_emailThe Okta login of the person the event happened to
user_nameThat person's display name, empty when Okta sent none
okta_user_idThat person's Okta user ID
actor_emailThe 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
reasonOkta's message for the event, for example "Max sign in attempts exceeded"
event_timeWhen 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

  1. 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.

  2. 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 example user_email.

  3. Set the requestor of any ticket

    A ticket the automation opens has no requestor unless you name one. Pin the Create Ticket argument requestor_email to {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.

  4. 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 is sample.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.

Something wrong or missing? Report an issue · View as Markdown