# 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](https://www.tryrisotto.com/docs/dashboard/automations) 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](https://www.tryrisotto.com/docs/integrations/access-governance/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](https://www.tryrisotto.com/docs/integrations/idp/okta) (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](https://www.tryrisotto.com/docs/integrations/access-governance/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](https://www.tryrisotto.com/docs/integrations/idp/okta#required-admin-roles).

## 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](#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

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](https://www.tryrisotto.com/docs/dashboard/automations#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](https://www.tryrisotto.com/docs/dashboard/automations#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](https://www.tryrisotto.com/docs/integrations/idp/okta) 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

- [Automations](https://www.tryrisotto.com/docs/dashboard/automations)
- [Okta integration](https://www.tryrisotto.com/docs/integrations/idp/okta)
- [Okta Identity Governance](https://www.tryrisotto.com/docs/integrations/access-governance/okta-identity-governance)

Source: https://www.tryrisotto.com/docs/integrations/identity/okta-automation-triggers
