Okta

ThoughtFarmer integrates with Okta for single sign-on (SSO) and user management. People sign in to ThoughtFarmer with their Okta account, and their profile information syncs automatically from Okta to ThoughtFarmer.

Overview

Do these steps in this order:

1. Create the ThoughtFarmer app in Okta
2. Set up user sync so ThoughtFarmer accounts are created from Okta. A person must have a ThoughtFarmer account before they can sign in with Okta.
3. Set up the login provider so people can sign in with Okta
4. Test the sync and sign-in

Step 1: Create the ThoughtFarmer app in Okta

1. In the Okta Admin Console, go to Applications and Resources > Applications and click Create App Integration.
2. Select SAML 2.0 and click Next.
3. Under General Settings, enter an App name (for example, ThoughtFarmer), optionally upload a logo, and click Next.

4. Under SAML Settings, fill in:

   • Single sign-on URL: ThoughtFarmer's sign-in URL. Replace yourcompany.thoughtfarmer.com with your ThoughtFarmer site address:
     https://yourcompany.thoughtfarmer.com/auth/saml/assertionconsumerservice
   • Use this for Recipient URL and Destination URL: leave this checked.
   • Audience URI (SP Entity ID): type exactly thoughtfarmer

   

5. Check that Name ID format is Unspecified and Application username is Okta username. These are the defaults.
6. Click Next, then Finish.
7. Open the app's Assignments tab, click Assign > Assign to People (or Assign to Groups), and assign everyone who should have access to ThoughtFarmer.

Where to find your Okta values

Once the app is created, Okta shows the values you'll need in Steps 2 and 3. They're all in one place:

1. In Okta, go to Applications and Resources > Applications and open your ThoughtFarmer app.
2. Click the Sign On tab.
3. Under Metadata details, click More details.
4. Use the Copy button next to each value. For the certificate, use Download.

You can also click View SAML setup instructions on the right side of the Sign On tab. It shows the same values with older labels (for example, Identity Provider Single Sign-On URL instead of Sign on URL).

The examples use yourcompany and made-up IDs. Your values will be different. Always copy them from Okta.

Step 2: Set up user sync

ThoughtFarmer's Employee Directory Connector syncs user data from Okta on a schedule. It can:

• Create and deactivate ThoughtFarmer accounts automatically.
• Update profiles from Okta data.
• Sync group and security group membership from Okta groups.

2a. Add profile attributes to the app in Okta

A new Okta app's profile only contains userName. If you don't add first name, last name and email, the sync sends blank values and ThoughtFarmer can't create the accounts.

1. In Okta, go to Directory > Profile Editor and click your ThoughtFarmer app's profile (for example, ThoughtFarmer User). Don't use User (default).
2. Click + Add Attribute.

3. Fill in the form and click Save. Repeat for each attribute.

   Data type	Display name	Variable name	Attribute type
   string	First name	firstName	Personal
   string	Last name	lastName	Personal
   string	Email	email	Personal

   Leave the other fields at their defaults. Type the variable names exactly, including upper and lower case.

   

4. To sync more profile fields, add an attribute for each one. Use the ThoughtFarmer field name with spaces and special characters removed. For supported fields and syntax, see Identity provider field mappings. Okta doesn't support syncing profile images.

2b. Map Okta's values to the app attributes

1. On the same page, click Mappings.
2. Click the Okta User to [your app] tab (for example, Okta User to ThoughtFarmer). Don't use the other direction.
3. For each attribute, pick the matching Okta value on the left:
   • user.firstName → firstName
   • user.lastName → lastName
   • user.email → email

4. Click the small ▾ next to each arrow and choose Apply mapping on user create and update. The arrow turns green.

   

   Note: New mappings start as Apply mapping on user create only (a yellow arrow with a "1"). With that setting, people who are already assigned to the app never get the values, and the sync fails with "FirstName cannot be empty".

5. Click Save Mappings. If Okta asks, click Apply updates now.
6. To check the mapping worked, go to the app's Assignments tab and click the pencil next to a user. First Name, Last Name and Email should be filled in.

2c. Create an Okta API token

1. In Okta, go to Security > API, open the Tokens tab, and click Create token.

2. Enter a name (for example, ThoughtFarmer). Under API calls made with this token must originate from, select Any IP. Click Create token.

   

3. Copy the token and keep it somewhere safe. Okta only shows it once.

2d. Create the Okta store in ThoughtFarmer

1. In ThoughtFarmer, go to Admin panel > Users & security > Employee directory connector.
2. Click Add new external user store.
3. Enter a Name (for example, Okta), select Okta as the Type, and click Save.

4. Open the store's Configuration tab and replace the values in the JSON with your own:

   {
     "oktaApiToken": "okta_api_token_here",
     "oktaApiUrl": "https://yourcompany.okta.com",
     "oktaAppName": "okta_application_name_here"
   }

   Setting	What to enter
   oktaApiToken	The API token from step 2c.
   oktaApiUrl	Your Okta address: the Sign out URL from More details. For example, https://yourcompany.okta.com. Don't use your -admin address.
   oktaAppName	The part of the Sign on URL between /app/ and the next /. In https://yourcompany.okta.com/app/yourcompany_thoughtfarmer_1/exk1a2b3c4d5e6f7g8h9/sso/saml, it's yourcompany_thoughtfarmer_1. Don't include the ID that comes after it.

   Keep the quotation marks around each value. Click Save configuration.

   

