Skip to main content

Some screenshots show mcp-s.com, which some existing organizations still use. New organizations use withwillow.ai. Copy the URLs shown in your own organization.

SCIM with Okta

Willow has an official integration in the Okta Integration Network (OIN). The same app handles both SSO and SCIM, so this guide covers both. If you only need SSO, see Configure Okta.

Supported features​

SCIM features​

  • Import Users
  • Create Users
  • Update User Attributes
  • Deactivate Users
  • Group Push

For supported SSO features, see Configure Okta.

Prerequisites​

Before you begin, ensure you have:

  • An Okta admin account
  • Your Willow Admin URL (e.g. app.withwillow.ai, or willow-admin.<your-domain>.com for On-Premise)
  • Your Willow Connect URL (e.g. acme-corp.withwillow.ai, or willow-dashboard.<your-domain>.com for On-Premise)
  • A SCIM API token — see Generate a SCIM API token in the SCIM provisioning overview

1. Add the Willow integration​

  1. In the Okta Admin Console, go to Applications → Browse App Catalog
  2. Search for Willow and select Add Integration
  3. Fill in:
    • Application label: "Willow" (recommended)
    • Willow Admin URL: your admin URL without a trailing /
    • Willow Connect URL: your connect URL without a trailing /
  4. Select Done
Adding the Willow integration from the Okta app catalog

2. Configure SSO​

  1. In the Willow app on Okta, go to the Sign On tab
  2. Select Edit
  3. Set Application username format to Email
  4. Select Save
  5. Copy the Client ID and Client Secret

Then finish in Willow:

  1. Go to Settings and expand Authentication Settings
  2. Select Edit on the SSO Provider card, and set Provider to Okta
  3. Enter the Client ID, Client Secret, and your Issuer URL. Use the org authorization server: your Okta domain with no path (e.g. https://dev-123456.okta.com), without the -admin suffix (for example, acme-corp.okta.com, not acme-corp-admin.okta.com). Do not add a /oauth2/default path; the Willow OIN app cannot use a custom authorization server.
  4. Select Save
Okta SSO provider configured in Willow Authentication Settings

For advanced SSO options (client credentials, passthrough refresh token, auth exchange), see Configure Okta.

3. Configure the SCIM connector​

  1. Open the Provisioning tab → Integration
  2. Check Enable API integration
  3. Paste your SCIM API token into API Token
  4. Keep Import Groups enabled to sync Willow groups into Okta
  5. Select Test API Credentials; if it succeeds, select Save
Configuring the Willow SCIM API integration in Okta

4. Enable provisioning actions​

  1. In Provisioning → To App, select Edit
  2. Enable:
    • Create Users
    • Update User Attributes
    • Deactivate Users
  3. Select Save
Enabling Create, Update, and Deactivate provisioning actions to the app in Okta

5. Assign users or groups​

  1. Open the Assignments tab
  2. Select Assign → Assign to Groups
  3. Assign the groups you want synchronized with Willow
Assigning groups to the Willow app in Okta

6. Push groups (optional)​

Assigning a group in step 5 provisions its users into Willow. This step is only needed if you also want the groups themselves (and their membership) created in Willow.

  1. Open the Push Groups tab
  2. Select + Push Groups → Find groups by name
  3. Add the groups you assigned in step 5
  4. Select Save

7. Sync a secondary email (optional)​

Use this when your people have a second address that other tools know them by, for example a Slack workspace on a different domain than Okta. Willow stores the second address as an email alias on the same user, so the user is recognized by either address and their primary email does not change.

warning

Ask your Willow contact to turn on Email Aliases for your organization before you add this mapping. Without it, Willow keeps one email per user, and the secondary email can replace the user's primary email.

  1. Go to Directory → Profile Editor and open the Willow app's user profile (for example, Willow User)
  2. Select Add Attribute and fill in:
    • Data type: string
    • Display name: Secondary email
    • Variable name: secondEmail
    • External name: emails.^[type=='other'].value
    • External namespace: urn:ietf:params:scim:schemas:core:2.0:User
  3. Select Save
Adding the Secondary email attribute to the Willow app profile in Okta
  1. Select Mappings, then open the Okta User to Willow tab
  2. In the secondEmail row, enter user.secondEmail and keep Apply mapping on user create and update selected
  3. Select Save Mappings, then Apply updates now
Mapping user.secondEmail to the secondEmail attribute on the Okta User to Willow tab

Adding the attribute alone sends nothing. Okta only sends the secondary email once step 5 maps it.

Each user's Secondary email in their Okta profile must hold the address you want as the alias. Push one user first, then check SCIM Logs: the request should carry two emails entries, and the user's row on the Users page shows a +1 badge. Then push everyone.

If another Willow user already has that address, as a primary email or an alias, Willow rejects the update with a 409 error, and Okta shows the error on that user. Remove or merge the other user, then retry.

Verification​

Once configured, the integration will automatically:

  • Provision new users when they are added to assigned groups in Okta
  • Update user attributes when they are modified in Okta
  • Deactivate users when they are removed from assigned groups
  • Sync group membership changes via SCIM

You can verify the sync status in Okta by checking the Provisioning tab logs and monitoring user and group operations.

On this page