Okta Integration
Connect Okta to let agents answer identity questions and take routine help-desk actions:
- Find a user and see their status, last sign-in, password age, and where their credentials come from (Okta, Active Directory, or federation)
- See a user's groups and enrolled MFA factors
- Read the System Log to explain a lockout, a failed sign-in, or an admin change
- Reset a password, unlock an account, expire a password, sign a user out everywhere, reset MFA, suspend and unsuspend a user, or add a user to a group
This integration can change user accounts. The nine write actions below are classified as write operations. With no governance policy, an agent that is allowed to use Okta runs them without asking. To require a person to approve each one, add a governance policy such as "the integration's Type is okta, and its Operation type is write". You can also grant the integration read-only scopes (see Required Permissions).
An agent acts on the user a request names. It does not check that the person who asks is that user. Without a policy, anyone who can message the agent can, for example, have it send a user a temporary password: the DM still goes only to that user, but their current password stops working, and with revoke_sessions they are also signed out everywhere. Add the policy before agents use Send a temporary password.
Capabilities
Once connected, agents can:
| Capability | Operation | Description |
|---|---|---|
| Search users | read | Find users by name or email prefix, or by an Okta search expression such as status eq "LOCKED_OUT" |
| Get a user | read | Full profile (including custom attributes), status, credential provider, and sign-in and password timestamps |
| User groups | read | The groups a user belongs to |
| MFA factors | read | A user's enrolled factors and their status. Phone numbers and device details are not returned |
| Search groups / group members | read | Find groups and list their members |
| System Log | read | Query audit events (90-day retention) by time range, filter expression, or keywords |
| Reset password | write | Okta emails a one-time reset link to the user's primary email. The link is never returned to the agent. The user is in RECOVERY until they finish the reset |
| Unlock user | write | Unlock a LOCKED_OUT user so they can sign in with their current password |
| Expire password | write | Force a password change at the next sign-in. No email is sent |
| Send a temporary password | write | For a user who cannot open their mailbox: set a temporary password and send it to them by Slack DM. The password never reaches the agent or its transcript. The DM is sent only to a member of the connected Slack workspace (never another organization's user seen through Slack Connect) whose email equals the Okta user's email or login. The user must choose a new password at the next sign-in. Needs a Slack integration in the same project; an approval rule on Slack or on Okta holds the call. Agents only: it is not available as a workflow step |
| Clear sessions | write | Sign the user out of all Okta sessions, and optionally revoke their OAuth tokens |
| Reset MFA factors | write | Remove all MFA enrollments so the user enrolls again |
| Suspend / unsuspend | write | Block sign-in while keeping group and app assignments, and restore it later |
| Add to group | write | Add a user to a group by the group's name or id, which gives them the group's apps and policies. Only Okta-managed groups can be changed, not app-sourced or built-in groups such as Okta Administrators. A group that grants Okta admin roles is refused, so the agent cannot make anyone an admin. If the user is already a member, nothing changes |
Every user lifecycle action reports the user's status before and after the change. Write actions refuse the me alias, which would target the admin account that owns the credential.
Not included: creating, deactivating, or deleting users; removing a user from a group; changing app assignments or admin roles; and returning a temporary password to the agent (it would place a plain-text password in the agent's transcript — Send a temporary password delivers it by Slack DM instead).
Prerequisites
- An Okta org and an Okta administrator who can create an API Services app (recommended) or an API token. Granting Okta API scopes to an app needs the Super Administrator role.
- An admin role that can manage the users the agent should help. For example, Help Desk Administrator can reset passwords and MFA, unlock users, and clear sessions. Suspending users and adding them to groups needs a broader role such as Group Administrator scoped to those users' groups. See Okta's administrator role permissions.
Authentication
Autoheal supports two authentication modes. Pick one when you add the integration.
| Mode | What you provide | When to use |
|---|---|---|
| OAuth 2.0 Service App — recommended | Client ID and private key (PEM), optionally a Key ID and scopes | Access is limited to the scopes you grant and the admin role you assign to the app. Tokens are short-lived; no long-lived secret is sent to Okta. |
| API Token | An Okta API token | Simplest to set up. The token has the same permissions as the admin who creates it, so create it as a dedicated service admin with a limited role. Tokens expire after 30 days without use. |
Both modes take your Okta Org URL, for example https://acme.okta.com. A custom URL domain also works.
Where to find each value
| Autoheal field | Where it is in Okta |
|---|---|
| Okta Org URL | In the Admin Console, click your username in the upper-right corner; your Okta domain is in the menu. It is also the Admin Console's address without -admin: https://acme-admin.okta.com → https://acme.okta.com. Some orgs use oktapreview.com or okta-emea.com. |
| Client ID | Your API Services app → General tab → Client Credentials section. |
| Private Key (PEM) | Shown once, when you generate the key on the app's General tab (step 1 below). Click PEM before you copy it. |
| Key ID (kid) | Shown with the key in the app's public keys on the General tab. Needed only when the app has more than one active key. |
| Scopes | The scopes granted on the app's Okta API Scopes tab. Leave blank to request the defaults. |
| API Token | Security → API → Tokens → Create token. Shown once, when it is created. |
Setup
- Create the credential in Okta
OAuth 2.0 Service App (recommended):
- In the Okta Admin Console, go to Applications and Resources → Applications (in older consoles, Applications → Applications), click Create App Integration, select API Services, and save the app.
- On the General tab, in Client Credentials, click Edit and set Client authentication to Public key / Private key. Keep Save keys in Okta, click Add key, then Generate new key. Okta shows the private key in JWK format: click PEM, then Copy to clipboard. To use your own RSA or EC key instead, paste its public half.
- In General Settings, clear Require Demonstrating Proof of Possession (DPoP) header in token requests, and save.
- On the Okta API Scopes tab, click Grant for
okta.users.read,okta.groups.read,okta.logs.read, and — for the write actions —okta.users.manage, plusokta.groups.manageandokta.roles.readto add users to groups. Granting scopes needs a Super Administrator. - On the Admin Roles tab, click Edit assignments and assign a role that can manage the target users (see Prerequisites).
- Copy the app's Client ID from the General tab.
warningOkta shows a generated private key only once. Copy it in PEM format before you close the dialog. If you lose it, add a new key to the app.
warningOkta turns on Require Demonstrating Proof of Possession (DPoP) by default for new API Services apps. Autoheal does not send DPoP proofs, so leave it on and every connection test fails with a DPoP error.
API Token: Sign in as the dedicated service admin, go to Security → API → Tokens → Create token, and copy the token. Okta shows it only once.
- Add the Integration in Autoheal
- Go to Integrations in Autoheal and click Okta.
- Enter a name (e.g. "Okta Production") and your Okta Org URL.
- Configure Credentials
Choose an Authentication mode and complete its fields:
- OAuth 2.0 Service App: Client ID and Private Key (paste the whole PEM, including its first
BEGINline and lastENDline). Add the Key ID if the app has more than one active key. Leave Scopes blank to requestokta.users.read okta.users.manage okta.groups.read okta.logs.read. To add users to groups, also grantokta.groups.manageandokta.roles.read, and enter all six scopes in Scopes. - API Token: paste the token.
- OAuth 2.0 Service App: Client ID and Private Key (paste the whole PEM, including its first
- Test and Save
Click Test Connection, then Save. For OAuth, the connection test also reports the scopes Okta granted.
Required Permissions
| Okta scope | Used by | Needed for |
|---|---|---|
okta.users.read | Search users, get a user, user groups, MFA factors | All user lookups, and the connection test |
okta.groups.read | Search groups, group members | Group lookups |
okta.logs.read | System Log | Audit-event queries |
okta.users.manage | Reset password, unlock, expire password, send a temporary password, clear sessions, reset MFA factors, suspend, unsuspend | Write actions only |
okta.groups.manage | Add to group | Adding users to groups. Not in the default scopes: grant it and list it in Scopes |
okta.roles.read | Add to group | Checking that the group grants no admin roles. The tool refuses to add a member without this check. Not in the default scopes: grant it and list it in Scopes |
Scopes say which APIs the app may call; the admin role says which users it may act on. Both are needed.
Send a temporary password also uses the project's Slack integration, whose app needs users:read.email (to check the Slack user is the Okta user) and im:write (to open the DM). A Slack workspace connected before these scopes were requested must be reconnected.
Read-only install: grant only okta.users.read okta.groups.read okta.logs.read, and enter exactly those scopes in the integration's Scopes field. Okta rejects the token request if Autoheal asks for a scope the app was not granted.
Example Queries
Once connected, you can ask an agent questions like:
Why is jane@acme.com locked out? Show the failed sign-ins from the System Log.
Unlock jane@acme.com and tell me her status afterwards.
Reset the password for jane@acme.com and sign her out of all sessions.
Which users in the Engineering group haven't signed in for 90 days?
jane@acme.com can't open her mailbox to reset her password. Send her a temporary password by Slack DM.
Add jane@acme.com to the VPN Users group.
jane@acme.com lost her phone — what MFA factors does she have? Reset them.
Troubleshooting
401 Unauthorized
- API token: check the token is complete and not revoked. Tokens expire after 30 days without use, and stop working if the admin who created it is deactivated.
- OAuth: see "OAuth token request failed" below.
- Check the Org URL is your org (
https://acme.okta.com), not the admin console URL (https://acme-admin.okta.com).
403 Forbidden — missing a scope
The OAuth token lacks a scope the tool needs. Grant it on the app's Okta API Scopes tab. If you set the Scopes field, add it there too.
403 Forbidden — permission denied (E0000006)
The admin role behind the credential cannot act on this user — for example, a Group Administrator acting on a user outside their groups, or any role acting on a Super Administrator. Assign a role that covers the user.
OAuth token request failed
invalid_scope: Autoheal asked for a scope the app was not granted. Grant it, or remove it from the Scopes field.invalid_clientor a signature error: check the Client ID, that the private key matches a public key registered on the app, and the Key ID if the app has several keys. Client authentication must be Public key / Private key.- A DPoP error: clear Require Demonstrating Proof of Possession (DPoP) header in token requests on the app.
Reset password or unlock fails for some users
These actions work only for users whose password Okta manages. Users sourced from Active Directory or a federated identity provider must reset or unlock in that system. Check the user's credential provider with a user lookup.
Rate limited (429)
Okta rate-limits each API per minute. Agents wait for the limit window to reset and retry automatically. Narrow System Log queries with a filter and time range to use fewer requests.