SSO with Microsoft AD FS internal network only

Warning
Only use this manual if you can not use the default and recommended method for configuring Microsoft AD FS for ZIVVER.

Configuring SSO with the method from this manual causes SSO to stop working when your AD FS certificate expires. This requires manually updating the AD FS metadata in ZIVVER after expiration of your AD FS certificate.

Configuring SSO with the method from this manual prohibits users from logging in to ZIVVER outside your internal network. This could cause login problems with for example working from home.

Introduction

ZIVVER supports Single Sign-On (SSO) via Microsoft AD FS, so that users can log in to ZIVVER with their workplace credentials. This manual shows how to set up SSO, as a ZIVVER administrator.

SSO operates on the basis of Security Assertion Markup Language (SAML) v2.0; in this scenario, Microsoft Azure AD is the Identity Provider (IdP) and ZIVVER is the Service Provider (SP).

To activate SSO in ZIVVER, you need the following:

  1. You are a ZIVVER administrator.

  2. You have access to AD FS management console on de AD FS server.

Set up SSO in ZIVVER using alternate method

  1. Open your favorite browser.

  2. Log in to the ZIVVER WebApp.

  3. Click Organisation settings tune in the lower left corner .

  4. Go to the Single Sign-On vpn_key page.

  5. Select Manually paste your organization’s Identity Provider (IdP) SAML metadata XML file contents.
    The following steps help you retrieve the SAML metadata of AD FS so that you can paste it in the ZIVVER WebApp.

  6. Log in on your AD FS server.

  7. Open a browser.

  8. Fill in the URL of the AD FS, followed by /FederationMetadata/2007-06/FederationMetadata.xml
    For example: https://adfs.organisation_domain.tld/FederationMetadata/2007-06/FederationMetadata.xml.
    Modern browser will automatically save a file called FederationMetadata.xml. In IE11 you can save the page as an .xml file using Ctrl + s.

    Tip
    Use the PowerShell cmdlet Get-AdfsEndpoint -AddressPath "/FederationMetadata/2007-06/FederationMetadata.xml to find your AD FS Metadata URL. The URL will most likely loke something like this: https://adfs.organisation_domain.tld/FederationMetadata/2007-06/FederationMetadata.xml
  9. Open the FederationMetadata.xml file in Notepad.
    Opening in Notepad is important because you need the metadata in plain text.

  10. Select and copy the full content of the .xml file.

  11. Go back to the Single Sign-On vpn_key page in ZIVVER.

  12. Paste the full content in the text box under Identity Provider XML.

  13. Place a checkmark next to Use Single sign-on.

  14. Click SAVE.

    Note
    ZIVVER is now configured to work with Single Sing-On, however AD FS has not been configured yet to handle incoming authentication requests from ZIVVER. When SSO is enabled in the ZIVVER admin panel, ZIVVER will only authenticate users via the Identity Provider. This could cause log in problems for users who are created before SSO is fully configured. Users will remain logged in and won’t be logged out when you toggle SSO on or off. ZIVVER administrators can always log in to ZIVVER with a username and password, even if AD FS is not yet configured to work with ZIVVER.
  15. Click the copy icon content_copy next to the ZIVVER metadata URL box. You will be able to use this URL in the following procedure.
    ZIVVER is now set up to work with Single Sign-On. The next and final step is to adjust the settings in the AD FS Management Console.

