Okta Setup

Okta is an identity and access management platform. Once connected, Junto can administer identity in a client's Okta org during ticket work -- look up and manage users, run lifecycle actions (activate, suspend, deactivate, unlock), reset passwords, revoke sessions, reset MFA factors, manage groups and application assignments, and investigate sign-in activity.

How Junto Connects

Junto connects to each Okta org through an API Services app you create in that org, using OAuth 2.0 client credentials. Every client has their own Okta org with its own credentials, so you connect Okta once per Junto company -- there is no shared, cross-tenant key. A run scoped to one company can only ever reach that company's Okta org.

Junto talks to Okta's management API directly and only offers the actions the scopes you grant allow. If a required scope is missing, the agent explains what to grant rather than failing silently.

Coming soon: one-click install from the Okta catalog

The steps below set up an API Services app manually, which works today. A one-click install from the Okta Integration Network is coming -- you'll add Junto from your Okta catalog and Okta will generate the credentials for you, no manual app creation required. Until then, follow the manual setup below.

Prerequisites

• An Okta org (Okta Identity Engine) for the client you're connecting
• Super Administrator access in that org, to create an API Services app and grant it admin permissions
• The org's Okta domain (for example, acme.okta.com or a custom domain)

Step 1: Create an API Services App in Okta

1. Sign in to the Okta Admin Console for the client's org.
2. Go to Applications → Applications and click Create App Integration.
3. Select API Services and click Next.
4. Give it a name (for example, "Junto") and click Save.
5. On the app's General tab, under Client Credentials, confirm Client authentication is set to Client secret. If it shows Public key / Private key, click Edit, choose Client secret, and save.
6. Copy the Client ID and, under CLIENT SECRETS, the Client secret. The secret is shown only once -- store it securely before leaving the page.

Step 2: Grant API Scopes

The scopes you grant control exactly what Junto can do. Grant the full set below for the complete capability set, or omit the *.manage scopes for an area to keep Junto read-only there.

1. On the app, open the Okta API Scopes tab.
2. Click Grant on each scope Junto should have:

Scope	Grants
okta.users.read	Look up and search users
okta.users.manage	Create, update, and run lifecycle actions on users
okta.groups.read	Look up groups and members
okta.groups.manage	Create, update, delete groups and manage membership
okta.apps.read	Look up applications and their assigned users
okta.apps.manage	Assign and unassign users and groups to applications
okta.factors.read	View users' enrolled MFA factors
okta.factors.manage	Reset users' MFA factors
okta.logs.read	Query the System Log for sign-in activity
okta.roles.read	List administrator role assignments

Least privilege

Granting a *.manage scope automatically includes its matching *.read. Grant only the areas you want Junto to act in -- for example, grant okta.logs.read and the *.read scopes for a read-only, investigation-focused connection.

Step 3: Assign an Admin Role to the App

Scopes alone allow Junto to read data, but administering users (deactivating accounts, resetting passwords, clearing sessions, resetting MFA) requires the app to hold an administrator role.

1. On the app, open the Admin roles tab.
2. Click Edit assignments.
3. Assign a role with sufficient permissions for the actions you want Junto to perform:
   • Super Administrator covers every capability.
   • For least privilege, assign narrower standard or custom roles (for example, a role scoped to user and group management) instead -- just ensure it covers the lifecycle, password, session, and factor actions you expect the agent to take.
4. Save the assignment.

Step 4: Configure in Junto

1. In Junto, go to Settings → Integrations → Okta.
2. Select the company whose Okta org you're connecting and click Connect.
3. Fill in:
   • Okta domain -- the org's domain, without the -admin part (use acme.okta.com, not acme-admin.okta.com). Custom domains are supported -- enter the full hostname.
   • Client ID -- from Step 1.
   • Client Secret -- from Step 1. This is encrypted before storage and never shown again.
4. Click Connect, then use Test connection to verify the credentials.
5. Repeat per company for each client Okta org you manage.

What the Agent Can Do

Once connected, the agent can administer the connected company's Okta org across the areas below. Every write action is approval-gated -- the agent proposes the change and a technician confirms before it runs.

Users & Lifecycle

Capability	Description	Risk Level
List / search users	Find users by name, email, status, or attribute	Low
Get user details	View a user's profile and current status	Low
Create user	Create a user, activated now or staged	Medium
Update user profile	Update a user's profile attributes	Medium
Activate user	Move a staged or deactivated user to active	High
Suspend / unsuspend user	Temporarily disable and re-enable a user (reversible)	High
Deactivate user	Deactivate a user -- destructive: removes the user's application assignments	High
Unlock user	Unlock a locked-out account	Medium
Expire password	Force a password change at next sign-in	High
Reset password	Send a reset email or set a temporary password	High
Clear sessions	Revoke all of a user's active sessions	High

Suspend vs. deactivate

Suspend is reversible and preserves the user's access; deactivate drops the user's application assignments and is intended for offboarding. The agent proposes suspend unless you explicitly ask to deactivate. Lifecycle actions also depend on the user's current state -- if a user is in a state where an action isn't valid, the agent explains the current state and the valid next step.

MFA & Factors

Capability	Description	Risk Level
List enrolled factors	See which MFA factors a user has registered	Low
Reset factors	Reset all of a user's factors, or a single factor	High

Groups

Capability	Description	Risk Level
List / search groups	Find groups across the org	Low
Get group	View a group's details	Low
List group members	List the members of a group	Low
Add / remove member	Add or remove a single group member	Medium
Bulk add / remove members	Add or remove many members at once, with per-user results	Medium
Create / update group	Create a group or update its name and description	Medium
Delete group	Delete a group	High
List group rules	View the rules that drive dynamic group membership (read-only)	Low

Applications

Capability	Description	Risk Level
List applications	List the org's applications	Low
Get application	View an application's details	Low
List application users	See which users are assigned to an application	Low
Assign / unassign user	Grant or revoke a user's access to an application	Medium
Assign group to application	Grant an application to everyone in a group	Medium

Sign-in Logs & Admins

Capability	Description	Risk Level
Query sign-in logs	Search the System Log by user, time range, event type, and outcome	Low
List failed sign-ins	A focused view of failed sign-in attempts	Low
List admin role assignments	See who holds administrator roles in the org	Low

High-impact actions -- lifecycle changes, password resets, session and factor resets, group deletion -- always require technician approval before the agent proceeds.

Troubleshooting

• Test connection fails with an authentication error -- Re-check the Client ID and Client Secret, and confirm Client authentication is set to Client secret on the app (Step 1). Regenerate the secret in Okta and reconnect if needed.
• Test connection fails to reach Okta -- Verify the Okta domain. Use the org domain (acme.okta.com), not the -admin hostname, and include the full hostname for custom domains.
• The agent says a scope is missing -- Grant the named scope on the app's Okta API Scopes tab (Step 2), then reconnect so Junto picks up the updated grants.
• A read works but a write action fails with a permission error -- The app likely lacks an administrator role. Assign a role that covers the action on the app's Admin roles tab (Step 3).
• A lifecycle action is rejected -- The user may be in a state where that action isn't valid (for example, activating an already-active user). The agent will name the current state and the valid next step.
• The agent can't find a user or group -- Confirm you're working in the ticket or run scoped to the right company. Each company reaches only its own connected Okta org.