Setting Up an Okta SCIM Integration for User Provisioning

Okta's SCIM (System for Cross-domain Identity Management) integration with Haystack automates the lifecycle of user management, ensuring that your intranet directory remains accurate and up to date in real-time. By linking Okta and Haystack, you can:

• Automate User Provisioning: Automatically create Haystack accounts for new hires and deactivate accounts for departing employees directly from Okta.
• Synchronize Profile Data: Seamlessly push employee attributes—such as job titles, manager relationships, locations, and birthdays—from Okta to populate Haystack profiles.
• Maintain Data Integrity: Ensure that changes made in your primary identity provider (Okta) flow through to Haystack, maintaining a single source of truth for your organizational structure.

Prerequisites & Permissions

Before beginning, ensure you have:

• Haystack Admin: You must have access to the Haystack Admin Console to generate authentication tokens.
• Okta Admin: You need permissions to create and configure SCIM Applications within the Okta portal.

Critical Pre-Integration Step: Check Notifications
If your team is currently in implementation, it is extremely important to ensure that your workspace notification settings are turned OFF before you start provisioning users. Content notifications are sent to all users (even those who haven't signed in yet), and you don't want to launch prematurely!

1. Visit the Security Settings page in your Admin Console.
2. Toggle Email and Mobile Notifications OFF.

Step-by-Step Configuration Guide

Phase 1: Enable SCIM in the Okta

1. In the Okta Admin Console, navigate to Applications and select your existing Haystack Single Sign-On (SSO) application. 
2. Go to the General tab and click Edit
3. Under the Provisioning section, check the box for SCIM.
4. Click Save. A new Provisioning tab will now appear in the application settings.
   

Phase 2: Find the SCIM Setup Details in Haystack 

1. In a separate browser tab, open your Haystack workspace

2. Navigate to the Admin Console and select User Provision & Login in from the lefthand menu. 

3. Toggle ON Enable SCIM based user provision

4. Then click the Generate a new token button. 

5. Click the Save User Provision Option at the bottom of the page. 

6. Keep this browser tab open, we'll use it in the next steps!
   

Phase 3: Configure SCIM Connectivity

1. Return to your Okta admin console and navigate to the newly visible Provisioning tab and select Integration from the left-hand menu.
2. Click Edit and enter the following details:
   • SCIM connector base URL: Paste the SCIM Base URL found on the SCIM setup section of your Haystack admin console. 
   • Unique identifier field for users: Enter userName 
   • Supported provisioning actions: Select Push New Users, Push Profile Updates, and Push Groups.
   • Authentication Mode: Select HTTP Header.
   • Authorization: Paste the token you created into the Haystack Admin Console
3. Click Test Connector Configuration to ensure the supported provisioning action you’ve enabled are green. If all looks good click Close. If you see any errors, double check your URLs and token.
4. Click Save. 
   
   

Phase 4: Configure User Provisioning Settings

1. In the Provisioning tab, select To App from the left-hand menu.
2. Tick the check boxes to enable the following settings:
   • Create Users
   • Update User Attributes
   • Deactivate Users
3. Click Save.
   

Phase 5: Attribute Mapping and Profile Editor

To ensure Haystack receives the correct profile data, you must align the Okta profile attributes with Haystack’s requirements.

1. On your app’s Provisioning tab, scroll down to the Attribute Mappings section of the page. Here you’ll see Okta’s table of default mapping. 
2. Click the Go to Profile Editor button just below the section header. Here, Once on the Profile Editor page, you’ll update the mapping specifications. 

Clean Up Unused Mappings

First, let’s mark the mappings we will not use as Do Not Map. Okta recommends that you remove these and it helps prevent confusion in the future.

1. On the Profile Editor, Click the Mappings button under the Attributes Header. 
2. Click the Okta User to Your App Name section of the header. 
   
3. Click the Green Arrows and select Do Not Map for the following attributes:
   user.middleName, user.honorificPrefix, user.honorificSuffix, user.nickname, user.profileUrl, user.preferredLanguage, user.timezone, user.employeeNumber, user.costCenter, user.organization, user.division, user.managerDisplayName
4. Next, click into the Your App Name to Okta User section of the header. 
5. Click the Yellow Arrows and select Do Not Map for the same following attributes:
   user.middleName, user.honorificPrefix, user.honorificSuffix, user.nickname, user.profileUrl, user.preferredLanguage, user.timezone, user.employeeNumber, user.costCenter, user.organization, user.division, user.ManagerName
6. Click Save at the bottom of the window. 

Add Custom Attributes

Next, we’ll add custom attributes that Haystack supports but aren’t in the Okta default attribute list. 

1. Click Add Attribute at the top of the Attributes list. 
2. In the Display Name field, add Profile Photo
3. In the Variable Name field, add photoURL
4. In the External Namespace field, add urn:ietf:params:scim:schemas:extension:haystack:1.0:User
5. Leave the rest of the fields as-is
6. Click Save
   

Repeat these steps for all of the custom attributes listed below, replacing the fields with the information listed in the table’s columns. Play close attention to the capitalization—ensure you're adding the Variable Name and External name exactly as listed. 

Map Custom Attributes to Okta Profile Attributes

1. Return to the Profile Editor and click the Mappings button under the Attributes header. 
2. Click on the Okta User to Your App Name section in the header. 
3. Scroll to the bottom of the attributes list to find your newly added custom attributes. They’ll be marked with a grey broken arrow, indicating they are unmapped. 
4. For each attribute, click the blank field box on the left side of the mapping and select the Okta profile field that houses the employee data that correlates to the custom attribute. 
   
5. Use the Preview tool if you’d like to confirm your mappings are populating the correct profile data for your users. 
6. When all of your new custom attributes are mapped, click Save Mappings. Then click Apply Updates.

Phase 6: Assign Users to the App

Let’s assign your users to the app! 

1. Find your newly created app in the Applications menu
2. Click Assignments in the header, then click the Assign button.
   
3. From the dropdown, select to assign Users (for one by one testing) or Groups if you’re ready to provision everyone. 
4. Select the Users or Groups to assign as needed. 
5. Once assigned, Okta will begin provisioning these users to Haystack automatically.

Best Practices

• Start with a Test User: Before assigning large groups, assign a single test user to the app and verify their profile updates correctly in Haystack.
• Namespace Accuracy: Ensure the custom attribute namespace (urn:ietf:params:scim:schemas:extension:haystack:1.0:User) is copied exactly, as it is case-sensitive.
• Public Photo URLs: For profile photos to sync correctly, they must be hosted at a publicly accessible URL.
• Date Formats: Ensure your Okta date attributes follow a supported format listed at the bottom of the custom attributes table above for Start Dates and Birthdays.

Need More Help?

If you run into any issues with your SCIM token or attribute mapping, our team is here to help!

• Chat with us: Use the support chat icon in the bottom right of this page.
• Email us: Reach out to support@haystackteam.com.

Keywords: Okta, SCIM, Provisioning, User Sync, Integration, Admin, Attributes, Automation, SAML, Profile Mapping