5. Open the Synchronization Settings tab and click Validate credentials. Refresh the page and check that it says SUCCESS.
   

2e. Check the field mappings in ThoughtFarmer

Open the store's Field Mappings tab. Each External store field must exactly match a Variable name in the Okta app profile from step 2a, including upper and lower case. To sync more fields, click Add.

2f. Run the sync

1. On the Synchronization Settings tab, under On-demand synchronization, check the tasks you want to run. To create the accounts, check Bulk create users. Click Synchronize now.

   

2. Open the Synchronization Logs tab. The status shows SUCCESS when the sync is done. This can take several minutes for a large number of users. Click view details to see which users were synced and what data came from Okta.
3. Under Daily synchronization, click Create one now to sync automatically every day. This also keeps the Okta API token from expiring.

Step 3: Set up the login provider

1. In ThoughtFarmer, go to Admin panel > Users & security > Login provider.
2. Under External providers, click Add new, select Custom SAML, and click Next.
3. Under Content, enter a Company sign in name (for example, Okta sign in). If your site has more than one login provider, people see this name on the sign-in page.

4. Under Settings, fill in both addresses. The https:// is already shown in front of each box, so leave it off what you type.

   • Host name: your ThoughtFarmer site address, for example yourcompany.thoughtfarmer.com
   • Login Provider complete hostname: Okta's Sign on URL from More details (the one ending in /sso/saml)

   

   Note: Don't use the Single Sign On URL from the Okta app's General tab here. That's ThoughtFarmer's own address. If you use it, signing in from the Okta dashboard works, but signing in from ThoughtFarmer shows "Sorry, you don't have access".

5. Under Custom SAML configuration, set External user store configuration to the Okta store you created in step 2d.

6. Under Advanced SAML options:

   • Single sign on binding type: HTTP Redirect
   • Identity provider sign out URL: copy the Sign out URL from More details and add /login/signout to the end. For example:
     https://yourcompany.okta.com → https://yourcompany.okta.com/login/signout
     This signs people out of their whole Okta session, not just ThoughtFarmer. It works with Okta's SAML Single Logout setting left disabled.
   • Single sign out binding type: HTTP Redirect
   • Certificate details: in More details, click Download next to Signing Certificate. Open the downloaded file in a text editor such as Notepad, copy everything, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, and paste it here.

   

   Note: If the Okta Sign On tab lists more than one certificate under SAML Signing Certificates (for example, SHA-1 and SHA-2), use the one with the status Active.

7. Under Configuration options, check Want SAML response signed and Want assertion signed.
8. Under Custom identity provider name, paste Okta's Issuer from More details into Issuer URL / Name. It must be an exact copy. It starts with http:// (not https://) and has no / at the end.

9. Click Save.

   

Step 4: Test

Keep a backup admin account

Before you switch anyone to Okta, add a regular user with Admin privileges. If Okta sign-in has a problem, you can still sign in with this account. Delete it when you no longer need it.

Switch existing users to Okta

Users created by the sync are already set up. For people who already had a ThoughtFarmer account:

1. Go to Admin panel > Users & security > User management.
2. Find the user, click ⋯ at the end of their row, and click Edit account.
3. Under Account type, select External User.
4. Under Employee Directory Connector configuration, select your Okta store. Enter the person's Okta username in Username and click Load account information.

5. Click Save.

   

Repeat for each user. To switch a large number of users at once, submit a Support request.

Test sign-in

1. Go to your ThoughtFarmer site and sign in with Okta. If your site has more than one login provider, choose the one you named in step 3.
2. You can also test from Okta. On the app's General tab, copy the Embed Link under App Embed Link and open it in your browser. This is useful because Okta admins are often sent to the Admin Console instead of the Okta dashboard, where the app tile would be.

Troubleshooting

The sync fails with "FirstName cannot be empty" or "LastName cannot be empty"

Okta is sending blank values. In Okta, open the app's Assignments tab and click the pencil next to the user:

• If First Name, Last Name and Email are blank, check that the attributes exist in the app profile (step 2a) and that each mapping arrow is green (step 2b). After you fix the mapping, unassign the user and assign them again if the values still don't appear.
• If the values are filled in, check that the ThoughtFarmer Field Mappings tab uses the same names (step 2e).

"Sorry, you don't have access" after signing in to Okta

• Signing in from Okta works, but signing in from ThoughtFarmer fails: the Login Provider complete hostname is wrong. It must be Okta's Sign on URL (ending in /sso/saml), not ThoughtFarmer's address (step 3).
• Both fail: check these, in order:
  • The user has a ThoughtFarmer account in the Okta store. Check the Synchronization Logs.
  • The login provider's External user store configuration is set to the Okta store.
  • The Issuer URL / Name matches Okta's Issuer exactly.
  • Okta's audience matches ThoughtFarmer's SAML name. On the app's General tab, Okta shows the audience as Audience Restriction (when you click Edit, the same field is called Audience URI (SP Entity ID)). It must match ThoughtFarmer's saml.service.provider.name configuration setting, which is thoughtfarmer by default.

The sync stopped working

The Okta API token may have expired or been revoked. This happens when the token isn't used for 30 days, or when the Okta account that created it is deactivated. Create a new token (step 2c), update oktaApiToken on the store's Configuration tab, and click Validate credentials.