Set up SSO in AD FS

  1. Open the AD FS Management Console.

  2. Click Add Relying Party Trust on the right.

  3. Choose Claims aware if you have a choice between Claims aware and Non-claims aware.

  4. Click Start.

  5. Select Import data about the relying party published online or on a local network.

  6. Under Federation metadata address (host name or URL), paste the ZIVVER metadata URL: https://app.zivver.com/api/sso/saml/meta.

  7. Click Next.

    Tip

    If you see the error message "An error occurred during an attempt to read the federation metadata. Verify that the specified URL or host name is a valid federation metadata endpoint. Verify your proxy server setting. For more information […​]" add the following registry key to the AD FS server and then reboot the server.
    Location: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319
    DWORD name: SchUseStrongCrypto
    Value: 1
    Background info

  8. Choose ZIVVER as name of the integration.

  9. Click Next.

  10. Choose an Access Control Policy or choose to Permit everyone.
    With an Access Control Policy you assert that only users belonging to a certain group are permitted to access ZIVVER.

  11. Click Next.
    You will be shown a summary of the settings regarding AD FS settings.

  12. Verify all the data is correct.

  13. Click Next.

  14. Leave the checkmark next to Open the Edit Claim Rules dialog checked.

  15. Click Close.

Set up Claim Rules

You must set up the Claim Rules in the AD FS Management Console in order to enable ZIVVER to retrieve information about a user from AD FS. Claim Rules translate attributes from AD FS into values ​​that ZIVVER can read and use. You will automatically enter the Edit Claim Issuance Policy if you have just created a Relying Party Trust. Otherwise go to Relying Party Trusts > app.zivver.com > Edit Claim Issuance Policy in the AD FS Management Console.

  1. Click Add Rule.

  2. Make sure that Send LDAP Attributes as Claims is selected.

  3. Click Next.

  4. At Claim rule name, enter a name, for example AD Attributes.

  5. Under Attribute Store: select Active Directory.

  6. In the first row, set LDAP Attribute to E-Mail-Addresses.

  7. In the first row, set Outgoing Claim Type to E-Mail Address.

  8. In the second row, set LDAP Attribute to objectGUID.

    Tip
    Select objectGUID from the dropdown menu. Retyping or copy and pasting objectGUID to the AD FS Management Console is prone to error and could lead to a missing objectGUID in the SAML response.
  9. In the second row, set Outgoing Claim Type to https://zivver.com/SAML/Attributes/ZivverAccountKey.

    Warning
    ZIVVER uses ZivverAccountKey in the encryption process. It is therefore important that the number is long, unique and random. Preferably, this number is generated by your organization and is not used by other integrations or systems. If it is not possible to generate this number yourself, using objectGUID is an alternative. However, this number is often used in other integrations, and is therefore a security risk. ObjectSID or other AD attributes should not be used, because these values ​​are easy to guess.
  10. Click Finish to save the claim rules.

  11. Click Add Rule to add a second claim rule.

  12. Choose the Transform an Incoming Claim template.

  13. Click Next.

  14. At Claim rule name enter a name, for example E-mail transform.

  15. Set Incoming claim type to E-Mail Address.

  16. Set Outgoing claim type to Name ID.

  17. Set Outgoing name ID format to Email.
    This ensures that the e-mail address of the user is passed as the primary value.

  18. Click Finish.
    You have now successfully set up the connection between ZIVVER and AD FS.

ZIVVER 2FA exemption (optional)

A ZIVVER account is protected by default with an additional access code (2FA). 2FA is also required when logging in to ZIVVER via SSO. However, the ZIVVER 2FA can be exempted in certain Authentication Contexts. AD FS can pass through certain Authentication Methods to prove the login attempt is secure enough to exempt ZIVVER 2FA.

With the following Authentication Methods, ZIVVER does not ask for a 2FA when logging in:

  • urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos

  • urn:federation:authentication:windows

Warning
The above Authentication Methods ensure that a user is never asked for 2FA when logging in to ZIVVER given these Authentication Contexts. This is a possible security risk because users can now log in to ZIVVER without 2FA. Be prudent before applying these Authentication Methods and analyze the security risks before implementing!

