ThoughtFarmer is able to integrate with Okta for SSO authentication and user management. This means one less password for users to remember, and automatic syncing of user information from Okta into ThoughtFarmer. Read more below on how you can set up Okta.

If you already have active users in ThoughtFarmer and you would like to switch them over to Okta, please contact the ThoughtFarmer Helpdesk first.

Okta setup

There are two main parts to setting up Okta:

1. Set up authentication into ThoughtFarmer via Okta.
2. Set up user sync so user data can be synced into ThoughtFarmer from Okta.

Cloud clients, please wait for us to set up your custom URL first before you set up Okta.

Set up authentication

1. In Okta, go to the Admin section > Applications. Add a new application. Create a new application integration. Choose the sign-on method SAML 2.0.
   
   
   
   

2. Under General Settings: Choose a name and logo for your Okta application.
   
   
   
   

3. Under SAML Settings:

• • Single Sign-on URL: https://tfurl.com/auth/saml/assertionconsumerservice (Replace "https://tfurl.com" with the url of your ThoughtFarmer site.)
    • Select the checkbox "Use this for Recipient URL and Destination URL".
  • Audience URI: thoughtfarmer
  • Refer to the screenshot below for the remaining settings to choose.

4. Click Next and Finish.

5. This will bring you to the page pictured below within the newly created application in Okta. Add some ThoughtFarmer users to your Okta application by clicking the Assignments tab. Click Assign and assign users so they can have access to your ThoughtFarmer intranet. Usernames and fields can be assigned on an application by application basis, so it is important that the data is set to populate the Okta application users.
   
   
   
   

6. Next you will need the SAML setup instructions. Click View Setup Instructions. This opens up a page with the information that you need to set up a new Login Provider in ThoughtFarmer.
   
   
    
7. Log into ThoughtFarmer and add a new login provider by going to Admin Panel: Users & security section > Login Provider page. Under External Providers, add a new login provider. Select Custom SAML as the type.
8. Fill in the create login provider page fields as described below, using the values from Okta's setup instructions that you opened in step 4.
   • Hostname: your ThoughtFarmer site URL
   • Login Provider complete hostname: Okta's "Identity Provider Single Sign-On URL"
   • External user store configuration: select your Okta external user store (see the User sync setup heading below on how to create it)
   • Single Sign On Binding Type: HTTP Redirect
   • Identity Provider Sign Out URL:  https://yourOktaApiUrl.com/login/signout (The Okta API URL is your "Identity Provider Single Sign-On URL" but only the "https://....com" portion.)
   • Single Sign Out Binding Type: HTTP Redirect
   • Certificate details: Okta's "X.509 Certificate" (include the "BEGIN CERTIFICATE" and "END CERTIFICATE" parts)
   • Configuration options: Select the checkboxes: "Want SAML Response Signed" and "Want Assertion Signed"
   • Issuer URL / Name: Okta's "Identity Provider Issuer"
     
     

User sync setup

ThoughtFarmer also has a feature that allows scheduled syncing of data from Okta into ThoughtFarmer. This allows users to be created and deactivated in ThoughtFarmer, user profiles to be updated, and membership of ThoughtFarmer groups and security groups to be based on the membership of Okta groups.

The Okta sync in ThoughtFarmer also has to be configured. See below on how to do it:

1. Go to the ThoughtFarmer Admin Panel: Users & security section > Employee Directory Connector page. Click Add New external user store.
2. Select the type Okta, give it a name (eg. Okta) and Save.
3. For the ThoughtFarmer user you're currently logged in as, if you want that user to be an Okta user, you need to convert the account type to External.
   1. Go to the Admin Panel: Users & security section > User Management page.
   2. Search for the user. On the right of the user's listing, click the gear icon, and select Edit Account.
   3. Change the user type to External, add the Okta username, choose your Okta in the dropdown and Save.
   4. Do the same for any other existing users in ThoughtFarmer that will come from Okta. If the Okta user doesn't have a ThoughtFarmer account yet, you can let the sync create the user. If you need help bulk changing many users at a time, please submit a request to ThoughtFarmer Helpdesk.
      
      
       
4. Go back to the Admin Panel: Users & security section > Employee Directory Connector page. Click on [your Okta]. On the Field Mappings tab, the link between the Okta data and the ThoughtFarmer data can be set. See instructions below on how to set up field mappings on both the ThoughtFarmer and Okta ends.

