Page Contents:

Table of Contents

exclude	.*\.

Overview

Regardless of your specific IdP, there are four high-level parts in the process of setting up SAML/SSO for ZenGRC, and this documentation is organized accordingly:

Part 1: Gathering ZenGRC Service Provider Details - “Service Provider” refers to any application (i.e. ZenGRC) that requests authentication from a central “Identity Provider”, or “IdP”. This section provides instructions for accessing information in ZenGRC that your IdP will use to identify ZenGRC as a trusted service provider. This part of the process must be performed by a ZenGRC Administrator.
Part 2: Entering ZenGRC Service Provider Details into Your IdP and Gathering IdP Details for your ZenGRC Admin - This section provides instructions for entering information about ZenGRC, obtained in the previous step, into your organization’s IdP. This step must be performed by a user with administrative access to your organization’s IdP platform (or more specifically, a user with permission to create and manage “service provider” applications in your IdP platform). This part of the process results in the generation of additional artifacts that your IdP administrator will then need to share with your ZenGRC administrator, who will use that information to apply further changes in ZenGRC.
Part 3: Entering IdP Details into ZenGRC - In order to finalize the “handshake” between ZenGRC and your IdP, a ZenGRC administrator must enter the information generated by your IdP administrator into ZenGRC.
Part 4: Enabling the SAML/SSO Login Option for ZenGRC End Users - The last step is turning on the SAML/SSO login option for ZenGRC users and determining which other login options you want to expose.

Part 1: Gathering ZenGRC Service Provider Details for your IdP Admin

To gather the information that your IdP administrator will need in order to add ZenGRC as a trusted service provider in your IdP platform, complete the following steps. These steps are the same for all IdPs except where otherwise noted. You’ll need to have administrator access to ZenGRC to complete this section.

If there are multiple options for logging into your ZenGRC instance, make sure to select Sign in with Email.
In the left-hand navigation, click Settings | Authentication.
If you are setting up SAML for the first time, the SAML checkbox will be unchecked. Do not select it until you've gone through all steps in this tutorial.

Note: The Debug Mode toggle in the screenshot above will display helpful debug information on failed attempts to log into ZenGRC via SSO. It should be enabled only when troubleshooting issues with your SAML/SSO configuration.
Click Edit Settings.
All IdPs require certain metadata about the service provider application, and depending on the specific IdP there are three possible ways to provide that metadata. If you aren’t sure which method your organization’s IdP supports, then complete the steps for all three options and include all of the resulting artifacts in the package you provide to your IdP administrator.
1. Option 1 - Metadata URL: If your organization’s IdP supports it, the easiest way for your IdP administrator to add the ZenGRC metadata to the IdP is by providing a metadata URL. To generate this URL, click Download ZenGRC Metadata (SP). A new browser tab will open with the metadata displayed in XML format. Copy the URL from your browser’s address field and paste it into a text file. Add the text file to the artifacts you are gathering for your IdP administrator.
2. Option 2 - Metadata File: The next easiest option is to add the metadata to the IdP via file upload. To generate the formatted metadata file for your IdP administrator, click Download ZenGRC Metadata (SP). A new browser tab will open with the metadata displayed in XML format. Find your web browser’s “Save As” dialogue and save the web page as an XML file by adding “.xml” to the end of the filename.
3. Option 3 - Copy-and-Paste the Metadata: If your organization’s IdP accepts neither of the above methods, then create a blank text file and copy each of the URLs in the above screenshot into the text file. You can quickly copy the values by clicking the Copy button to the right of each one. However, be sure to also add the field labels so that your IdP administrator knows which URL value goes where in the IdP platform.
In order to validate the authenticity of authentication requests that claim to be coming from a trusted service provider, IdPs compare those requests against an encrypted certificate from the service provider application. ZenGRC provides this certificate in the metadata collected above, however, some IdPs (e.g. Okta) require that this encrypted service provide certificate be uploaded into the IdP separately from the metadata. If you aren’t sure whether your organization’s IdP requires that the certificate be uploaded separately, go ahead and download it now and include it with the artifacts that you're gathering for your IdP administrator. Your IdP administrator will know whether it’s required, and if it turns out that it is, you’ll have saved yourself a step by downloading it right now.
At this point, you should have only one certificate available in ZenGRC. To download the certificate, click the ellipsis to the right of the certificate and select Download.
Click the Advanced Settings tab and take a screenshot of ZenGRC’s default SAML advanced settings. These settings default to the most common values, but your IdP administrator might ask you to modify them after reviewing them. It’s recommended you take this screenshot directly from your ZenGRC instance rather than from this documentation:
Collect everything you’ve generated in the prior steps and provide it to your IdP administrator along with a link to these setup instructions. This package should now include:
1. ZenGRC certificate (if you think it might be required by your IdP)
2. ZenGRC metadata (in the form of a metadata URL, the downloaded metadata XML file, and/or a text file you created manually by copying/pasting)
3. Screenshot of Advanced Settings

