Skip to main content

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
warning

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:

CapabilityOperationDescription
Search usersreadFind users by name or email prefix, or by an Okta search expression such as status eq "LOCKED_OUT"
Get a userreadFull profile (including custom attributes), status, credential provider, and sign-in and password timestamps
User groupsreadThe groups a user belongs to
MFA factorsreadA user's enrolled factors and their status. Phone numbers and device details are not returned
Search groups / group membersreadFind groups and list their members
System LogreadQuery audit events (90-day retention) by time range, filter expression, or keywords
Reset passwordwriteOkta 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 userwriteUnlock a LOCKED_OUT user so they can sign in with their current password
Expire passwordwriteForce a password change at the next sign-in. No email is sent
Send a temporary passwordwriteFor 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 sessionswriteSign the user out of all Okta sessions, and optionally revoke their OAuth tokens
Reset MFA factorswriteRemove all MFA enrollments so the user enrolls again
Suspend / unsuspendwriteBlock sign-in while keeping group and app assignments, and restore it later
Add to groupwriteAdd 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.

ModeWhat you provideWhen to use
OAuth 2.0 Service App — recommendedClient ID and private key (PEM), optionally a Key ID and scopesAccess 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 TokenAn Okta API tokenSimplest 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 fieldWhere it is in Okta
Okta Org URLIn 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 IDYour 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.
ScopesThe scopes granted on the app's Okta API Scopes tab. Leave blank to request the defaults.
API TokenSecurity → API → Tokens → Create token. Shown once, when it is created.

Setup​

  1. Create the credential in Okta

    OAuth 2.0 Service App (recommended):

    1. 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.
    2. 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.
    3. In General Settings, clear Require Demonstrating Proof of Possession (DPoP) header in token requests, and save.
    4. 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, plus okta.groups.manage and okta.roles.read to add users to groups. Granting scopes needs a Super Administrator.
    5. On the Admin Roles tab, click Edit assignments and assign a role that can manage the target users (see Prerequisites).
    6. Copy the app's Client ID from the General tab.
    warning

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

    warning

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

  2. Add the Integration in Autoheal
    1. Go to Integrations in Autoheal and click Okta.
    2. Enter a name (e.g. "Okta Production") and your Okta Org URL.
  3. 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 BEGIN line and last END line). Add the Key ID if the app has more than one active key. Leave Scopes blank to request okta.users.read okta.users.manage okta.groups.read okta.logs.read. To add users to groups, also grant okta.groups.manage and okta.roles.read, and enter all six scopes in Scopes.
    • API Token: paste the token.
  4. Test and Save

    Click Test Connection, then Save. For OAuth, the connection test also reports the scopes Okta granted.

Required Permissions​

Okta scopeUsed byNeeded for
okta.users.readSearch users, get a user, user groups, MFA factorsAll user lookups, and the connection test
okta.groups.readSearch groups, group membersGroup lookups
okta.logs.readSystem LogAudit-event queries
okta.users.manageReset password, unlock, expire password, send a temporary password, clear sessions, reset MFA factors, suspend, unsuspendWrite actions only
okta.groups.manageAdd to groupAdding users to groups. Not in the default scopes: grant it and list it in Scopes
okta.roles.readAdd to groupChecking 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_client or 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.