Documentation

Okta

* If you already have active users in ThoughtFarmer and you're looking to switch them over to Okta, please contact ThoughtFarmer first.

Okta Setup

The main parts to the setup are below. If you're a cloud client, please wait for us to set up your custom url first before you set 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

Set up authentication

  1. Within Okta browse to the Admin section > Applications. Add a new application. Create a new application integration. Choose the sign-on method as SAML 2.0.

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

  2. SAML Settings 
    Replace https://tfurl.com below with the url of your ThoughtFarmer site. 

saml%20settings.png

  1. Click next and finish.

  2. This will bring you to the below page 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. 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. 

    assign.png

  3. Then, you will need the SAML setup instructions. Click View Setup Instructions. This will open up the page with the information that you will need to setup a new Login Provider within ThoughtFarmer.

    setup%20instructions.png
     
  4. Log into ThoughtFarmer and add a new login provider by going to Admin Panel > Login Provider. Then add a new login provider under "External Providers". Select "Custom SAML".
Fill in the field names like so, using values from Okta's "View Setup Instructions" (see previous step):
  • 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 "Employee Directory Connector Setup" 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: "Want SAML Response Signed" and "Want Assertion Signed: checked
  • Issuer URL / Name: Okta's "Identity Provider Issuer"

    okta%20login%20provider%20edited.png

User sync setup

ThoughtFarmer also has a tool 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.

This tool is independent of the main ThoughtFarmer website and runs as a Windows service. Please contact ThoughtFarmer support to obtain access to this tool. 

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

  1. Go to Admin Panel > Employee Directory Connector > Add New external user store
  2. Select the type "Other", give it a name (ex: "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'll need to convert the account type to "External". Go to Admin Panel > User Management. Search for the user. On the right, click the gear icon > Edit Account. Change the type to "External", add the Azure username, choose your Okta in the drop down and save. 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, contact ThoughtFarmer. 


     
  4. Go back to Admin Panel > Employee Directory Connector > [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 end.

Set up field mappings in ThoughtFarmer

This is where you can configure which Okta profile fields should sync into 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. 
For example:
 

Set up field mappings in Okta

For each field mapping in ThoughtFarmer, you'll need to set them up in Okta too.
 
  1. In Okta, go to Directory > Profile Editor
  2. Find your ThoughtFarmer application, 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 completed the field mappings, you'll need to set up the configuration tab in ThoughtFarmer.
 
  1. In ThoughtFarmer, 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.
    config.PNG
    {
     "oktaApiToken": "okta_api_token_here",
     "oktaApiUrl": "https://oktaapiurl",
     "oktaAppName": "okta_application_name_here"
    }
  2. 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" and copy the token and paste into ThoughtFarmer
    • 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, click "Profile"
      • Copy the "Variable name"  and paste into ThoughtFarmer
  3. In ThoughtFarmer's Okta settings, click the Basic Information tab. If a user doesn't have a ThoughtFarmer account, but they're a member of the Okta group that ThoughtFarmer is syncing with, you can have their account be automatically created after they log in without having to run a sync first. If you want this enabled, check off "User auto-creation".  

Test Okta sync and authentication

After ThoughtFarmer Support has helped your install the Windows service and you've configured everything listed above, then you're ready to test syncing users from Okta into ThoughtFarmer.
  1. Go to Admin Panel > Employee Directory Connector > [your Okta] > Synchronization Settings.
  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.


     
  4. Click the Synchronization Logs tab. Here, you can view the status of your sync. Flip back and forth between this tab and another tab for the sync status to update. The status should say "Success" after it's done. This can take several minutes depending on how many users you're syncing in. 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, logout of ThoughtFarmer. If you now have two identity providers associated with your ThoughtFarmer url you should see a screen that asks you to choose the provider. Select the Okta provider. This will trigger the start of the authentication flow. Log into Okta and the user will be redirected back to ThoughtFarmer and logged in as the matching user. It is important that the userName sent in the Okta SAML negotiation matches to a user setup in the ThoughtFarmer system.