Introduction

How to set up SSO, as a Zivver administrator? Zivver supports Single Sign-On (SSO) through Microsoft AD FS. With this, users can log in to Zivver with their workplace credentials.

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

To activate SSO in Zivver, this is necessary:

1. You are a Zivver administrator.
2. You have access to AD FS management console on the AD FS server.

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.

   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 this registry key to the AD FS server. 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, type objectGUID in the LDAP Attribute column.
9. Push TAB on your keyboard.

10. Click objectGUID and select it from the drop-down menu.
    

    Selecting objectGUID from the drop-down menu after typing is necessary because objectGUID is not available in the drop-down menu by default. These steps are prone to error. Thus do those steps precisely.

11. In the second row, set Outgoing Claim Type to https://zivver.com/SAML/Attributes/ZivverAccountKey.
    

    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.

12. Click Finish to save the claim rules.

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

14. Choose the Transform an Incoming Claim template.

15. Click Next.

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

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

18. Set Outgoing claim type to Name ID.

19. Set Outgoing name ID format to Email.
    This ensures that the email address of the user is passed as the primary value.

20. Click Finish.
    You have now successfully set up the connection between Zivver and AD FS.

Set up SSO in Zivver

1. Log in to the WebApp.
2. Click the room_preferences Organization Settings icon at the bottom left of your browser window.
3. Go to people_outline User administration.
4. Go to Single Sign-on.
5. Select Automatically.

6. Enter the URL of your organization AD FS federation metadata XML file in the text box under URL.

   Use the PowerShell cmdlet Get-AdfsEndpoint -AddressPath "/FederationMetadata/2007-06/FederationMetadata.xml" on your AD FS server to retrieve the AD FS metadata URL. The URL will probably be built up something like: https://<adfs.organisation_domain.tld>/FederationMetadata/2007-06/FederationMetadata.xml
    
   If your organization only uses AD FS from an internal network, Zivver cannot retrieve 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.

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

8. Click Save.

9. On to of the page, click the key Enable Single sign-on button.
   You can now exempt Zivver 2FA or test SSO.

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 these 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

Do these steps to set the 2FA exemption for AD FS in Zivver:

1. Log in to the WebApp.
2. Click the room_preferences Organization Settings icon at the bottom left of your browser window.
3. Go to people_outline User administration.
4. Go to Single Sign-on.
5. Scroll down to the Zivver 2FA exemptions card.
6. In the Authentication methods to be exempted field, enter these values:
   • urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos
     
   • urn:federation:authentication:windows
7. 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?
4. User: you are immediately redirected to the login screen of your organization.
5. Administrator: you are prompted to choose between your Zivver password and your workplace credentials to log in.
6. 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.
7. 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 with these steps:

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.

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 e-mail address as login name
• Set a custom login name
• Leave login name empty by default

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 is automatically be forwarded to AD FS. If a user logs into AD FS with a User Principal Name (UPN) such as contoso\jdoe, they cannot log in with the prefilled e-mail address. This can be confusing for users. Use these 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 this command to set the email AD attribute as an alternative login name:
   Set-ADFSClaimsProviderTrust -TargetIdentifier "AD AUTHORITY" -AlternateLoginID mail -LookupForests <forest domain> Background information
   

   Substitute <forest domain> 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 start this 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. Then, users can fill in values for their username other than UPNs.

To do this, add document.forms['loginForm'].UserName.value = '$lt;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.

Create shortcut to the WebApp (optional)

Use this link to create a shortcut. With this, the user can directly open the WebApp without a manual login.

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

Add trusted networks to AD FS (optional)

Applies to Windows Server 2012 and Windows Server 2012 R2

If your organization uses AD FS for SSO, you can set that users can log in to Zivver only from within a certain IP range. Do not use Trusted networks 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.