Follow the steps below to set the 2FA exemption for AD FS in ZIVVER:

  1. Log in to the ZIVVER WebApp.

  2. Click the Organization Settings tune icon at the bottom left of your screen.

  3. Click Single Sign-On (SSO) vpn_key .

  4. In the SAML 2.0 authentication contexts with ZIVVER 2FA exemptions field, enter the following values:
    urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos
    urn:federation:authentication:windows

  5. Click SAVE.
    You have now successfully set a 2FA exemption for AD FS. When users log in via SSO with the above Authentication Contexts, ZIVVER will not ask for 2FA.

Log in to the WebApp with SSO

  1. Go to the WebApp.

  2. Enter your e-mail address.

  3. What is your role in ZIVVER?

    • User: you are immediately redirected to the login screen of your organization.

    • Administrator: you are prompted to choose between your ZIVVER password and your workplace credentials to log in.

  4. Log in with your workplace credentials.
    Depending on the existence of a 2FA exemption, you may be asked for an extra login method. With a 2FA exemption in place, you can skip the last step.

  5. Enter your extra login method.
    You are logged in to ZIVVER WebApp.

Log in to Outlook with SSO

In the ZIVVER Office Plugin in Outlook you log in with SSO in the following way:

  1. Click the ZIVVER tab.

  2. Click Manage Accounts account_circle .

  3. Click the link Add an account add_circle .

  4. Select the e-mail address with which you want to log in.

  5. Click Yes, I want to log in now.
    You will be redirected to the login screen of your organization.

  6. Log in with the workplace login details of your organization.
    Depending on the existence of a 2FA exemption, you may be asked for an extra login method. With a 2FA exemption in place, you can skip the last step.

  7. Enter your extra login method.
    You are logged in to Outlook.

Change User Name field on AD FS login page (optional)

Applies to: Windows Server 2012 R2 and Windows Server 2016.

Note
These are advanced settings.

AD FS supports customizing the login experience on Windows Server 2012 R2 and Windows Server 2016. Below are three options to customize the Username field on the AD FS login page.

Set up email address as login name

ZIVVER uses the e-mail address as the login name. If you log in to the ZIVVER WebApp, your e-mail address will automatically be forwarded to AD FS. If a user logs into AD FS with a User Principal Name (UPN) such as contoso\jdoe, then they will not be able to log in with the prefilled e-mail address. This can be confusing for users. Use the following steps to set up AD FS so that the e-mail address is also accepted as the login name:

  1. Open Powershell on the primary AD FS server.

  2. Use the following command to set the email AD attribute as an alternative login name:
    Set-ADFSClaimsProviderTrust -TargetIdentifier "AD AUTHORITY" -AlternateLoginID mail -LookupForests
    Background information

    Note
    Substitute with your AD domain.
    Users will now be able to also log in to AD FS with their email address as username.

To remove the alternative login method issue the following command:
Set-ADFSClaimsProviderTrust -TargetIdentifier "AD AUTHORITY"-AlternateLoginID $NULL -LookupForests $NULL

Set a custom login name

Edit the AD FS onload.js file to set a custom login name. This will allow users to fill in values for their username other than UPNs.

To do this, add document.forms['loginForm'].UserName.value = '\\' to the AD FS onload.js.
Use Example 2 in this Microsoft article as a model.

Leave login name empty by default

Adjust the AD FS onload.js to leave the username field blank by default. To do this, add`document.forms['loginForm'].UserName.value = ''` to AD FS onload.js.
Use Example 2 in this Microsoft article as a model.

Create shortcut to the WebApp (optional)

Use the link below to create a shortcut, which allows the user to directly open the WebApp without having to log in manually:

Add trusted networks to AD FS (optional)

Applies to Windows Server 2012 and Windows Server 2012 R2

Warning
This may affect users' ability to mail securely. Consider the situation carefully before proceeding.

If your organization uses AD FS for SSO, you can set that users can only log in to ZIVVER from within a certain IP range. Trusted networks should not be used in ZIVVER if you also use SSO. Therefore, set the IP range in AD FS.
Learn how to set up trusted networks in AD FS.

Was this article helpful?

thumb_up thumb_down