Skip to content
Help Center
withpersona.comDashboard

Using Persona Workflows to manage Okta users & profiles

Last updated on .

View Markdown Contact support Contact support 15 min read
On this page

Overview

Okta is a leading identity and access management (IAM) platform. Organizations use it to protect workforce access to applications. The Persona Okta marketplace integration connects to your Okta tenant. You can then get detailed user profile data and do account actions directly in Persona Workflows.

This integration helps Compliance, IT, and People Ops teams work faster. It syncs important attributes, including custom profile fields. It also automates account lifecycle actions, for example resetting MFA factors or suspending and unsuspending users. It can also manage group membership: it can add users to Okta groups and remove users from them. Teams do not have to change tools.

Benefits

Unified Employee Context: Show Okta profile attributes in Persona, including custom fields such as legal name or date of birth. This decreases manual searches and mismatches.

Reduced Manual Work: Replace repetitive admin tasks with workflows that you can use again. These workflows run the same way every time, at large volume.

Fewer Verification Hurdles: Automatically use the correct identity information from Okta, for example the legal name and not the preferred name. This increases verification success and decreases manual fixes.

Integration Features

The Persona Okta integration gets data in real time and does direct account actions. These features give secure, two-way workflows between Persona and Okta.

  • Retrieve User Profile: Finds an Okta user and returns standard and custom attributes. These attributes add data to Persona Workflows and Cases.
  • Update User: Updates the profile or credentials of a user.
  • Expire Password and Generate a Temporary Password: Expires the current password of a user. Returns a temporary password from Okta for the next sign-in of the user.
  • Reset All MFA Factors: Removes all enrolled authenticators for a user. The user must enroll again at the next sign-in. This is useful after high-risk events.
  • Suspend User: Temporarily stops access for an Okta user during an investigation.
  • Unsuspend User: Gives access again to a suspended user after the investigation clears them.
  • List Groups for a User: Lists the groups that a user is a member of.
  • List Groups: Lists the groups in your Okta tenant. Use it to find the ID of a group by its name or type.
  • Add User to Group: Adds a user to an Okta-managed group.
  • Remove User from Group: Removes a user from an Okta-managed group.

Setting up the Okta integration

Prerequisites

Make sure that you have:

  • Admin access to your Okta account.
  • The necessary API permissions to access Okta credentials.

You can use an Okta API Service or an Okta API key to connect Okta to Persona. To select an authentication method, read the FAQs.

Option A: Connect via API Service

