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

The first step is to set up ZIVVER to use Microsoft AD FS SSO. This can be accomplished in the ZIVVER WebApp, if you have administrator rights.

The two methods for setting up ZIVVER to use AD FS SSO differ only in how the ADFS federation metadata is entered in ZIVVER. If you choose to paste the contents of the FederationMetadata.xml file in the ZIVVER admin interface, you won’t be able to also paste in an URL pointing to the file, and vice-versa.
  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 (the default is: https://<adfs.organisation_domain.tld>/FederationMetadata/2007-06/FederationMetadata.xml) in the text box under Automatically retrieve metadata from URL (recommended)..
  6. Place a checkmark next to Use Single sign-on.
  7. Click SAVE.
  8. 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.
ZIVVER will always try to log in via SSO when SSO is on. This can lead to log-in problems for users when SSO is not set up in AD FS. Disable SSO temporarily until SSO is set in AD FS. Users remain logged in when you enable SSO.

Set up SSO in ZIVVER using alternate method

Using the metadata URL does not work if the ADFS server you are using is not reachable from the Internet. The metadata needs to be imported from a file in such cases:

  1. Open your browser.
  2. Fill in the URL of your AD FS-server in the address bar, followed by /FederationMetadata/2007-06/FederationMetadata.xml
    e.g.: https://<adfs.organization.com>/FederationMetadata/2007-06/FederationMetadata.xml).
    The file should be saved on your computer now.
  3. Open the file in a text editor (for example Notepad).
  4. Copy the entire contents of the file to the clipboard.
  5. Log in to the ZIVVER WebApp.
  6. Click Organisation settings tune in the lower left corner .
  7. Go to the Single Sign-On vpn_key page.
  8. Select Manually paste your organization’s Identity Provider (IdP) SAML metadata XML file contents.
  9. Place the contents of the FederationMetadata.xml file in the text box under Identity Provider XML.
  10. Place a checkmark next to Use Single sign-on.
  11. Click SAVE.
  12. 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.
ZIVVER will always try to log in via SSO when SSO is on. This can lead to log-in problems for users when SSO is not set up in AD FS. Disable SSO temporarily until SSO is set in AD FS. Users remain logged in when you enable SSO.
If you use the alternate method, you will have to manually update the metadata every time it changes - such as when the IdP certificate expires. Disruptions of service may result.

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. Choose Import data about the relying party published online or on a local network (e.g. from step 8. of Set up SSO in ZIVVER)
    OR
    Choose Import data about the relying party from a file and select the file you downloaded in step 12. of Set up SSO in ZIVVER then continue from step 7. below.
  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.

    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 Value: 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 digest of the settings regarding AD FS coupling.

  12. Check that 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

ZIVVER must retrieve information about the user from the AD FS. To do this, you must set up the Claim Rules in the AD FS Management Console. These rules translate attributes from the AD FS into values ​​that ZIVVER can read and use. If you have just created an AD FS link, you will automatically enter the ** Edit Claim Issuance Policy ** window. Do not you see this? Then go to Relying Party Trusts > app.zivver.com > Edit Claim Issuance Policy.

  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. Enter the following attributes in the diagram below:

    • LDAP Attribute: ObjectGUID - Outgoing Claim Type: https://zivver.com/SAML/Attributes/ZivverAccountKey
    • LDAP Attribute: E-Mail Addresses - Outgoing Claim Type: E-Mail Address

    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 you and is not used in other connections 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 connections, and is therefore a security risk. ObjectSID or other AD attributes should not be used, because these values ​​are easy to guess.

  • Click Finish to save the claim rules.

  • Click Add Rule to add a second claim rule.

  • Choose the Transform an Incoming Claim template.

  • Click Next.

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

  • Now set the following transformation:

    1. Set Incoming claim type to E-Mail Address.
    2. Set Outgoing claim type to Name ID.
    3. Set Outgoing name ID format to Email.
      This ensures that the e-mail address of the user is passed as the primary value.
  • Click Finish.
    You have now successfully set up the connection between ZIVVER and AD FS.

  • Authentication Methods

    A ZIVVER account is protected by default with an additional access code (2FA). 2FA is also required when logging in via SSO. AD FS can pass the Authentication Method to ZIVVER, in order to receive the required 2FA. In the SAML standard this is called Authentication Context.

    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
    The above Authentication Methods ensure that you are never asked for 2FA when logging in to ZIVVER. This is a possible security risk because users can now log in to ZIVVER without 2FA. Be prudent before applying these Authentication Methods and think about the possible consequences!

    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, 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.

    Optional: Change User Name field on AD FS login page

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

    These are advanced settings.

    What you need to know before making these changes
    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, substituting the relevant AD domain used by your organization for <forest domain>:
      Set-ADFSClaimsProviderTrust -TargetIdentifier "AD AUTHORITY" -AlternateLoginID mail -LookupForests <forest domain>
      background information Users will be able to also log in to AD FS with his e-mail 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 = '<clientdomain.local>\\<yourusername>' 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, adddocument.forms['loginForm'].UserName.value = '' to AD FS onload.js. Use Example 2 in this Microsoft article as a model.

    Optional: Create shortcut to the WebApp

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

    https://adfs.<organization>.<tld>/adfs/ls/idpinitiatedsignon.aspx?logintorp=https://app.zivver.com/SAML/Zivver

    Optional: Add trusted networks to AD FS

    Applies to Windows Server 2012 and Windows Server 2012 R2

    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 shoud be configured 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