# SSO with Microsoft AD FS

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

01. Open the AD FS Management Console.
02. Click **Add Relying Party Trust** on the right.
03. Choose **Claims aware** if you have a choice between **Claims aware** and **Non-claims aware**.
04. Click **Start**.
05. Select **Import data about the relying party published online or on a local network**.
06. Under **Federation metadata address (host name or URL)**, paste the _Zivver metadata URL_: `https://app.zivver.com/api/sso/saml/meta`.
07. Click **Next**.

Info

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`

08. Choose **Zivver** as name of the integration.
09. 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](https://docs.zivver.com/en/admin/sso/microsoft-adfs.html#set-up-sso-in-ad-fs). Otherwise go to **Trust relationships** \> **Relying Party Trusts** \> **app.zivver.com** \> **Edit Claim Rules…** in the AD FS Management Console.

01. Click **Add Rule…**.
02. Make sure that **Send LDAP Attributes as Claims** is selected.
03. Click **Next**.
04. At **Claim rule name**, enter the name `AD Attributes`.
05. Under **Attribute Store** select **Active Directory**.
06. In the first row, set **LDAP Attribute** to **E-Mail-Addresses**.
07. In the first row, set **Outgoing Claim Type** to **E-Mail Address**.
08. In the second row, type `objectGUID` in the **LDAP Attribute** column.
09. Push **TAB** on your keyboard.
10. Click **objectGUID** and select it from the drop-down menu.

Info

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

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.

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 the name `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 [Zivver WebApp](https://app.zivver.com/).
2. Click **Organization Settings**.
3. Expand **User administration**.
4. Click **Single Sign-on**.
5. Select **Automatically** recommended.
6. Enter the URL of your organization AD FS federation metadata XML file in the text box under **URL**.

Tip

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`

Note

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](https://docs.zivver.com/en/admin/sso/microsoft-adfs-internal-network-only.html) and proceed from there.

7. Click Save.
8. Click  Enable Single sign-on in the top-right corner.

_You can now [exempt Zivver 2FA](https://docs.zivver.com/en/admin/sso/microsoft-adfs.html#zivver-2fa-exemption-optional) or [test SSO](https://docs.zivver.com/en/admin/sso/microsoft-adfs.html#log-in-to-the-webapp-with-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`

Warning

The above Authentication Methods ensure that a user is never asked for 2FA when logging in to Zivver under these Authentication Contexts. Skipping 2FA in this scenario is a possible security risk because users can log in without it. Be prudent before applying these Authentication Methods and analyze the security risks before implementing.

Follow these steps to configure the 2FA exemption for HelloID in Zivver:

1. Log in to the [Zivver WebApp](https://app.zivver.com/).
2. Click **Organization Settings**.
3. Expand **User administration**.
4. Click **Single Sign-on**.
5. Scroll down to the **Zivver 2FA exemptions** card.
6. In the **Authentication methods to be exempted** field, enter:
   - `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 [Zivver WebApp](https://app.zivver.com/).
2. Enter your email address.
3. Depending on your role in Zivver:
   - Users are redirected directly to the organization’s login screen.
   - Administrators can choose between logging in with their Zivver password or workplace credentials.
4. Log in with your organization’s credentials.

_Depending on whether a 2FA exemption applies, you may be prompted for an additional login method. If a 2FA exemption is in place, this step is skipped._
5. Enter your additional login factor.

_You are now logged in to the Zivver WebApp._

## Log in to Outlook with SSO

In the Zivver Office Plugin for Outlook, you can log in via SSO using these steps:

1. Click the **Zivver** tab.
2. Click **Manage accounts**.
3. Click the link _add_circle_ **Add an account**.
4. Enter the email address you want to use for login.
5. Click Next.

_You will be redirected to your organization’s login screen._
6. Log in with your organization’s credentials.

_Depending on whether a 2FA exemption applies, you may be prompted for an additional login method. If a 2FA exemption is in place, this step is skipped._
7. Enter your additional login factor.

_You are now logged in to Outlook._

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

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

Info

These are advanced settings.

[What you need to know before making these changes](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/advanced-customization-of-ad-fs-sign-in-pages#things-to-know-before-you-start).

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](https://docs.zivver.com/en/admin/sso/microsoft-adfs.html#set-up-email-address-as-login-name)
- [Set a custom login name](https://docs.zivver.com/en/admin/sso/microsoft-adfs.html#set-a-custom-login-name)
- [Leave login name empty by default](https://docs.zivver.com/en/admin/sso/microsoft-adfs.html#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](https://app.zivver.com/), your e-mail address is automatically forwarded to AD FS. If a user logs into AD FS with a [User Principal Name](https://docs.microsoft.com/en-us/windows/desktop/ad/naming-properties#userprincipalname) (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:

```powershell
Set-ADFSClaimsProviderTrust -TargetIdentifier "AD AUTHORITY" -AlternateLoginID mail -LookupForests <forest domain>
```

[Background information](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/configuring-alternate-login-id)

Info

Substitute `<forest domain>` with your AD domain.

_Users will now also be able to log in to AD FS using their email address as username._

To remove the alternative login method, start this command:

```powershell
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 = '<clientdomain.local>\<yourusername>'` to the AD FS `onload.js` file.
Use [Example 2 in this Microsoft article](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/advanced-customization-of-ad-fs-sign-in-pages#example-2-accept-sam-account-name-as-a-login-format-on-an-ad-fs-form-based-sign-in-page) as a model.

### Leave login name empty by default

Adjust the AD FS `onload.js` file to leave the `username` field blank by default. To do this, add `document.forms['loginForm'].UserName.value = ''` to the AD FS `onload.js` file.

Use [Example 2 in this Microsoft article](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/advanced-customization-of-ad-fs-sign-in-pages#example-2-accept-sam-account-name-as-a-login-format-on-an-ad-fs-form-based-sign-in-page) 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

Warning

This can affect users’ ability to mail securely. Consider the situation carefully before you proceed.

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](https://app.zivver.com/organization/network-restrictions) 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](https://docs.microsoft.com/en-us/windows-server/identity/ad-fs/operations/access-control-policies-w2k12).