Part 2: Entering ZenGRC Service Provider Details into Your IdP and Gathering IdP Details for your ZenGRC Admin

This section provides instructions for entering the service provider information that your ZenGRC administrator collected from ZenGRC into your organization's IdP. In order to perform this part of the setup process, you must have administrative access to your organization's IdP.

Before completing these steps, ensure that the ZenGRC administrator has provided you with the following artifacts:

ZenGRC’s encrypted service provider certificate (if your IdP platform requires one)
ZenGRC metadata (depending on your IdP, this might be in the form of a metadata URL, a formatted XML file to upload to your IdP, or a text file with metadata values that you can copy-and-paste into your IdP)
A screenshot of ZenGRC’s SAML advanced settings for you to review and communicate any required changes back to the ZenGRC administrator

The process of entering service provider details into the IdP platform varies depending on the specific IdP your organization is using, so expand the appropriate section for your organization's specific IdP below:

Expand

title	Click here for Okta

Configuring Okta

Sign in to Okta as an administrator.
Click Developer Console in the top-left corner of Okta and select Classic UI.
Follow the Okta documentation to Set up a SAML application in Okta until you arrive at the following screen:
Enter the service provider metadata collected from ZenGRC into Okta.
1. 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 below.
2. 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:
Click Show Advanced Settings in Okta. (The screenshot below displays this and the following two steps).
Next to Enable Single Logout, select the checkbox beside Allow application to initiate Single Logout.
In the Single Logout URL text box, paste the value from ZenGRC Single Logout URL. The string will end with "single_logout_service."
In the SP Issuer field, paste the value again from ZenGRC Entitly ID. The string will end with "metadata."
Click Browse next to Signature Certificate and select the certificate that your ZenGRC administrator should have provided.
Click Upload Certificate.
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.firstName.
Continue clicking through the Okta set up until finished.
IMPORTANT: Make certain to add users or user groups determined by your organization, or the connection will fail.
Once complete, Okta displays a page where you can view set up. Right-click on the Identity Provider Metadata link and select Copy Link Address. This link will need to be entered into ZenGRC, so be sure to save it so that you can provide it to your ZenGRC administrator)
Review the screenshot of ZenGRC’s SAML 2.0 advanced settings that your ZenGRC administrator provided and make sure to provide any required changes to your ZenGRC administrator along with the IdP metadata URL you copied in the prior step.

NOTE: The IdP metadata URL includes IdP certificate information, so there is no need to provide Okta’s IdP certificate separately to the ZenGRC administrator.

Expand

title	Click here for Onelogin

Configuring Onelogin

