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!