Okta

ThoughtFarmer integrates with Okta for SSO authentication and user management, allowing users to log in with a single set of credentials while ensuring their information syncs automatically from Okta to ThoughtFarmer.

If you have existing active users in ThoughtFarmer and plan to transition them to Okta, contact the ThoughtFarmer Helpdesk before proceeding.

Okta setup

Setting up Okta integration with ThoughtFarmer involves two main steps:

1. Configure authentication – Enable SSO login to ThoughtFarmer via Okta.
2. Set up user synchronization – Sync user data from Okta into ThoughtFarmer.

For cloud clients: Wait until your custom URL has been set up before proceeding with Okta configuration.

Configure Okta

1. In Okta, go to Applications > Applications in the left-hand menu.

2. Click Create App Integration, select SAML 2.0 as the sign-on method, and click Next.
   
   
   
   

3. Under General Settings, enter a name and upload a logo for your Okta application.
   
   
   
   

Configure SAML

1. Under SAML Settings:

• • Single Sign-On URL: https://tfurl.com/auth/saml/assertionconsumerservice
    • Replace https://tfurl.com with your ThoughtFarmer site URL.
    • Check Use this for Recipient URL and Destination URL.
  • Audience URI: thoughtfarmer
  • Refer to the screenshot for additional required settings.

4. Click Next, then Finish.

Assign users

1. Open the Assignments tab in your Okta application.
2. Click Assign, then assign users who should have access to ThoughtFarmer.
3. Ensure that usernames and relevant fields are correctly mapped to the Okta application.
   
   
   
   

Retrieve SAML setup instructions

1. Navigate to the Sign On tab.
2. Click View SAML Setup Instructions to access the necessary configuration details for ThoughtFarmer.

Configure ThoughtFarmer 

1. Log in to ThoughtFarmer.
2. Go to the Admin panel: Users & security section > Login provider page.
3. Under External Providers, click Add New and select Custom SAML.

Fill in the login provider details

Under Settings:

• Hostname: Your ThoughtFarmer site URL.
• Login Provider complete hostname: Okta's Identity Provider Single Sign-On URL.

Under Custom SAML Configuration:

• • External user store configuration: Select your Okta external user store (see the User sync setup section for details on creating it).

Advanced SAML options section

• • Single Sign-On Binding Type: HTTP Redirect.
  • Sign Out URL: https://yourOktaApiUrl.com/login/signout
    
    • Use Okta's Identity Provider Single Sign-On URL, but only keep the https://....com portion.
  • Single Sign-Out Binding Type: HTTP Redirect.
  • Certificate Details: Paste Okta's X.509 Certificate (including BEGIN CERTIFICATE and END CERTIFICATE).
  • Configuration Options: Enable the following checkboxes:
    • Want SAML Response Signed
    • Want Assertion Signed
  • Issuer URL / Name: Okta's Identity Provider Issuer.

Click Save to complete the setup.

Set up user sync

ThoughtFarmer allows scheduled syncing of user data from Okta, enabling:

• Automatic user creation and deactivation in ThoughtFarmer.
• Profile updates based on Okta data.
• Group and security membership synchronization from Okta groups.

Configure Okta sync in ThoughtFarmer

1. Go to the ThoughtFarmer Admin panel: Users & Security section > Employee Directory Connector page.
2. Click Add new external user store.
3. Enter a name (e.g., Okta).
4. Select Okta from the Type dropdown.
5. Click Save.

Set up Okta configuration in ThoughtFarmer

1. Under the Configuration tab, update the following JSON settings with your Okta details:

{
"oktaApiToken": "okta_api_token_here",
"oktaApiUrl": "https://oktaapiurl",
"oktaAppName": "okta_application_name_here"
}

Retrieve Okta configuration values

1. Get the Okta API token

   1. In Okta, go to Security > API.
   2. Click the Tokens tab.
   3. Click Create Token and enter a name.
   4. Under API calls made with this token must originate from, select Any IP.
   5. Click Create Token.
   6. Copy the generated token and paste it into the oktaApiToken field in the Okta configuration in ThoughtFarmer.
