How do I connect Grovo to ADFS 2.0+ for single sign-on (SSO)?

This document is intended for an IT administrator to set up their Active Directory for SAML 2.0 SSO into Grovo. This document assumes that readers have a basic understanding of Active Directory as well as its Federation Service. Your deployment should follow Microsoft’s best-practices for deploying AD FS clusters and proxies—configuring a full AD DS / AD FS deployment is outside the scope of this guide.

If you wish to avoid the overhead of maintaining and supporting ADFS 2.0+, we suggest you look into 3rd party Identity Providers such as Okta and OneLogin.

Prerequisites

•  An ADFS 2.0/3.0/4.0 instance with an ADFS SAML endpoint that is exposed to the devices that will need to authenticate

Download Your Metadata

1.  Your metadata file should be found at https://<your-domain>/FederationMetadata/2007-06/FederationMetadata.xml. Make sure you are accessing through HTTPS.

2.  You will need this file to complete the configuration below.

Add a Relying Party Trust in ADFS

1.  Within ADFS 2.0+ Management, click Relying Party Trusts under AD FS 2.0 > Trust Relationships

2.  On the right hand side, select Add Relying Party Trusts...

3.  On the welcome screen select Start.

4.  Select Enter data about the relying party manually and select Next to advance. 

5.  Enter the Display name along with any Notes (optional) describing the relying party trust. Select Next to advance.

Note: The Display name can be set to whatever you'd like. We recommend setting it to something like Grovo SSO. Just make sure it's easy to identify this configuration in ADFS in case you need to make changes to it in the future.

6.  Select Next without altering this page.

Note: Grovo does not support encrypted claims. If you specify an encryption certificate below, SSO with Grovo will not work.

7.  Check Enable support for the SAML 2.0 WebSSO protocol and enter the Relying party SAML 2.0 SSO service URL. It should be a URL like this:

https://<subdomain>.grovo.com/sso/saml2/saml-assertion  

8.  Select Next to advance.

Note: Please replace <subdomain> with your company's unique subdomain. For example, if the URL you use to access Grovo is https://thunderdome.grovo.com, your subdomain is thunderdome.

9.  Set the Relying party trust identifier to:

https://<subdomain>.grovo.com/sso/saml2/metadata

10.  Select Add and then Next to advance.

Note: Please replace <subdomain> with your company's unique subdomain. 

11.  Select the appropriate access control policy for your organization. Select Next to advance.

12.  The Monitoring section will be grayed out by default. Skip this page by selecting Next to advance.

13.  Check the following box: Configure claims issuance policy for this application. Select Close to finish the Wizard. 

Configuring the Claim Rules

1.  From the drop-down list, select Send LDAP Attributes as Claims. Select Next to advance.

2.  Describe the Claim rule name by providing an appropriate name. We recommend Send LDAP Attributes as Claims.

3.  From the LDAP Attribute drop-down list (left hand column), select or type E-Mail-Addresses, Given-Name, and Surname. These attributes will come directly from your Active Directory's attribute store.

4.  From the Outgoing Claim Type drop-down list (right hand column), select or type E-Mail Address, First Name, and Last Name. Select OK to advance.

Note: The Outgoing Claim Type values must match the screenshot below. Grovo accepts very specific values, and will reject a user from gaining access to Grovo if these values are not correctly set.

5.  Select Add rule... to add another rule.

6.  From the Select Rule Template window, select Transform an Incoming Claim. Select Next to advance. 

7.  Describe the Claim rule name by providing an appropriate name. We recommend E-mail to NameID.

8.  For the Incoming claim type, select E-Mail Address from the drop-down. For the Outgoing claim type select Name ID from the drop-down. The Outgoing name ID format doesn't matter, but we recommend selecting Unspecified.

9.  Check the following radio button: Pass through all claim values. Select OK to advance. 

10.  Confirm that the order of the Issuance Transform Rules matches the screenshot below. The first claim rule template you created in steps 1-4, Send LDAP attributes as claims, should be given an order value of 1. The second claim rule you created in steps 5-9, Transform an Incoming Claim, should be given an order value of 2.

11.  Within ADFS 2.0 Management, select Relying Party Trusts under AD FS 2.0 > Trust Relationships. On the right hand side, select Properties.

12.  From the Properties window, select the Endpoints tab.

13.  Select Add SAML... to add a SAML Assertion Consumer Endpoints. We're going to be adding two endpoints with a binding of Redirect and Post.

Redirect Binding
• Confirm that Endpoint type is set to SAML Assertion Consumer
• Binding is set to Redirect
• Set the trusted URL as default is checked
• Index is set to 0
• For the Trusted URL, type in https://<subdomain>.grovo.com/, replacing <subomain> with your company's appropriate subdomain
• Select OK to advance

POST Binding
• Confirm that Endpoint type is set to SAML Assertion Consumer
• Binding is set to POST
• Set the trusted URL as default is unchecked
• Index is set to 1
• For the Trusted URL, type in https://<subdomain>.grovo.com/sso/saml2/saml-assertion, replacing <subomain> with your company's appropriate subdomain
• Select OK to advance 

14.  Confirm the endpoints match the screenshot below. The first URL, https://<subdomain>.grovo.com/, should have an Index value of 0 with Binding set to Redirect. The second URL, https://<subdomain>.grovo.com/sso/saml2/saml-assertion, should have an Index value of 1 with Binding set to POST.

15.  Select Apply and then OK to complete the configuration in ADFS.

Final steps: Configure Grovo to connect with your ADFS setup for SSO using these instructions: SP-Initiated SAML 2.0. 

After that, you're ready to go!