This article outlines how to set up and configure SAML with Envoy Visitors. To learn more about the benefits of using single sign-on, please read our About SAML article.
- Go to Integrations > All integrations.
- Locate Single sign-on and click “Install.”
- Enter the fingerprint from your IdP in the Fingerprint field.
(Optional) Set SAML to required
If you’d like to configure SAML as required, we recommend first setting up SAML as optional and testing with a small group of users. Once you’re sure SAML is working properly for your users.
- Go to Integrations > Enabled integrations.
- Locate SAML and click “Configure.”
- Enter your IdP HTTP SAML URL in the Identity Provider HTTP SAML URL field.
- Toggle “Required” to the “on” position.
Configuring SAML for common IdPs
You can connect Envoy to any SSO provider with SAML 2.0. We’ve provided guides for a few common IdPs:
Configuring SAML for ADFS 3.0
- This guide does not cover how to install ADFS, configure domains and certificates, or provision users in AD or Envoy. Before you configure ADFS for SSO with Envoy:
- Users should already exist in Active Directory, and the admins and employees that need Envoy access should already exist in Envoy. If you need help populating your Envoy employee directory from AD, learn more here.
- This guide assumes ADFS v3.0 or ADFS 2012 R2 are installed on Windows Server 2012 R2.
Step 1: Configure ADFS
- Go to the ADFS Management Console.
- Under Trust Relationships, select “Relying Party Trusts,” then “Add Relying Party Trust.” Envoy will be the relying party in this setup.
- Under Select Data Source, select “Import data about the relying party published online or on a local network.”
- In the Federation metadata address field, type in: https://app.envoy.com/a/saml/metadata
- For Display Name enter “Envoy Identity” (you can enter any name you like here to identify the service). Click “Next” and select “ADFS profile,” then click “Next” again.
- Click through the remaining steps, configuring Multi-factor Authentication and Issuance Authorization Rules as desired. These are not required, and this guide assumes they are not used.
- After finishing the wizard, select Envoy Identity and then “Edit Claim Rules” (alternatively, you can leave the box checked at the end of the wizard to automatically open the claim rules).
- At this point, there should not be any rules. Select the option to add a rule.
- Under Claim rule template, select “Send LDAP Attributes as Claims” from the dropdown. Click “Next.”
- Under Claim rule name enter “Get LDAP email” (you can enter any name you like here). For Attribute store, select “Active Directory.” Add a mapping by selecting “E-Mail Addresses” from both the LDAP Attribute and Outgoing Claim Type dropdowns.
- This assumes that your Envoy login email is stored in Active Directory as the user’s Email Address attribute. If you intend to use a different attribute, change the first field to the attribute that contains the user’s login for Envoy. Click “Finish.”
- Click “Add” to create a second Claim Rule. On the next page, select “Transform an Incoming Claim.”
- Under Claim rule name, enter something such as “Email to NameID.”
- For incoming claim type, select “E-Mail Address” (this corresponds to the Outgoing Claim from the previous rule).
- For outgoing claim type, select “Name ID.”
- For outgoing name ID format, select “Email.”
- Leave the other options on their defaults.
- Click “Finish,” then save the rules by clicking “Apply” or “OK.”
Step 2: Configuring Envoy
Envoy requires a fingerprint of the authentication certificate that will be used to sign the SAML assertion. In this section, we’ll find the fingerprint and connect with Envoy.
- In the management console, under Service > Certificates, find the “Token-signing” certificate.
- Envoy expects a SHA1 fingerprint. On the Details tab, scroll down to see that the Thumbprint Algorithm is SHA1, then select “Thumbprint” to view the signature.
- Copy this thumbprint.
- Log in to your Envoy dashboard and go to your Integrations page. Under Single sign-on, find SAML and click “Install.”
- Paste the fingerprint that was copied from AD.
- **Note: be sure to remove all the spaces from your fingerprint. **
- Under Identity Provider HTTP SAML URL you can optionally enter the URL for the IdP that corresponds to Envoy. This may be something like https://yourdomain.com/adfs/ls/IdpInitiatedSignOn.aspx?logintoRP=https://app.envoy.com/a/saml/consume
- Click “Save.”
- If you’re logged in to Envoy, log out now. This will ensure that any errors are not hidden during login.
- Login to the AD IdP-initiated signon page.
- Select “Envoy” from the dropdown, and click “Sign in.”
- If everything is configured correctly, you should be logged in to the Envoy dashboard!
If you see an error on the Envoy login screen after attempting to sign in to Envoy using SSO, you may need to check some configuration settings.
Scenario 1: SAML certificate is not valid
This may indicate that the identifiers are mis-configured for the Envoy Relying Party Trust. Check the Identifiers tab of the properties dialog and ensure that there is a single Relying Party identifier with https://app.envoy.com/a/saml/consume.
Scenario 2: SAML account not found
This error could result from a couple problems:
- It may indicate that the fingerprint in the Envoy configuration is misconfigured. Make sure that you have the SHA1 fingerprint (or thumbprint) of the token-signing certificate. If you are unsure which certificate is used, you may try capturing the SAML request in the browser and decoding it to check.
- It may also indicate that the SAML assertion was sent successfully, but that Envoy could not find a user that corresponds to that email address. Ensure that that the user who is logging in has an email address that is already provisioned and confirmed in Envoy.
Scenario 3: No error, just displays login screen
This may indicate that the user’s email address is not getting sent correctly. Double check that there are two Claim Rules configured to send the LDAP email address as a Name ID claim.
If you need support
If you need to contact Envoy support, there are a few pieces of information that we’ll need to help resolve your issues.
- Tell us the exact time that you tried logging in and saw an error. It helps us to be able to look up the failure in our logs. Let us know the email address of the user that is attempting to log in, so we can double check that user is in our system.
- It’s also very helpful to capture the SAML request in the browser so we can compare it to what we expect. Most web browsers support a way to view the contents of a request. Here’s how to capture the request in Internet Explorer 11.
- Before making the login attempt, hit F12 to open Developer Tools. Click to the Network tab, and press the green play button to start recording.
- Now try to sign in. After the attempt fails, you should see many requests in the network tab at the bottom of the screen. The one we are interested in is the POST request to our SAML consume endpoint, https://app.envoy.com/a/saml/consume
- Click DETAILS and examine the Request Body. It should start with “SAMLResponse=…” followed by a bunch of encoded data.
- Select this data and send it to us. You can also decode it yourself.