Skip to main content

Provision and sync accounts with Okta

Create Okta accounts for employees, keep their profile information in sync, and suspend or deactivate accounts when employees leave directly from Humaans.

The integration covers account provisioning, account activation, data syncing, and deprovisioning. Humaans is the source of truth, meaning changes flow from Humaans to Okta, and not the other way around.

Before you begin

  • Your Humaans role must have permission to manage the Okta integration and its provisioning settings. Owners, admins, finance, and tech have access by default under Integrations in Permissions.

  • An Okta administrator must create an API token with access to read user fields and manage users.

  • Employees must have a work email address in Humaans. Humaans uses this address as their Okta login.

  • Employees must be active members in Humaans to be provisioned. Profiles in the New Hires tab aren't included.

To use Okta for signing in to Humaans, configure SAML separately. To learn more, visit Configuring Enterprise SSO with SAML.

Step 1: Create an API token in Okta

Humaans uses an API token to create and update users in Okta. The token acts with the permissions of the Okta administrator who creates it, so create it with an administrator who can manage users.

  1. Sign in to Okta as an administrator.

  2. In the Admin Console, go to Security, then API.

  3. Click the Tokens tab.

  4. Click Create token.

  5. Enter a name for the token, such as Humaans.

  6. Click Create token.

  7. Copy the token value.

Okta shows the token value once. Copy it before closing the window.

To learn more about creating a token and configuring its permissions and network restrictions, visit Manage Okta API tokens.

Step 2: Connect Okta to Humaans

  1. In Humaans, click Integrations.

  2. Find Okta.

  3. Click Configure.

  4. In Connection, enter your organisation's domain in the Okta Domain field, such as example.okta.com.

  5. Paste the token into the API Token field.

  6. Click Save.

After the connection is saved, the Configuration and Logs tabs become available.

Enter the domain you use to sign in to Okta. Humaans supports domains that end in okta.com, oktapreview.com, or okta-emea.com.

After you save, the token appears as a row of asterisks. To replace it, enter a new token and click Save. Leave the field empty to keep the saved token.

To remove the connection, click Disconnect in the Connection tab.

Step 3 - Choose when accounts are created

To configure provisioning so that when a new account is created in Humaans, one is also added to Okta:

  1. Click Configuration.

  2. Click Provisioning.

  3. Enable Provision Okta users.

  4. In the When to provision dropdown, select As soon as the employee is created or Employment start date.

  5. If you select Employment start date, select the offset: on the day, one day before, one week before, two weeks before, or one month before.

  6. Click Save.

Humaans provisions people once they become active members. This doesn't include new hires. To learn more, visit Adding employees to Humaans.

Humaans creates each account with the person's work email as the Okta username and email, plus their first name, last name, and a link to their Humaans profile. Any other fields come from your field mappings.

If a person already has an Okta account with the same work email, Humaans doesn't create a second account. To link existing accounts, enable Keep data in sync.

Step 4 - Choose when accounts are activated

New accounts start in Okta as staged accounts. Activation moves an account to active and prompts Okta to email the person an activation link. Okta sends this email, not Humaans.

  1. In the Provisioning tab, open the When to activate accounts dropdown.

  2. Select As soon as the account is provisioned, Employment start date, or Never - accounts will be activated manually.

  3. Click Save.

If you select Never, activate each account yourself in Okta.

Step 5 - Choose which fields sync

  1. In Configuration, click Syncing.

  2. Review the Humaans fields and their corresponding Okta fields.

  3. Enable the optional mappings you want to use.

  4. To sync profile changes to Okta, enable Keep data in sync.

  5. Click Save.

The mappings are used when Humaans creates an Okta account. Keep data in sync also sends subsequent changes to mapped fields from Humaans to Okta.

Last name and work email are set by default because they identify the account. Humaans always sends the first name, last name, and work email when it creates an account. The following table lists the default mappings.

Humaans field

Okta attribute

On by default

Company name

Organization

No

First name

First name

Yes

Last name

Last name

Yes

Work email

Email

Yes

Middle name

Middle name

No

Preferred name

Nickname

No

Personal email

Secondary email

No

Employee ID

Employee number

No

Work phone

Primary phone

No

Personal phone

Mobile phone

No

Full address

Address

No

Country code

Country code

No

Timezone

Timezone

No

Job title

Title

No

Department

Department

No

Manager

Manager

No

  • The First name row shows a dropdown for its source instead of a fixed label. Choose between first name or preferred name.

  • Full address maps to the street address, city, state, and zip code attributes in Okta.

  • The Employee ID mapping accepts the Humaans employee ID or the Humaans ID.

  • The Manager mapping accepts the manager's name or email.

Step 6 - Add a custom field mapping

This is an optional step. Map any Humaans field, including your own custom fields, to an additional Okta attribute.

  1. In the Syncing tab, click Add mapping.

  2. In the source column, select the Humaans field to sync from.

  3. In the destination column, select the Okta attribute to sync into.

  4. Click Save.

To remove a mapping, click the trash icon at the end of its row.

The source can be any custom field from the Basics, Employment, and Job role sections.

Built-in fields that aren't in the default table are also available: Humaans ID, pronouns, nationality, teams, contract type, place of work, place of work city, place of work country, probation end date, employment start date, employment end date, last working day, manager, and manager email.

The destination can be any text or list attribute in your Okta user profile, including custom attributes you've added in Okta. Humaans reads the attributes from your Okta profile, so add a custom attribute in Okta first, then select it in Humaans.

When the destination is a list attribute, Humaans sends the value as a list. When the destination is a text attribute and the source has several values, such as teams, Humaans joins the values with commas.

Keep data in sync

  • When you toggle on Keep data in sync, changes you make to people in Humaans update their Okta profile.

  • When it's toggled off, Humaans uses the field mappings only when it creates an account.

  • Syncing is one-way: changes in Okta don't update Humaans.

  • Humaans skips suspended and deactivated accounts.

Sync existing employees

Provisioning and syncing apply to changes made after you set up the integration. To apply your settings to people who were already in Humaans, save your settings, then click Sync all users in the Syncing tab.

Syncing all users provisions, links, updates, or deprovisions accounts as your settings require. Humaans limits how often you can run it. If you've run it recently, the button shows the time you can run it again.

Step 7 - Choose what happens when employees leave

  1. In Configuration, click Deprovisioning.

  2. Enable Deprovision Okta accounts.

  3. Select Deactivate or Suspend in Deprovisioning action.

  4. Select a time in Deprovision at.

  5. Click Save.

Deactivate: the person loses access and their account becomes deactivated.

Suspend: the person loses access and the account stays in Okta as suspended, so you can reactivate it later.

Humaans applies the selected action on the employee's last working day, at the selected time in their timezone. 24:00 (midnight) means the end of their last working day.

Humaans runs a final sync before it deprovisions an account. Accounts that were never activated can't be suspended, so Humaans deactivates them instead. Humaans skips accounts that are already suspended or deactivated.

Review activity and errors

The Logs tab records every provisioning, syncing, activation, and deprovisioning action, including errors. Visit the Logs tab to confirm accounts were created, or to investigate an action that didn't complete.

Reconnect the integration

If Okta stops accepting the token, the Connection tab shows "An authentication issue has occurred. Please reconnect to continue syncing Okta with Humaans."

To restore syncing:

  1. Create a new API token in Okta.

  2. Open the Okta integration in Humaans.

  3. In the Connection tab, paste the new token into the API Token field.

  4. Click Save.

Okta tokens stop working when the administrator who created them is deactivated or loses their administrator role. Create tokens with an account that stays active, such as a dedicated administrator account.

Did this answer your question?