Table of Contents
Summary
This guide walks you through setting up Single Sign-On (SSO) with Whistic using Okta as your Identity Provider. You'll configure the Whistic backend SAML app in Okta, set up SSO in Whistic, and create the required bookmark app for user access.
Important: Whistic supports SP-initiated sessions only, which is why both a backend SAML app and a bookmark app are required in Okta.
For general SSO concepts, role management options, and complete troubleshooting, see Using Whistic With SSO.
✅ Before You Begin
Requirements:
- Okta admin access
- Whistic Admin access
-
Decision on role management: Whistic-controlled or IDP-controlled
- Not sure which to choose? Review Using Whistic With SSO for guidance
Time to Complete: 15-20 minutes
⚙️ Step 1: Build Whistic Backend App in Okta
- In Okta, navigate to Applications > Applications > Browse App catalog
-
Search for Whistic and click
Add integration
-
Go to the General tab and click Edit
- Check Do not display application icon to users
- This prevents the app from appearing in users' Okta dashboards since they'll access Whistic via the bookmark
-
Navigate to the Sign on tab
- Ensure Application username format is set to Okta username or Email
- This is critical for proper user authentication
-
Copy the Metadata from the Sign on tab
- You'll need this for Step 2
🔧 Step 2: Configure SSO in Whistic
These steps must be completed by a Whistic Admin.
- In Whistic, navigate to the Settings drop-down in the upper right corner and select Company Settings
- Scroll down to the Single Sign-On Provider section
-
Paste your metadata from Okta into the provided box
-
Select your role source:
- Whistic (you'll manage permissions in Whistic User Management)
- IDP (you'll manage permissions through Okta groups)
⚠️ Warning: Setting role source to IDP before configuring roles in Okta can lock users out of Whistic. - Click Submit
-
Copy the three generated links that appear:
- SP Entity ID
- ACS / SSO URL
- Metadata URL
You'll use these links in Step 3.
(Example from Test Account)
🔗 Step 3: Complete Backend App Configuration
Return to your Okta Whistic backend app from Step 1.
- Click Edit on the Sign on tab
-
Update the following fields with the URLs from Step 2:
- SSO URL = ACS / SSO URL (from Whistic)
- SP Entity ID = SP Entity ID (from Whistic)
- Click Save
Your backend app configuration is now complete.
🔖 Step 4: Build Okta Bookmark App
A bookmark app is required because Whistic only supports SP-initiated sessions. This is how your users will access Whistic.
- In Okta, navigate to Applications > Applications
- Click Browse App Catalog
- Search for "Bookmark App" and click Add
-
Configure the bookmark:
-
URL:
companyName.whistic.com - Replace "companyName" with your actual company name in Whistic
- Application label: Whistic (or your preferred name)
-
URL:
- Click Done
- Assign users to the bookmark app so they can access it from their Okta dashboard
👥 Step 5: Set Up Roles (IDP-Controlled Only)
Skip this step if you selected Whistic-controlled roles in Step 2. For Whistic-controlled setup, see Sign Up Approval Modes.
If you selected IDP-controlled roles, configure role assignments in Okta:
Configure Group Attribute Statements
- In your Whistic backend app, click the Sign On tab
- Scroll down and click Edit
-
Under Group Attribute Statements, add a filter:
- Name: Role
- Filter: Starts with "Whistic"
-
Click Save
Create Okta Groups
- In Okta, go to Directory > Groups
- Click Add Group
-
Create groups using exact SSO attribute values (case-sensitive):
- WhisticAdmin (for Admin/Manager access)
- WhisticViewVendorAssessment (for viewing vendor assessments)
- WhisticRequestQuestionnaires (for requesting questionnaires)
- Assign users to the appropriate groups
whisticAdmin or
WhisticAdminA instead of WhisticAdmin will prevent
permissions from being passed to Whistic.
🧪 Step 6: Test Your Setup
Before enabling "SSO Required," thoroughly test your configuration.
-
Create a test user in Okta
- For IDP-controlled roles: Assign them to appropriate Whistic groups
- For Whistic-controlled roles: Ensure default roles are configured
-
Have the test user access Whistic:
- Click the bookmark app from their Okta dashboard
-
Or navigate directly to
companyName.whistic.com
-
Verify in Whistic User Management:
- Navigate to Admin Tools > User Management
- Confirm the user appears after their first login
- Check that the user is set as "Managed" and "Activated"
- Verify correct permissions were applied
-
Test permission updates:
- Whistic-controlled: Edit in User Management
- IDP-controlled: Update Okta group assignments, then have user log in again
Once testing is successful, you can enable SSO Required from Admin Tools > Company Settings > Single Sign-On Settings.
➕ Adding New Users
When SSO is set to required, new users are added through your IDP, not directly in Whistic.
Whistic-Controlled Roles
- Provision the user in Okta and assign them to the Whistic bookmark app
-
User visits the bookmark link (
companyName.whistic.com) - Upon authentication, their account is created automatically with default roles
- Adjust permissions in Admin Tools > User Management if needed
IDP-Controlled Roles
-
Provision the user in Okta and assign them to:
- The Whistic bookmark app
- Appropriate Whistic role groups (e.g., WhisticAdmin)
-
User visits the bookmark link (
companyName.whistic.com) - Upon authentication, their account is created with assigned permissions
- Update permissions by changing Okta group assignments (changes sync on next login)
FAQ
Stuck in a session-expired loop?
Ensure the Application username format in Okta is set to Email or Okta username (must include email address). This is the NameID-format setting. Fix this, regenerate your metadata, and update it in Whistic.
Receiving a "Page Requires Authentication" error and roles are not being passed through?
Verify your Okta groups are named exactly as our SSO attribute values
(case-sensitive). Example: WhisticAdmin works, but
whisticAdmin or WhisticAdminA will not work.
Why is a second Okta Bookmark app required?
Whistic only supports SP-initiated sessions. The bookmark app is the entry point for users to initiate their SSO session. See Okta's guide for more information on bookmark apps.
Do I need to configure Group Attribute Statements if I'm using Whistic-controlled roles?
No, Group Attribute Statements are only needed for IDP-controlled roles.
Why can't I edit users in User Management anymore?
If you selected IDP-controlled roles, user permissions must be managed through Okta groups. Contact Whistic Support if you need manual adjustments or want to switch to Whistic-controlled roles.
What happens if my SSO certificate expires?
You'll need to generate new metadata in Okta and provide it to Whistic Support or your CSM to update on our side.
Can I test SSO in a sandbox environment?
Whistic does not currently offer sandbox/test configurations. Test with a single user in your production environment before rolling out to all users.
Where can I find the complete list of SSO attribute values for roles?
See our User Permissions Guide for all available roles and their corresponding SSO attribute values.
I'm getting a 500 Internal Server Error when logging in.
This typically means:
- Users aren't accessing Whistic via the bookmark link
- Attribute mapping is incorrect in Okta
- The Whistic-provided links weren't applied correctly in Step 3
- Verify that the SP Entity ID and ACS URL match exactly what Whistic generated.
My users are being redirected to a non-SSO login page.
This can happen if SSO Required is not enabled, or if there's a mismatch in your configuration. Contact Whistic Support for assistance troubleshooting this issue.
For additional troubleshooting and general SSO questions, see Using Whistic With SSO.