SSO Setup Part 1: Gather SSO Details

Owned by Victoria Buhler (Deactivated)
Last updated: Oct 25, 2022 by Dave Lake (Deactivated)
4 min read

Overview

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.

Prerequisites

You’ll need to have administrator access to ZenGRC to complete this section.


On this page

Part 1: Gather SSO Details

Gathering ZenGRC Service Provider Details for your IdP Admin

 

 

 

1. ZenGRC Sign-in

If there are multiple options for logging into your ZenGRC instance, make sure to select Sign in with Email.

Click to enlarge

 

 

2. Go to Settings

In the left-hand navigation, click Settings | Authentication.

 

Click to enlarge

 

 

 

3. Keep SAML Unselected

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.

 

 

 

4. Edit/Configure Settings

Click Edit Settings (or, if you're setting up SAML for the very first time in ZenGRC, this button may say Configure instead of Edit Settings).

 

 

 

5. Obtain Metadata

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.


→ 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.

 

→ 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.

 

→ 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.

 

 

 

6. Download Metadata File

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.

 

 

 

7. SAML Settings Screenshot

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.

 

 

 

 

 

8. Confirm all data collected

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 metadata (in the form of a metadata URL, the downloaded metadata XML file, and/or a text file you created manually by copying/pasting)

  2. ZenGRC certificate (if you think it might be required by your IdP)

  3. Screenshot of Advanced Settings

 

 

© 2021 Copyright Reciprocity, Inc.
https://reciprocity.com