Do these steps to configure the Private Key JWT Authentication method.

  1. In Okta Admin, create an API Services app. Go to Applications and Resources > Applications. Click Create App Integration and select the API Services option.

    • Give the application a name and save it. Copy the Client ID that Okta generates to your clipboard.

  2. In the Persona Dashboard, go to Integrations > Marketplace > Okta.

    • Click + Add Credential. Select Okta API Service.
    • Enter your Okta tenant information. Paste the Client ID from the API Service that you created.
    • When you save, you get a JWKS URL. You give this URL to Okta in the next step.

  3. In Okta Admin, go back to the API Service that you created in Step 1. On the General tab, find the Public Keys section. Select the Use a URL to fetch keys dynamically configuration option. Paste in the JWKS URL from the Persona dashboard in the Url field. Save your changes.

    Do this step before you change the client credentials in Step 5. In Okta, Public Keys and Client Credentials are separate forms, and the client credentials need a saved public key. If you save them in the wrong order, Okta shows the error “An active client authentication (sig) key or URL is required.”

  4. Go to the Okta API Scopes tab. Grant the scopes that your integration needs. At a minimum, grant okta.users.read to get user information. The table below shows scopes that customers frequently grant. Grant only the scopes that you need.

    Okta API ScopeAffected Okta API Endpoints
    okta.users.read: Read User’s InfoList all users; Retrieve a user; List all groups for a user
    okta.users.manage: Manage User’s InfoUpdate a user; Activate a user; Deactivate a user; Reactivate a user; Expire a password and generate a temporary password; Reset all factors for a user; Suspend a user; Unlock a user account; Unsuspend a user; Generate a temporary access code for a user
    okta.authenticators.read: Read AuthenticatorsList all authenticators; Retrieve an authenticator
    okta.groups.read: Read GroupsList groups
    okta.groups.manage: Manage GroupsAdd user to group; Remove user from group

    To add users to groups or remove users from groups, grant okta.groups.manage. To find group IDs with List groups, also grant okta.groups.read. If you add scopes to a credential that is already connected, connect the credential again in Persona. The new scopes then take effect.

  5. Go back to the General tab of your API Service. Make these edits, and save each section:

    SectionEdits to make
    Client Credentials• Set Client authentication to Public key / Private key
    General Settings• Uncheck the Require Demonstrating Proof of Possession (DPoP) header in token requests checkbox

  6. Next, assign an admin role and a resource set to your service app. These define which actions the app can do and which Okta resources it can access. At a minimum, your admin role must have the permission to Retrieve a user. Your resource set must include All users, or all users that you plan to access through Persona. If you add users to groups or remove users from groups, your resource set must also include the groups that Persona changes, not only the users. Other permissions and resources change with your use case.

    If you already have a role and a resource set, assign them in the Admin roles tab of your service app. Then go to the next step.


    To create a new role and resource set:

    • Go to Security > Administrators.

    • Click the Roles tab. Click Create new role.

    • Set Role name to Persona Okta Integration Role or a similar title.

    • Grant permissions for the endpoints that you use. Grant only the permissions that your integration use case requires. For help, use the table below or Okta’s permissions catalog.

      Role permissions by Okta API endpoint

      Okta API EndpointRequired Role Permissions
      List all usersUser > View users and their details or Edit users’ profile attributes
      Retrieve a userUser > View users and their details or Edit users’ profile attributes
      Update a userUser > Edit users’ profile attributes
      Activate a userUser > Edit users’ lifecycle states > Activate user
      Deactivate a userUser > Edit users’ lifecycle states > Deactivate users
      Reactivate a userUser > Edit users’ lifecycle states > Activate users
      Expire a password and generate a temporary passwordUser > Set users’ temporary password
      Reset all factors for a userUser > Reset users’ authenticator
      Suspend a userUser > Edit users’ lifecycle states > Suspend users
      Unlock a user accountUser > Edit users’ lifecycle states > Unlock users
      Unsuspend a userUser > Edit users’ lifecycle states > Unsuspend users
      List groups for a userUser > View users and their details; Group > View groups and their details
      List groupsGroup > View groups
      Add user to groupUser > Edit users’ group membership; Group > Manage group membership
      Remove user from groupUser > Edit users’ group membership; Group > Manage group membership
      List all authenticatorsNone
      Retrieve an authenticatorNone
      Generate a temporary access code for a userUser > Edit users’ authenticator operations > Manage user’s temporary access code

    • Click the Resources tab. Click Create new resource set.

    • Set Name to Persona Okta Integration Resource Set or a similar title.

    • Click + Add resource. Search for Users and select All users.

    • If you use Add user to group or Remove user from group, click + Add resource again. Add the groups that Persona changes.

    • Go back to your application at Applications > Applications. Click the Admin roles tab. Click Edit assignments. Select your new Persona Okta Integration Role role and your new Persona Okta Integration Resource Set resource set. Save your changes.

    For the group actions, the least-privilege option is the Group Administrator role. Assign this role to the Persona app, and limit it to only the groups that Persona must manage.

  7. After you connect, click Test in the Persona dashboard. Make sure that the credential works.