Sign in to Onelogin as an administrator
If you aren't already there, navigate to Adminstration.
Click Application in the top menu and then click the Add Application button
Type SAML into the search field to filter the list of applications, and then select the application called . If you don’t see this application in your Onelogin instance, you can select any application from the list (these are just templates that we’re going to modify anyway)
Replace the value in DisplayName with the whatever name you plan to use for ZenGRC (“ZenGRC,” “ZenGRC Prod,” etc.)
Click Save
From the left-hand-side navigation, click Configuration. This is where we’ll enter the service provider URLs from ZenGRC (or, if you don’t have administrative access to ZenGRC, then a ZenGRC administrator should have provided these URLs to you in a text file)
NOTE: Leave the ACS URL Validator filed blank
From the left-hand-side navigation, click Parameters. Click the + icon to add a new parameter.
Under Field Name, type nickname and select Include in SAML assertion. Click Save.
In the resulting drop-down, select First Name and click Save
To obtain the IdP metadata, click the More Actions drop-down, and select SAML Metadata. You’ll need to provide this file to your ZenGRC administrator so they can upload it into ZenGRC’s SAML 2.0 settings in the next part of the setup process.
Click Users and add the ZenGRC administrator (and any other users you want to add at this time)
Review the screenshot of ZenGRC’s SAML 2.0 advanced settings that your ZenGRC administrator provided and make sure to provide any required changes to your ZenGRC administrator along with the IdP metadata file you downloaded above.

Expand

title	Configuring Azure AD

Configuring Azure AD

Sign in to Microsoft Azure as an administrator and navigate to the Azure Active Directory service console. It may be available immediately on your Azure landing page, or you might have to navigate to it by first clicking More Services.
From the left-hand-side navigation menu in the Active Directory console, click Enterprise Applications. It may take several minutes for this screen to load.
Click New Application
Select Non-gallery application
Give the application name (e.g. “ZenGRC”, “ZenGRC Prod”, etc.), and click Add
NOTE: In some cases, Azure AD may hang after adding the new application. If so, simply navigate back through to the Enterprise Applications list and select the newly created application from the list before continuing to the next step.
Click the Set up single sign-on tile
Click the SAML tile.
Next, we’ll enter the service provider metadata from ZenGRC. Click the pencil icon in the top-right corner of the panel titled Basic SAML Configuration
Enter the service provide fields from ZenGRC as follows. If you have administrator access to ZenGRC then you can copy-and-paste the URLs directly as per the screenshot. Otherwise, your ZenGRC admintrator should have provided a text file with the required URL values.
Click Save.
NOTE: Ignore any prompts that might appear in Azure AD asking you if you'd like to test the application
Next, we’ll configure the required user attributes. Click the pencil icon in the top-right corner of the title titled User Attributes & Claims
Delete all four of the pre-configured
attributes under the Additinal claims section
Click Add new claim
Enter nickname in the Name field, select user.displayname from the Source attribute drop-down, and click Save
Return to the User Attributes & Claims screen, and now we’re going to modify the existing Unique User Identifier claim. To edit it, click the row as highlighted in the screenshot (it doesn’t look clickable, but it is)
Modify the existing selectiion in the Source attribute dop-down to user.mail, then click Save.
Next, you’ll obtain the IdP metadata URL, which you’ll need to share with the ZenGRC adminstrator so they can enter it back into ZenGRC’s SAML 2.0 settings. To obtain the URL, navigate back to the Single sign-on setup screen, and in the section titled SAML Signing Certificate, copy the App Federation Metadata URL by clicking the copy button. Paste this URL into a text file that you will share with the ZenGRC administrator.
Assign at least one user, the ZenGRC administrator, to the application. This will ensure that they can test the SSO connection once they completed the setup. To add the user, click Users and Groups in the left-hand-side menu and the desired user(s).
Share the metadata URL you collected above with ZenGRC administrator, who will complete the configuration in ZenGRC.

Expand

title	Configuring ADFS

Configuring ADFS

Sign in to ADFS as an administrator.
Review the screenshot of ZenGRC’s SAML 2.0 advanced settings that your ZenGRC administrator provided and make sure to provide any required changes to your ZenGRC administrator along with the IdP metadata URL you copied in the prior step.
NOTE: The IdP metadata URL includes IdP certificate information, so there is no need to provide Okta’s IdP certificate separately to the ZenGRC administrator.

Expand

title	Can't find your IdP?

General Guidance for Configuring Unlisted IdPs

This section provides general information that you and your ZenGRC administrator can use to enter ZenGRC service provider details into an IdP that has not been covered explicitly in this documentation.

