SSO with Microsoft AD FS

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

  1. Open your 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. Enter the URL of your organisation AD FS federation metadata XML file in the text box under Automatically retrieve metadata from URL (recommended).

    Tip
    Use the PowerShell cmdlet Get-AdfsEndpoint -AddressPath "/FederationMetadata/2007-06/FederationMetadata.xml on your AD FS server to retreive the AD FS metadata URL. The URL will probably be built up something like: https:///FederationMetadata/2007-06/FederationMetadata.xml
    Note
    If your organization only uses AD FS from an internal network, then ZIVVER cannot retreive the AD FS metadata from a URL. Go to the manual to set up SSO via AD FS for internal networks and proceed from there.
  6. Place a checkmark next to Use Single sign-on.

  7. Click SAVE.

    Note
    ZIVVER is now configured to work with Single Sign-On, however AD FS has not been configured yet. When SSO is enabled in the ZIVVER admin panel, ZIVVER will try to log users in via SSO. This could temporarily lead to login problems for users that already use ZIVVER. This login problem is resolved as soon as AD FS has been configured. Users that are currently logged in will remain logged in and will not be logged out when enabling or changing the SSO configuration in ZIVVER. ZIVVER administrators will always be able to log in to ZIVVER with their username and password, even when AD FS has not been configured yet.

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