Option B: Connect via API key

  1. Create an API token in Okta Admin.
    • Go to Security > API > Tokens > Create Token.
    • Copy the API token.
    • Note: In this article, “API key” and “API token” have the same meaning.
    • An API token has the permissions of the admin who created it. If you use the group actions, that admin needs a role that can manage the target groups.
  2. Add the API token as a credential in Persona.
    • Go to Persona Dashboard > Integrations > Marketplace > Okta > Add Credential > Okta API Key Credential.
    • Enter your Okta subdomain. Give the credential a nickname. Paste the token.
  3. After you connect, click Test. Make sure that the credential works.

Persona does not support OAuth 2.0 for our Okta integration. Okta OAuth 2.0 credentials have a maximum lifetime of 90 days, and you cannot extend it. Thus, they are not applicable for long-lived integrations. This authorization scheme is not for machine-to-machine communication. It causes integration errors.

Using the Okta integration in a workflow

  1. Create a new workflow, or open an existing workflow that you want to update.
  2. Add a new Action step > Integrations.
  3. Select the Okta integration. Select your Okta credential.
  4. Configure the inputs, for example the user identifier and the action. Map outputs to Persona fields as necessary.
  5. Save and publish the workflow.

Okta Operations Overview

Persona can sync field values. Persona can also use the Okta API to do these actions:

  • Get user profiles.
  • Issue temporary passwords.
  • Reset MFA factors.
  • Suspend or unsuspend users.
  • Manage group membership.

These actions give two-way workflows. Teams can manage investigations and not change platforms. Below is a full list of the Workflow Action steps and configurations for the Okta integration:

Retrieve a user

Gets the profile of an Okta user and puts the values in Workflow variables in Persona.

Configuration Steps:

  • Provide values for required fields:
    • ID of the user to retrieve.
  • Provide values for optional fields:
    • Fields to include: limits the result to the listed properties, for example status,profile:(login,email). Use commas to separate properties. Profile attributes use the format profile:(firstName,lastName). You can select custom profile attributes in the same way. The result always includes the id of the user. Persona sends the selection to Okta, so fields that you do not select never leave Okta. Persona also applies the same selection to the response. Thus, Persona does not return fields that you do not select, and does not keep them in the Workflow integration log. If you leave this field empty, the result includes all fields.

Update a user

Updates the profile or credentials of an Okta user. You can use this action to reset the password of the user.

Configuration Steps:

  • Provide values for required fields:
    • ID of the user to reset.
    • Request body that includes the attributes to update. For the request body schema, read Okta’s documentation.

Activate a user

Configuration Steps:

  • Provide values for required fields:
    • ID of the user to activate.

Deactivate a user

Configuration Steps:

  • Provide values for required fields:
    • ID of the user to deactivate.

Reactivate a user

Configuration Steps:

  • Provide values for required fields:
    • ID of the user to reactivate.

Reset all factors for a user

Removes all enrolled MFA authenticators for the specified user. The user must enroll again at the next sign-in. Teams frequently use this action after a high-risk event, or when they think that devices are compromised.

Configuration Steps:

  • Provide values for required fields:
    • ID of the user to reset.

Suspend a user

Temporarily stops the access of a user during an investigation. A suspended user cannot access apps that Okta protects until you unsuspend the user.

Configuration Steps:

  • Provide values for required fields:
    • ID of the user to suspend.

Unlock a user account

Unlocks a user who is locked out. Also unlocks an active user that Okta blocks from unknown devices. Unlocked users have an ACTIVE status and can sign in with their current password.

Configuration Steps:

  • Provide values for required fields:
    • ID of the user to unlock.

Unsuspend a user

Gives access again to a suspended user. Enter the user identifier to put the user back in an active state. Access then starts again as your Okta policies specify. Teams usually use this action after an investigation ends or after they resolve false positives. This keeps the effect on legitimate users small.

Configuration Steps:

  • Provide values for required fields:
    • ID of the user to unsuspend.

List groups for a user

Lists all groups that the user is a member of.

Configuration Steps:

  • Provide values for required fields:
    • ID of the user.

List groups

