Steps to Configure and Manage Okta SSO Provisioning with Consensus
Overview:
SSO provisioning for Okta allows your IDP to become the source of truth for all user information and application licensing.
Configuring the Integration
Step 1: Log in to Okta and Enable SCIM Provisioning for Consensus Application
If you don’t currently have a Consensus Application installed for use with OKta authentication (SAML 2.0), then you should first follow the steps outline in the article link below:
https://support.goconsensus.com/how-to-set-up-saml-2.0-sso-okta
If you do, then proceed to enable SCIM provisioning in your existing Consensus application.
Go to Application “General” settings > Edit > Select checkbox “Enable SCIM Provisioning”
Step 2: Create a new Okta API Token for Consensus
When logged into Okta as an administrator, select “Security” > “API” from the left hand menu.
Create a new token called “Consensus SSO Provisioning” or something that helps you identify its use properly, and copy the new token value.
Step 3: Login to Consensus and Configure SSO Provisioning
Login to Consensus and then visit the SSO configuration page by clicking the gear icon, selecting “Integrations” and then navigating to the “SSO” tab.
Scroll down the bottom of the page, and you should see a new section available called “SSO Provisioning.”
*Important Note - if the fields are greyed out and you are not able to input any text, this means the feature has not been enabled as a permission for your account. Please contact your CS representative to assist.
Okta Token - Insert the generated token from Okta
- Paste in the token you just copied from Okta, into the “Okta Token” field.
Okta URL - Insert URL from Okta
- Visit your Okta account and copy/pase the first part of the URL
Click ‘Check Status’. The red text that says “SSO provisioning not available” to the right of SSO Provisioning should turn green and say “SSO provisioning available”.
Click ‘Save’ at the bottom of the page
A green pop up will say “SSO settings have been updated”
Step 4: Configuring SCIM Connection in Okta
If you didn’t enabled SCIM provisioning from Step #1, please do this now inside of the Consensus Okta application.
After provisioning is enabled, from Consensus web app go to Settings > Integrations > SSO > scroll down to SSO Provisioning. You will see a SCIM connector base URL and a SCIM Authorization Header.
Keep this screen open. Then, go into Okta > Applications > Consensus > Provisioning > click ‘Edit’ and paste the SCIM connector base URL that you obtained from Consensus.
- For SCIM Connector base URL, paste the SCIM Connector base URL value from Consensus.
- For ‘Unique identifier field for users’, insert email.
- For Supported Provisioning Actions, check the first 3 checkboxes
- Import New Users and Profile Updates
- Push New Users
- Push Profile Update
- For Authentication Mode select HTTP Header
- For Authorization, paset the SCIM Authorization Header value from Consensus.
Additional SCIM Settings:
Once you’ve enabled SCIM and setup/tested the connection with Consensus, please make sure you duplicate the below settings for both the “To Okta” and “To App” configuration pages:
A Note on Custom Application Attributes
After configuring SCIM connection you will now see “Consensus Role(s)” and “Consensus Group” in the Profile Editor as new custom attributes created for the Consensus Application.
Here’s an example of Consensus Role(s). All values will be brought over from Consensus to Okta for use in User assignment to your application.
Step 5: Importing Users from Consensus
It is best practice to run an initial import process from Consensus to Okta once you’ve finished setting up the integration.
Visit the “Import” tab from within the Consensus application and select “Import Now.”
This will import all existing users from your Consensus account and match them using their primary email address to any users/people in your Okta account.
If a user is matched via their email address, they will automatically be assigned to the application and information for assigned Groups and Roles will be populated inside of the custom attributes for the user’s profile.
Managing the Integration
Creating and Updating Users
- Once SSO Provisioning in setup and enabled with Consensus, you must make sure that all new users are assigned access to Consensus from within Okta.
- From the user’s profile in Okta, choose “Assign Applications.”
- Choose the Consensus Application
- Assign to proper Role and Group values
You can also assign users to the app from the “Assignments” tab inside of the application. Choose “Assign to People” and you will be prompted with a similar screen to select users and individually assign them.
To view the last time a user was synced from Okta to Consensus, we've also added a new "Last SSO Sync" column on the users table in Consensus. 
Unassigning Users
- If a user leaves your company or no longer needs to have access to Consensus, you can un-assign them from the application in Okta.
- This action will deactivate them in Consensus and instead of deleting their user information altogether, will simply update their status to “Disabled” instead of “Enabled.”
You can visit the “Assignments” tab on the Consensus Application within Okta, and simply select the “X” next to a users name to unassign them from the app.
Other Key Aspects About The Integration:
- You must have SCIM settings enabled to create/update users from Okta into Consensus. If disabled, new and updated user details will not be sent to Consensus.
- Initially assigning user will provide an error message IF the CREATE action is not enabled in SCIM to find/sync new users.
- Changes made while the SCIM sync settings are disabled will not be queued and sent to Consensus later/in bulk.
- If you try to assign an email address to a user that already exists in Consensus, this error will appear after attempted sync.
- Email must be unique
- If you need to add a New Roles or Groups, you should add this in the Consensus application first, and then sync it in using the Import functionality from the application.
- A note on creating Admin users from Okta.
Admin users
- Currently, you can not create or update an Admin user role from Okta right now.
- These users must be initially imported/matched to your application.
- If you attempt to make an update to this level of role, you’ll see this error.
Reaching License Limits in Consensus
User limit has been reached - not enough licenses in Consensus
If you have provisioned more users to Conesnsus than you have available licenses for, you’ll begin to see errors within Okta for each user assignment.
-
