Overview
Set up and maintain Okta as your identity provider (IdP) for login to ZenGRC.
Prerequisites
Administrator access to ZenGRC
Administrator access to Okta
Step by Step Instructions
Initial Setup and Configuration
This set of instructions is intended to be completed first and includes steps on the initial configuration.
1. Sign in to Okta
Sign in to Okta as an administrator.
2. Reviewing the Dashboard
Depending on the setup of the Okta for your company, this should take you to the main dashboard for Okta.
3. Go to Applications
Expand the Applications menu and select Applications
Okta documentation on Build a Single Sign-On (SSO) integration is included if needed for additional information
4. Create the SSO Application in Okta
Select Create App Integration to begin creating the integration between ZenGRC and Okta
5. Setting up for SAML 2.0
Select the SAML 2.0 from the options listed and click Next
6. Name the Application for SSO
Enter the App Name for the integration as ZenGRC and click Next
If you wish to add a logo for the Application and not show the gear icon (highlighted with the green box). Email Support at [email protected] and the image file can be sent to you.
Do not select any of the App Visibility option to avoid application from not displaying
7. Input the Metadata from ZenGRC
Enter the service provider metadata collected from ZenGRC into Okta.
If you happen to have administrative access to both Okta and ZenGRC, then you can copy-and-paste the values directly from ZenGRC into Okta as shown.
If you are an Okta administrator but do not have administrative access to ZenGRC, then copy-and-paste these settings from the text file provided to you by the ZenGRC administrator.
IMPORTANT
If Okta is configured for users to utilize an actual user account and not an email address to log into the network applications, the flag for the Application Username format under SAML Settings will need to be updated to email (Okta defaults to username).
Click Save.
8. Configure Advanced Settings
Click Show Advanced Settings in Okta.
9. Logout Settings
Next to Enable Single Logout, select the checkbox beside Allow application to initiate Single Logout.
10. Adding Additional Metadata from ZenGRC
In the Single Logout URL text box, paste the value from ZenGRC Single Logout URL. The string will end with "single_logout_service."
11. Adding Final Metadata from ZenGRC
In the SP Issuer field, paste the value again from ZenGRC Entity ID. The string will end with "metadata."
12. Load ZenGRC Signature Certificate
Click Browse next to Signature Certificate and select the certificate that your ZenGRC administrator should have provided.
Click Upload Certificate.
13. Attribute Setup
Under Attribute Statements, create two custom parameters as follows:
Add email to the Name field with a value of user.email
Add nickname to the Name field with a value of user.fullName
14. Configuration Complete
Scroll down to the bottom of the screen and click Next.
15. Feedback
Select the option I’m an Okta Customer Adding an Internal App to be able to skip the remaining questions on this screen.
16. Finishing the Configuration
Scroll down to the bottom and select Finish.
17. Download Okta SAML Certificate
From the main screen where the ZenGRC application was just created, be sure you have Sign On tab selected.
Scroll down till you see SAML Signing Certificates and select the drop-down from Actions and select Download Certificate.
Be sure this certificate is given to the ZenGRC Administrator, as it will be required to complete the integration between ZenGRC and Okta.
18. Add Users to the Application for SSO
The final step in Okta is to add users to the application that will require access to ZenGRC using the SSO Login option.
Users are added under the Assignments tab from the main screen where the ZenGRC application was just created.
The following steps MUST be completed in ZenGRC by the ZenGRC Administrator to complete the integration
19. Import the Okta SAML Certificate into ZenGRC
The certificate downloaded from Okta needs to be imported into ZenGRC by the ZenGRC Administrator.
From ZenGRC, go to Settings > Authentication.
Click the Edit Settings for the SAML 2.0 Authentication.
Scroll down to the bottom and select Browse to locate the file provided by the Okta Administrator.
Click Load IdP Metadata to load the certificate selected above.
The bottom fields, which should be blank for first-time setup, will populate automatically once the above file is imported with the Okta metadata information. This completes the integration handshake between the two systems.
Scroll down to the bottom and click Next
Scroll down to the bottom again and click Next to exit the settings screen
20. Enable SAML 2.0 and Debug
Enable the SAML 2.0 option on the Authentication Settings screen
Enable the Debug Mode on the Authentication Settings screen
SAML Groups Configuration
Contact Customer Support at [email protected] or via the Intercom Messenger to have SAML Groups enabled in your instance prior to following these steps.
1. Access Groups in ZenGRC
Log into ZenGRC and go to Settings > Authentication.
Click the option to Edit/Manage Groups.
2. Create Groups in ZenGRC for User Access
Enter a name for the four individual access groups (these will need to be duplicated in Okta as well).
Note: The groups can be named as you wish, but we recommend referencing the access level in it to avoid confusion.
Check the box for Enable group-based role handling in ZenGRC.
Click Save SAML Settings.
3. Log into Okta as an Administrator
Log into Okta as the Administrator.
4. Go to the User Interface
Click Developer Console in the top-left corner of Okta and select Classic UI.
5. Reviewing the Dashboard
Depending on the setup of the Okta for your company, this should take you to the main dashboard for Okta.
6. Go to Groups
Expand the Directory menu and select Groups.
7. Adding Groups to Okta
Select Add Group.
8. Setting Up the Group
Enter the name of the group exactly as it is in ZenGRC.
Enter a description (optional).
Click Save.
Do this step for each of the groups configured in ZenGRC. There should be 4 total (Administrator, Editor, Reader, Contributor). There is no group for No Access.
9. Confirm All Groups
Once all the groups have been added to Okta, verify they appear as expected and the names match exactly to what is in ZenGRC.
If you need to edit anything, select the title you want to edit and in the following screen click the Profile option to edit the name or description.
10. Add Users to the Groups
Select the group access name to add users to.
The first tab is labeled People.
Click the Assign People option to access the screen of adding users.
11. Selecting Users for Each Group
Scroll through the list of Not Members and click the users to add to the Members column who should be with this access level.
OR
Use the search option to find users and click on the name to add them to the Members column.
Click Save when done selecting users.
12. Adding Application to Group
The second tab is labeled Applications.
Click the Assign Applications option to access the screen of adding applications.
13. Selecting Application for Each Group
Use the Search field to find the application ZenGRC.
Click the Assign option next to the application.
Click Done to save.
14. Return to Groups
Click the Back to Groups option to go back to the main Groups screen to work on the next group.
Repeat steps 10 through 14 till all Group Names have been configured with Users and Application.
15. Verify Group Names Configured
Validate from the Group main menu that all 4 group names have People assigned and 1 Application assigned.
16. Go to Application
From the menu on the left-hand side, expand the Applications option.
Select Applications.
17. Select the ZenGRC Application
Use the Search field to find the ZenGRC application.
Click the application name to select it.
18. Change in the General Tab
Select General from the tab just below the title of the Application.
19. Editing the SAML Settings
Click the Edit option to the right-hand side of the SAML Settings.
20. Adding Group Attribute
Click Next in the General Settings setup.
In the SAML Settings screen, scroll down till Group Attribute Statements (optional) can be seen.
Enter the following parameters:
Add groups to the Name field.
Add .* to the field to the right of Matches regex.
Scroll down some more and click Next.
Scroll down to the bottom of the page and click Finish.
21. Change in the Assignments Tab
At the main Application screen, select the Assignments tab.
22. Remove the Individual Users
With the Groups added to the application, the Individual users need to be converted to the groups to avoid access issues.
23. Converting the Users
Using the drop-down menu, select the Convert All Assignments option. This will convert the Individual users that have been assigned to their respective Groups.
For users already logged into ZenGRC, this will not affect them. However, anyone trying to log in during the conversion may experience an issue as they are updated to the group they are assigned to. Once the conversion is done users should be able to log in normally.
24. Warning Message
When selecting the Convert All Assignments, a warning message will pop up. Select the Convert All option to start the process.
25. Validate the User Types
Once the conversion is complete, refresh the screen.
Validate the Type of user column to be sure all show Group. Any user who still shows as an Individual was not assigned to a Group in steps 10 and 11. It is best at this time to delete the user from the application using the X to the right-hand side of their name.
Then go back to the Groups screen and add the user(s) to their appropriate Group for access. This will automatically update the application through the Group and will not require another conversion.
Updating Certificates
This set of instructions is intended to be completed when a new certificate is required or is expiring.
1. Sign in to ZenGRC
Use the Sign in with SSO, provided the certificate you are replacing has not already expired for Okta. If so, then utilize Sign in with Email or Sign in with Google.
2. Access Authentication Settings
In the left-hand navigation, click Settings > Authentication.
3. Edit Settings
Click SAML 2.0 > Edit Settings to access the ZenGRC and Okta confirmation URLs and certificates.
4. Add IdP Certificate
Scroll to the bottom of the screen.
Click the option to + Add IdP Certificate.
Make sure the certificate file is available and open at this point. The file itself will not be imported, but rather the data in the file will need to be copied and then pasted into ZenGRC.
5. Adding Certificate Data
After clicking the + Add IdP Certificate a new blank field will open to allow the pasting of the certificate data from Okta to ZenGRC.
Be sure to copy all the data if using a file. There will be a starting and ending point identified by the following:
-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----
Be sure to copy everything as it is all required for the certificate creation in ZenGRC.
Click Save when done.
6. Confirm Loaded Certificate
Once saved, there should now be two certificates displayed:
The old one was originally configured with SSO/SAML and the new one just added.
Click Next and Next (following screen) to exit out.
The next step of removing the old certificate is OPTIONAL - keeping the application clean is important, but not required.
7. Removing Old Certificate
Click the … at the end of the box containing the old certificate.
A drop-down will display and selecting Delete will delete the old certificate.
After deleting the certificate, be sure to log out and log back into ZenGRC to be sure the new certificate alone is working and will allow SSO login to continue.