Lists the groups in your Okta tenant (GET /api/v1/groups). Use this action to find the ID of a group. The action returns the ID, Type, Name, and Description of each group. You can change the membership only of groups with the Type OKTA_GROUP.

Configuration Steps:

  • Provide values for optional fields:
    • Query: finds groups whose name starts with this value. The match is not case-sensitive.
    • Search: a filter expression that Okta applies to the groups. For the syntax, read Okta’s documentation.
    • Limit: the maximum number of groups to return.
    • After Cursor: the cursor that gets the next page of results.

Add user to group

Adds a user to an Okta group (PUT /api/v1/groups/{groupId}/users/{userId}). The user gets the apps, admin roles, and permissions of the group. If the user is already a member of the group, the action succeeds and makes no change.

You can change the membership only of Okta-managed groups (Type OKTA_GROUP). You cannot change built-in groups, such as Everyone. You also cannot change groups that Okta imports from a directory, such as Active Directory or LDAP. If you select one of these groups, Okta does not accept the request and the action fails.

Set the Group ID in the workflow step. Do not use a value that the end user entered. Group membership can give apps, admin roles, and permissions. For more information, read Securing high-risk actions in Workforce integrations.

Configuration Steps:

  • Provide values for required fields:
    • Group ID: the ID of the group. To find it, use List groups.
    • User ID: the ID of the user. To find it, use List all users or Retrieve a user.

Remove user from group

Removes a user from an Okta group (DELETE /api/v1/groups/{groupId}/users/{userId}). The same limits apply as for Add user to group. You can change only Okta-managed groups (Type OKTA_GROUP). You cannot change built-in groups or groups that Okta imports from a directory.

Okta sign-on policies and MFA policies are often assigned to groups. If you remove a user from one of these groups, the sign-in protection of the user can become weaker. Do not use this action on a group that enforces a sign-on or MFA policy, unless that is your intent. Set the Group ID in the workflow step.

Configuration Steps:

  • Provide values for required fields:
    • Group ID: the ID of the group. To find it, use List groups.
    • User ID: the ID of the user. To find it, use List all users or Retrieve a user.

FAQs

When should I use an API service vs. an API key?

An API service is a service account for service-to-service communication. API service credentials use Private Key JWT authentication. This gives more security than API keys. You configure the capabilities on the service. They are not connected to a specific Okta user.

An API key is a unique, secret code. Applications use it to access an API. An API key is like a master key that you generate in Okta and give to Persona. An API key has the same capabilities as the Okta user who issued it. If someone deactivates that user, the API key stops working.

Persona recommends API services for our Okta integration. Persona recommends API keys only for tests. Okta API services give durable credentials. Their capabilities are not connected to a specific user account. Thus, the integration is more reliable, more secure, and easier to manage. API keys are less secure. A person who has the key can send requests to Okta for you, usually with broad permissions.

What happens when I reset all factors?

Okta clears all MFA enrollments for the user. At the next sign-in, Okta tells the user to enroll factors again, as your Okta policies specify.

Why can’t Persona add a user to a group?

These are the usual causes:

  • The group is not Okta-managed. Persona can change only groups with the Type OKTA_GROUP. To see the Type of a group, use List groups.
  • The credential does not have the okta.groups.manage scope. Or, the admin role or resource set of the Persona app does not include the group.
  • The user ID or the group ID is not correct.

Plans Explained

Okta Integration by plan

Startup ProgramEssential PlanGrowth PlanEnterprise Plan
Okta IntegrationNot AvailableNot AvailableLimitedAvailable

Learn more about pricing and plans.

Was this page helpful?If something is missing, let us know and we will take a look.
Thanks for the feedback. It helps us improve these docs.

Related articles

Configure Persona for the Okta Account Management Policy
Marketplace and 3rd-Party Integrations · Authentication
Okta integration overview
Marketplace and 3rd-Party Integrations · Authentication
Securing high-risk actions in Workforce integrations
Marketplace and 3rd-Party Integrations · Workforce