Before we start off, here are a couple of reminders to ensure that you will be able to successfully enable Okta SSO:
- You’ll need to have an Okta account to setup the Okta SSO in Pequity.
- You must be an Okta administrator to make application configurations in Okta.
- You must be a Pequity administrator to make site-wide configurations in Pequity. This is something the Pequity team will handle on your behalf.
Configure Pequity Application in Okta
In Okta, navigate to Applications > Applications and select Create App Integration.
Select the SAML 2.0 for the Sign-in method. Select Next.
In the General Settings, add “Pequity” as the App name. You can download the App logo here. Leave the App visibility selections unchecked, and select Next to continue.
In Configure SAML, fill out the SAML Settings.
Please note, as stated below, “company” in the URLs throughout this document should be replaced with the company name of your instance. For example “Walmart.pequity.app,” not “Company.pequity.app”
- Single sign on URL will be https://company.pequity.app/api/saml2/acs/ where “company” is your unique Pequity subdomain.
- Audience URI (SP Entity ID) will be https://company.pequity.app/api/saml2/metadata where “company” is your unique Pequity subdomain.
|📣 Please note that this URI URL should NOT have a trailing slash. This is intentional. If a trailing slash is added to this link, the setup will not work.|
- Default RelayState will be left blank.
- Name ID format will be EmailAddress.
- Application username will be Okta Username.
- Update application username on will be Create and update.
Next, add 3 Attribute Statements (optional). This will map Pequity user data to Okta user data.
- first_name will be attributed to the value user.firstName.
- last_name will be attributed to the value user.lastName.
- email will be attributed to the value user.email.
Leave the Group Attribute Statements (optional) blank. We’ll walk through how to add Pequity to specific user groups in the next section.
Next, select Preview SAML Assertion. Save this file and send it to your Pequity Customer Success Manager and Pequity Technical Project Manager.
Finally, in the Feedback section, select that you are an Okta customer, scroll to the bottom of the page and select Finish.
Create a Pequity user group in Okta
This is optional if you’d like to restrict Pequity access to specific users in a group.
In Okta, navigate to Directory > Groups and select Add Group.
Enter the group name and description (we recommend adding the term “Pequity” to the name and description), and select Save.
Within the Pequity group, navigate to the Applications tab and select Assign applications.
Find the Pequity application and select Assign and then Done.
Then, navigate to the People tab in the Pequity group and select people to assign to the group.
📣 Important information on User Access:
- If an existing user logs into Pequity using Okta with an email that does not match their Pequity user email, they will be created as a new user and their Pequity permissions will not transfer.
- For new users logging into Pequity but granted access to Pequity in Okta, they will default to “guests” until a company admin specifies their permissions.
Configure Okta in Pequity
Navigate to Applications and select Pequity. On the General tab, select Edit within SAML Settings.
Select Next in the General Settings to land on Configure SAML. On the far-right of the page, Select Download Okta Certificate.
Then, scroll down to the section titled Preview the SAML assertion generated from the information above, select Preview SAML Assertion.
Save both the Okta Certificate as well the SAML Assertion.
Please also navigate to the Sign On tab. Scroll down until you see the link for "identity provider metadata. Once you click the "identity provider metadata" link, it will open up a new tab with the code. Please download this code to XML. This has the entity ID in it which is required to finalize setup.
Send the Okta Certificate, SAML Assertion, and Identity Provider Metadata to your Pequity Customer Success Manager and Pequity Technical Project Manager to finalize the Okta setup within Pequity.
Congratulations! You’ve setup Okta with Pequity 🎉
Logging into Pequity with SSO
There are a few possible outcomes after a user logs into Pequity. Below are the possible cases you will run into:
|User was added/has logged in to Pequity prior to SSO setup and has access to the Pequity app in your company's Okta SSO settings||After logging in via SSO, they will be matched to their existing user in Pequity and retain the same permissions|
|User was not added to Pequity prior to SSO setup but has access to the Pequity app in your company's Okta SSO settings||After logging in via SSO, they will default to a "guest" user type in Pequity. A company admin will need to specify their user type and permissions in the Pequity tool to change this.|
|User was added to Pequity prior to SSO setup but does not have access to the Pequity app in your company's Okta SSO settings||User will be unable to login and see a 403 error page that the "Service is not configured for this user." They will need to be added to your company's Okta SSO settings to login.|
|User was not added prior to SSO setup and does not have access to the Pequity app in your company's Okta SSO settings||User will be unable to login and see a 403 error page that the "Service is not configured for this user." They will need to be added to your company's Okta SSO settings to login.|
🎉 All done! Questions?
We’re here to help! Feel free to reach out to us at firstname.lastname@example.org.