Note:This article provides steps on how to initially set up Okta's SSO solution with Simpplr, as well as how to provision users from Okta to Simpplr. For information on how to sync attributes from Okta to Simpplr, click here.
To complete this setup, you'll need your company's Okta admin user, as well as someone with Salesforce Administrator access. We highly recommend having someone with Salesforce and Okta experience completing this setup, as some steps can get a bit technical.
Table of Contents
Add the Salesforce Application in Okta
- Log in to Okta with Admin credentials and click on the Admin button in the top right to open the admin console panel.
- Navigate to Applications > Applications. Then click Browse App Catalog.
- Search for Salesforce.com and select it from the list of results. Click Add integration.
- Set your Application label if you wish to change it from Salesforce.com and make sure Production is chosen in Instance Type.
- In the Custom Domain field, add your company domain. For example, if your url is https://simpplr.my.salesforce.com, input simpplr to the Custom Domain field.
- From the next tab Sign-on options, select SAML 2.0.
- In the Default Relay State field, enter your Simpplr app's url. For example, if your Simpplr app url is https://companyname--simpplr.vf.force.com/apex/simpplr__app?u=/, that's what you'll enter in the Default Relay State field. Example shown below.
- Scroll down to the SAML 2.0 login instructions. Right click on the Identity Provider metadata and click Save link as (MacOS users will show slightly different options here). Save the link to your computer.
- In Login URL, enter the Login URL. This is your domain URL in Salesforce. It should look similar to https://mydomain.my.salesforce.com (replace mydomain with your custom domain name).
- In Credentials Details, select the Application username format as Custom. In the given field, add the expression: user.email+'.simpplr' (this is used to make the username unique). Once finished, click Done.
- Change the "Update application username on" setting to "Create and update."
Enable and Deploy My Domain on your Salesforce Org
The Salesforce My Domain feature allows you to select a custom domain name for your application. A My Domain URL looks like https://customer.my.salesforce.com.
- In your Salesforce Org, click Setup. Then in the Quick Find box, type My Domain. Choose My Domain from the results.
- Type in your requested domain name and click Check Availability. If your name is already taken, choose a different one.
- Click Save.
Configure SSO in Salesforce
- Log in to Salesforce with the same administrator username and password used for User Management settings in Okta.
- Navigate to Setup and type Single sign on into the Quick Find Box. Then choose Single Sign-On Settings.
- Click Edit and check the SAML Enabled box, then click Save.
- In the list at the bottom of the page, select New to add a new SAML Single Sign-On configuration.
- A new page will open. Choose New from Metadata File and upload the file you created in Okta. Then click Create.
- In the Quick Find box to the left, type in My Domain and click.
- From here, scroll down to Authentication Configuration and click Edit.
- In the Authentication Service section, by default, Login Form is checked. Uncheck it and choose the unique Okta value that is showing. Then click Save.
Enable User Provisioning in Okta
For controlling user access and ensuring system continuity if an admin leaves your company, Simpplr highly recommends creating a new administrator account in Salesforce. This should be a service account, not tied to any one user's email address. You will use this account’s username and password to configure the Salesforce app in Okta. When you create an administrator account, Salesforce will provide you with a token.
Note:Every time you reset this account’s password, Salesforce will provide you with a new token, and you need to edit the Salesforce app’s Provisioning settings in Okta using the new password/token as described below. We recommend keeping this password static.
- In Okta, from your Applications menu in your Salesforce application set up earlier, go to the Provisioning tab and choose Configure API Integration. Then select Enable API Integration.
Scroll down to Step 5 below for instructions on newer Okta tenants.
For older Okta tenants, you'll need to input the Salesforce admin's username, along with that user's password and a security token sent to the email address the admin is tied to. To get the token, head to Salesforce and from your user profile, choose My Settings, then type "reset" into the Quick Find box and choose Reset My Security Token. Follow the prompts to have a new token sent to your admin email address.
Head back to Okta and paste all the information with no spaces or other characters.
- Once input, click Test API Credentials. If successful, a verification message appears at the top of the screen. Select To App in the left panel, then enable the provisioning features you want to connect to Simpplr.
- For newer Okta tenants, the Username and Password + Token fields have changed to OAuth Consumer Key: Consumer Key from your Salesforce OAuth settings and OAuth Consumer Secret: Consumer Secret from your Salesforce OAuth settings. For more on how to gather this information, complete the steps in this article.
Once the security info has been authenticated, you should see a screen similar to this:
Select parameters such as Create user, Update User Attributes, and Deactivate Users. We recommend enabling each parameter from the list.
Note:Okta recommends managing users completely from Okta, which is why we're selecting all the parameters above.
- Click Save. You can now assign people to the app (if needed) and finish the application setup.
Running a user provisioning log
For detailed instructions on running a user provisioning log from Okta, check out this article from Okta's Help Center!
Control User Access
If you don't populate timezones for your users in Okta, the timezone will be set to Pacific time by default within Salesforce.
Create three groups in Okta or Active Directory (if you are syncing groups from Active Directory). The group name should be similar to Simpplr_User, Simpplr_App_Manager and Simpplr_Admin. You'll use these groups to control user access on Simpplr.
- Log in to the Okta Admin page.
- Navigate to Application > Application and search for your Salesforce org. In the results, click the Application name.
- Click on Assignments, then Assign on the left side of the screen. Choose Assign to Groups.
- Search for the group called Simpplr Admins and click Assign.
Select the Profile System Administrator and select all Permission Sets that start with Simpplr. Once finished, click Save. Then go back.
- Search for the other group called Simpplr Users and click Assign.
Select the Profile Simpplr User and assign only the Permission Simpplr_User. Then click Save and go back.
- Click Done.
- Now once more, create a Simpplr User group for the Simpplr_App_Manager role. Select all permissions that start with Simpplr. Then Done.
- You should see something similar to the image below.
- Now head to your Directory > Groups to assign users to these groups. You can assign everyone in the org to the Simpplr Users group and choose the users you want for Simpplr Admin.