2. Okta API URL
   1. In Okta, go to Applications > [your app] > Sign On.
   2. Click View SAML Setup Instructions.
   3. The Okta API URL is the Identity Provider Single Sign-On URL, but only the https://....com portion (omit everything after .com)
      
3. Okta App Name
   1. In Okta, go to Applications > [your app] > Sign On.
   2. Click View SAML Setup Instructions.
   3. Locate the Identity Provider Single Sign-On URL.
   4. In the URL, find the segment between /app/ and the next / (before /sso/saml). This is your Okta App Name.
      • Do not include any additional alphanumeric ID that appears after this segment.
   5. Copy this value and paste it into the oktaAppName field in ThoughtFarmer.
4. Validate the Configuration
   
   1. In ThoughtFarmer, click Save Configuration.
   2. Navigate to the Synchronization Settings tab.
   3. Click Validate Credentials.
   4. Refresh the page and confirm the credentials are successfully validated.

Field mappings

To ensure accurate synchronization of user data, you can map additional fields in the Employee Directory Connector. This allows user attributes from Okta to be correctly imported into ThoughtFarmer.

For a detailed reference on which Okta attributes correspond to ThoughtFarmer fields, refer to the Identity Provider Field Mappings documentation.

This guide includes:

• Standard attributes that ThoughtFarmer supports
• Syntax guidelines for custom attributes
• Best practices for configuring field mappings.

Set up field mappings in Okta

To ensure user data syncs correctly between Okta and ThoughtFarmer, field mappings must be configured in both platforms. Note that Okta does not support syncing profile images.

Add Attributes in Okta

1. In Okta, navigate to Directory > Profile Editor.
2. Find your ThoughtFarmer application, and click Profile.
3. Click + Add Attribute and create an attribute for each ThoughtFarmer profile field listed in the Field Mappings tab.
   • Use the same name as the corresponding ThoughtFarmer profile field, but remove spaces and special characters.
     
     
4. Once all attributes are added, click Save.

Map Okta Attributes to ThoughtFarmer fields.

1. Click Mappings in the Profile Editor.
2. Select the Okta User to [Your ThoughtFarmer Application] tab.
3. On the Okta user profile side, select the corresponding Okta profile field.
4. On the ThoughtFarmer user profile side, choose the matching ThoughtFarmer field.
5. Click the green Apply mapping on user create and update arrow.
6. Click Save Mappings to apply the changes.
   
   

Test Okta sync and authentication

Run an on-demand sync

1. In ThoughtFarmer, navigate to the Employee Directory Connector store (Admin panel: Users & security > Employee directory connector > Okta) > Synchronization Settings.
2. Select the sync tasks you want to run under On-demand synchronization.
3. Click Synchronize now.
4. (Optional) Set up a Daily synchronization schedule to automate synchronization.
5. We recommend running Bulk update users first to review the users being pulled in without modifying the current user list.
   
   

Verify the sync status

1. Click the Synchronization Logs tab.
2. The sync status should display Success once completed.
   • The process may take several minutes depending on the number of users.
3. Click View Details to review:
   • Which users were synced.
   • The specific user data pulled from Okta.

Test authentication

1. Create a temporary Admin user:
   1. Add a regular user with Admin privileges for testing.
   2. Delete this account when no longer needed.
   3. This user serves as a backup in case of Okta authentication issues.
2. Convert an existing ThoughtFarmer user to an Okta user:
   
   1. Navigate to the Admin panel > Users &Security section > User Management page.
   2. Search for the user.
   3. Click the gear icon next to their name and select Edit Account.
   4. Change Account Type to External.
   5. Enter the user’s Okta username and select the correct Okta store.
   6. Click Save.

Repeat Step 2 for any other existing users migrating to Okta.

If a user does not already exist in ThoughtFarmer, allow the sync to create the account.

For bulk updates, submit a Support request via the ThoughtFarmer Helpdesk.