1. Sign in to Okta as an administrator.
   
   

2. Click Developer Console in the top-left corner of Okta and select Classic UI.
   
   

   Open

   

    

3. Follow the Okta documentation to Set up a SAML application in Okta until you arrive at the following screen:
   
   

    

4. 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:
      
      

       

5. Click Show Advanced Settings in Okta. (The screenshot below displays this and the following two steps).
   
   

6. Next to Enable Single Logout, select the checkbox beside Allow application to initiate Single Logout.
   
   

7. In the Single Logout URL text box, paste the value from ZenGRC Single Logout URL. The string will end with "single_logout_service."
   
   

    

8. In the SP Issuer field, paste the value again from ZenGRC Entity ID. The string will end with "metadata."
   
   

9. Click Browse next to Signature Certificate and select the certificate that your ZenGRC administrator should have provided.
   
   

10. Click Upload Certificate.
    
    

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

12. Continue clicking through the Okta setup until finished.
    
    

    IMPORTANT: Make certain to add users or user groups determined by your organization, or the connection will fail.
    
    

     

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

    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 Credentials Details will need to be updated to email. By selecting edit for the Settings, scroll down to the field labeled Application username format and select email from the dropdown menu (Okta defaults to username). Click Save.
    
    

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

Back to top

1. Sign in to Onelogin as an administrator
   
   

2. If you aren't already there, navigate to Administration.
   
   

3. Click Application in the top menu and then click the Add Application button
   
   

    

4. Type SAML into the search field to filter the list of applications, and then select the application called OneLogin SAML Test (IdP). 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).
   
   

    

5. Replace the value in DisplayName with whatever name you plan to use for ZenGRC (“ZenGRC,” “ZenGRC Prod,” etc.)
   
   

6. Click Save
   
   

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

    

8. From the left-hand-side navigation, click Parameters. Click the + icon to add a new parameter.
   
   

9. Under Field Name, type nickname and select Include in SAML assertion. Click Save.
   
   

    

10. In the resulting drop-down, select First Name and click Save
    
    

     

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

     

12. Click Users and add the ZenGRC administrator (and any other users you want to add at this time)

     

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

Back to top

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

    

    

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

    

3. Click New Application
   
   

    

4. Select Non-gallery application
   
   

    

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

6. Click the Set up single sign-on tile
   
   

   
   
   

7. Click the SAML tile.
   
   

    

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

    

9. 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 administrator should have provided a text file with the required URL values.
   
   

10. Click Save.

    NOTE: Ignore any prompts that might appear in Azure AD asking you if you'd like to test the application
    
    

11. Next, we’ll configure the required user attributes. Click the pencil icon in the top-right corner of the title titled User Attributes & Claims
    
    

    
    
    

     

12. Delete all four of the pre-configured attributes under the Additional claims section
    
    

     

13. Click Add new claim
    
    

     

14. Enter nickname in the Name field, select user.displayname from the Source attribute drop-down, and click Save
    
    

     

15. 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)
    
    

     

16. Modify the existing selection in the Source attribute drop-down to user.mail, then click Save.
    
    

     

     

17. Next, you’ll obtain the IdP metadata URL, which you’ll need to share with the ZenGRC administrator 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.
    
    

     

     

18. 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).
    
    

     

19. Share the metadata URL you collected above with ZenGRC administrator, who will complete the configuration in ZenGRC.

Back to top

1. Log into your Windows server as an administrator.

    

2. Click the Windows button, then click Server Manager
   
   

    

3. From the top menu of the Server Manager dashboard, click Tools and select AD FS Management
   
   

   
   
   

4. From the left-hand side directory tree, click Relying Party Trusts
   
   

    

5. Click Add Relying Party Trust
   
   

    

6. Leave the default selection of Claims Aware and click Start
   
   

    

7. On the next screen, you’ll upload the ZenGRC metadata XML file provided by your ZenGRC administrator.
   
   You’ll need to have this XML file available on the local server where you’re configuring ADFS.
   
   

   To upload the file, select the radio button for Import data about the relying party from a file, browse to the metadata XML file, and click Next
   
   

    

    

8. Enter the name you’d like to use for the ZenGRC relying party application in the Display Name field and click Next
   
   

    

    

9. In the next screen, leave the default selection for Permit everyone, and click Next
   
   

    

    

10. In the next screen, you may optionally review the details under each tab or simply click Next
    
    

     

     

11. In the final screen of the wizard, leave the Configure claims issuance policy for this application checkbox selected, and click Close.
    
    

     

     

12. A new window titled Edit Claim Issuance Policy should open automatically. Note that it might open behind the current AD FS setup window.
    
    If you can’t find it, then click Edit Claim Issuance Policy… from the right-hand-side menu in the AD FS setup window. Once you have the window in view, click Add Rule…
    
    

     

     

13. In the next screen, leave the default selection for Claim rule template, and click Next
    
    

     

     

14. Name the rule whatever you like (e.g. “ZenGRC Required Attributes”).
    
    

     

     

15. Create two LDAP mappings as per the following screenshot. In the Attribute Store drop-down, select Active Directory, then click Finish.
    
    

     

16. Click OK
    
    

     

     

17. Next, you’ll construct the ADFS IdP metadata URL to provide back to your ZenGRC administrator.
    
    The URL is comprised of your Active Directory’s hostname URL plus a federation metadata endpoint that we’ll obtain from ADFS.
    
    Starting with the endpoint, expand the Service folder from the left-hand side directory tree and click Endpoints.
    
    Scroll all the way to the bottom of the list of endpoints to the section titled Metadata. Locate the federation metadata URL. It should be similar to the highlighted URL in the following screenshot:
    
    

    
    Note: Unfortunately you cannot copy this value from ADFS, so you’ll need to actually type it into a text file that you’ll share with your ZenGRC administrator. When combined with the Active Directory host URL, the resulting URL string should look similar to the following:
    
    → https://ad2016.corp.zengrc.net/FederationMetadata/2007-06/FederationMetadata.xml
    
    

18. 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 ADFS IdP metadata URL you generated in the prior step.
    
    Note: Part 4 of these instructions will already instruct the ZenGRC administrator to set Want Name ID to true.
    
    

Back to top

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.

1. If your IdP requires a certificate from the service provider, upload the one provided to you by the ZenGRC administrator.
   
   

2. 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.
      
      Note: 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:

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

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 organization's 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.
  
  

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

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

Back to top