To learn more about the benefits of using single sign-on, please read our About SAML article.
- Go to Integrations > All integrations.
- Locate SAML and click “Install”.
- Enter the fingerprint from your IdP in the Fingerprint field.
(Optional) Set SAML to required
Tip: 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, switch it to required.
- 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.
Note: Global admin's will always be able to authenticate with a password regardless of if requiring SAML is on or off.
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.
3. 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:
4. 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.
5. 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.
6. 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).
7. At this point, there should not be any rules. Select the option to add a rule.
8. Under Claim rule template, select “Send LDAP Attributes as Claims” from the dropdown. Click “Next.”
9. 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 drop-downs.
• 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.
10. Click “Finish”.
11. Click “Add” to create a second Claim Rule. On the next page, select “Transform an Incoming Claim”.
12. 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.
2. 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.
3. Copy this thumbprint.
4. Log in to your Envoy dashboard and go to your Integrations page.
5. Under Single sign-on, find SAML and click “Install”.
6. Paste the thumbprint that was copied from AD into the "Fingerprint" field.
Note: be sure to remove all the spaces from your fingerprint.
7. Under Identity Provider HTTP SAML URL you can optionally enter the URL for the IdP that corresponds to Envoy.
• This may be something like
8. 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”.
4. If everything is configured correctly, you should be logged in to the Envoy dashboard!