Set up field mappings in ThoughtFarmer

Here you can configure which Okta profile fields should sync with which ThoughtFarmer profile fields. 

1. The ThoughtFarmer field column is the name of the ThoughtFarmer profile field. The External store field is the ThoughtFarmer field name in Okta.
2. For the Data owner column, choose your Okta external user store. 

Set up field mappings in Okta

For each field mapping in ThoughtFarmer, you'll need to set them up in Okta too. Currently, Okta does not support profile images being uploaded.

1. In Okta, go 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 in the Field Mappings tab above. Give it the same name as the profile field in ThoughtFarmer, but without spaces and special characters.
   
   
   
   
4. In Okta, click Mappings.
   
   
    
5. Click the Okta User to <name of your application> tab.
6. The Okta user profile side is where you select the profile field in Okta. The ThoughtFarmer user profile side shows the fields that Okta will map to. Select the green arrows so the field mappings can be applied on user creation and update.
   
   

Set up Okta configuration in ThoughtFarmer

After you complete the field mappings, you need to set up the configuration tab in ThoughtFarmer.

1. In the ThoughtFarmer Admin Panel: Users & security section > Employee Directory Connector page. Click on [your Okta].
2. Under the Configuration tab, replace the placeholder text below with your Okta details so they can be used by the Windows service for the sync.
   
   
   
   {
    "oktaApiToken": "okta_api_token_here",
    "oktaApiUrl": "https://oktaapiurl",
    "oktaAppName": "okta_application_name_here"
   }
   
   
3. Follow the steps below to locate the above values in Okta.
   
   • Okta Api Token
     • In Okta, go to Security > API.
     • Click the Tokens tab.
     • Click Create Token, copy the token and paste it into ThoughtFarmer configuration.
   • Okta API Url
     • In Okta, go to Applications > [your app] > Sign On.
     • Click View Setup Instructions under Settings.
     • The Okta API URL is your "Identity Provider Single Sign-On URL" but only the "https://....com"; portion. This excludes everything after the ".com". 
   • Okta App Name
     • In Okta, go to Directory > Profile Editor.
     • Find your ThoughtFarmer application, and click Profile.
     • Copy the "Variable name" and paste it into ThoughtFarmer.
4. In ThoughtFarmer's Okta settings, click the Basic Information tab. If a user doesn't have a ThoughtFarmer account, but they are a member of the Okta group that ThoughtFarmer is syncing with, you can have their account automatically created after they log in without having to run a sync first. If you want this enabled, select User auto-creation.  

Test Okta sync and authentication

1. Go to the ThoughtFarmer Admin Panel: Users & security section > Employee Directory Connector page > [your Okta] > Synchronization Settings tab.
2. At the bottom, click Validate credentials. If the setup has been done properly, then it should validate successfully and show a green banner. You may have to refresh the page a few times until it succeeds. It should only take about a minute or so.
   
   
   
   
3. Check off the sync tasks that you want to run and click Synchronize Now. You can also set up a daily sync schedule so it'll run a sync automatically on a regular basis. We recommend running a Bulk Update users, so you can see which users are being pulled in without affecting your current user list.
   
   
    
4. Click the Synchronization Logs tab. Here, you can view the status of your sync. The status should say Success after it's done. This can take several minutes depending on how many users you are syncing. Click View details after the sync is done to see who got synced in and what info was pulled from Okta.
5. To test the login, create a temporary regular user with Admin privileges and then delete the regular user when you don't need it anymore. This account can serve as a backup access method in the event that Okta authentication encounters issues.
6. If you want the ThoughtFarmer user that you are currently logged in as to be an Okta user, you need to convert the account type to External. To do this:
   1. Go to the ThoughtFarmer Admin panel: Users & security section > User Management page.
   2. Search for the user.
   3. On the right of the user entry, click the gear icon and select Edit Account in the dropdown menu.
   4. Change the Account type to External, add the Okta username, choose your Okta store in the dropdown menu and click Save.
7. Repeat Step 6 for any other existing users in ThoughtFarmer that will come from Okta. If an Okta user doesn't have a ThoughtFarmer account yet, you can let the sync create the user. If you need help bulk changing many users at a time, please open a Support request on our Helpdesk.