If your IdP requires a certificate from the service provider, upload the one provided to you by the ZenGRC administrator.
Next, you’ll need to enter service provider metadata into the IdP. Depending on the IdP, this metadata can be provided by:
1. Entering into your IdP the metadata URL that your ZenGRC should have provided from ZenGRC
2. Uploading the formatted metadata XML file provided by your ZenGRC administrator
3. Copying-and-pasting the metadata values that your ZenGRC provided you in the form of an unformatted text file. If you’re going this route, it;'s important to note that metadata setting names vary among IdP providers, which can cause confusion as to what information should be entered where. The following are examples of metadata values along with some of the common names that IdPs use to refer to them:

Sample Setting Value	Common Names that IdPs use to refer to the Setting	Notes
https://[yourdomain].zengrc.com/saml/metadata	Audience Audience URL (SP Entity ID)
https://[yourdomain].zengrc.com/saml/assertion_consumer_service/	Recipient ACS (Consumer) URL Validator ACS (Consumer) URL	This same value might need to be entered into multiple fields in your IdP
https://[yourdomain].zengrc.com/saml/single_logout_service/	Single Logout URL	If your IdP provides an option for whether to allow single logout, enable the setting and enter this value for the single logout URL

3. Create two custom parameters for the ZenGRC application as follows:

4Parameter Name	Parameter Value
email	user.email
nickname	user.firstName

4. Review the screenshot that the ZenGRC administrator provided showing the default values for the SAML 2.0 Advanced Settings in ZenzGRC, and note any changes that need to be made either in the IdP or back in ZenGRC in order to match your organizations policies. Refer to the following descriptions of the advanced settings:

Enable encrypted nameID - Indicates that the nameID of the logout request sent by this SP will be encrypted.
Enable authentication request signed - Indicates whether the authorization request messages sent by this SP will be signed. (Metadata of the SP will offer this info.)
Enable single logout request - Indicates whether the logout request messages sent by this SP will be signed.
Enable logout response signed - Indicates whether the logout response messages sent by this SP will be signed.
Enable sign metadata - Sign the metadata false or true (use sp certs).
Want messages signed - Indicates a requirement for the response, logout request and logout response elements received by this SP to be signed.
Want assertions signed - Indicates a requirement for the assertion elements received by this SP to be signed. The Metadata of the SP will offer this info.
Want assertions encrypted - Indicates a requirement for the assertion elements received by this SP to be encrypted.
Want name Id - Indicates a requirement for the NameID element on the SAML 2.0 response received by this SP to be present.
Want attribute statement - Indicates a requirement for the attribute statement element.
Fail on authentication context mismatch - True validates the authentication context and False ignores the context.

6. ZenGRC requires a certificate from your IdP. For some IdPs (e.g. Okta), IdP certificate information is provided as part of the IdP metadata URL. In other cases, you may need to export a certificate explicitly from the IdP and ask the ZenGRC administrator to upload that IdP certificate into ZenGRC.

5. Provide the IdP metadata, the IdP certificate (if not included in the metadata), and any required modifications to ZenGRC’s SAML 2.0 advanced settings to your ZenGRC administrator.

Part 3: Entering IdP Details Back into ZenGRC

In this section of the setup process, you will finalize the “handshake” between ZenGRC and your IdP by entering the information generated by your IdP back into ZenGRC. This process must be completed by a ZenGRC administrator, and that ZenGRC administrator must have access to the artifacts generated by your IdP administrator in the prior section. These artifacts should include:

IdP metadata
Any required changes that your IdP requested you make on the Advanced Settings tab in ZenGRC’s SAML 2.0 setup screen

This process of entering IdP details into ZenGRC varies depending on the specific IdP your organization is using, so expand the appropriate section for your specific IdP below:

Expand

title	Entering from Okta

Entering from Okta

After securing the Okta metadata link from your Okta administrator, complete the following steps in ZenGRC:

Navigate to Settings | Authentication and click Edit Settings.
On the Settings tab, below the IdP Metadata heading, paste the link your Okta administrator provided from the Okta setup into the URL to metadata file.
Click Load IdP Metadata.
NOTE: Okta includes Idp certificate information via the metadata URL, so you do not need to separately upload Okta’s IdP certificate into ZenGRC.
If your Okta administrator noted any changes that need to be made to ZenGRC’s SAML 2.0 Advanced Settings, click the Advanced Settings tab and make the required changes.
Click Next to complete the setup and return to the main Authentication settings screen.

Expand

title	Entering from Onelogin

Entering from Onelogin

After securing the Onelogin metadata file from your Onelogin administrator, complete the following steps in ZenGRC:

Navigate to Settings | Authentication and click Edit Settings.
Scroll down to the IdP Metadata heading and click click to browse to browse to the metadata file provided by your IdP admin.
Click Load IdP Metadata (Note: The Onelogin metadata file includes the IdP certificate, so it does not need to be added separately)
If your IdP administrator recommended any change to ZeGRC’s advanced SAML 2.0 setting, click Advanced Settings and apply those changes.
Click Next to complete the setup and return to the main Authentication settings screen.

Expand

title	Entering from Azure AD

After securing the Azure AD metadata file from your Azure AD administrator, complete the following steps in ZenGRC:

Navigate to Settings | Authentication and click Edit Settings.
Scroll down to the IdP Metadata heading and click click to browse to browse to the metadata file provided by your IdP admin.
Click Load IdP Metadata (Note: The Azure AD metadata file includes the IdP certificate, so it does not need to be added separately)
Click Advanced Settings and modify the ID Name Format setting to Email Address
If your IdP administrator recommended any other changes to the Advanced Setting tab, apply them now.
Click Next to complete the setup and return to the main Authentication settings screen.

Expand

title	Entering from ADFS

Entering from ADFS

If your IdP administrator recommended any other changes to the Advanced Setting tab, apply them now.
Click Next to complete the setup and return to the main Authentication settings screen.

Expand

title	Can't find your IdP?

General Guidance for Unlisted IdPs

If you do not see instructions for your specific IdP, this section provides general information that you and your IdP administrator can use to enter IdP details into ZenGRC. The following are examples that ZenGRC might need from your organization’s IdP, along with the different names the fields may be called in your IdP:

Sample Setting Value	Common Names that IdPs use to refer to the Setting	Notes
https://app.onelogin.com/saml/metadata/470451	IdP Metadata URL
https://oneloginreciprocity.onelogin.com/trust/saml2/http-post/sso/470451	Single Sign On Service URL SAML 2.0 Endpoint (HTTP) Sign-on URL SSO URL IdP Login URL
https://oneloginreciprocity.onelogin.com/trust/saml2/http-redirect/slo/470451	Single Logout Service URL SLO Endpoint (HTTP)
X.509 Public Certificate	Public Certificate IdP Certificate	Be sure to include the entire certificate, including `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE------.` For some IdPs (e.g. Okta), the IdP certificate is provided via the IdP metadata URL and so does not need to be uploaded separately into ZenGRC

Be sure to also review ZenGRC’s SAML 2.0 Advanced Settings tab with your IDP administrator.

Test

Part 4: Enabling the SAML 2.0/SSO Login Option for ZenGRC End Users

In this final section of the setup process, you’ll enable the SAML 2.0/SSO option, test that you are able to log in using SAML 2.0 / SSO, and then turn off unwanted authentication options.

If you aren't already there, navigate to Settings | Authentication and select Edit Settings
Select the SAML 2.0 checkbox and enable the Debug mode toggle.
NOTE: ZenGRC will prevent you from disabling other authentication options until you've successfully logged in using SAML 2.0 / SSO.
Log out of ZenGRC.
On the ZenGRC log in page, select Sign in with SSO.
NOTE: If there are issues with the settings, and you have the Debug mode toggle on, they should display here.
Access Settings | Authentication.
Deselect any unwanted authentication methods.
Deselect the Debug Mode checkbox

Test

Versions Compared

Old Version 68

New Version 69

Key

Overview

Part 1: Gathering ZenGRC Service Provider Details for your IdP Admin