SSO met Microsoft AD FS

Inleiding

ZIVVER ondersteunt Single Sign-On (SSO) via Microsoft AD FS, zodat gebruikers met de inloggegevens van hun werkplek in ZIVVER kunnen inloggen. Deze handleiding legt uit hoe je als beheerder SSO instelt.

SSO werkt op basis van Security Assertion Markup Language (SAML). Hierbij is AD FS de Identity Provider (IdP) en ZIVVER de Service Provider (SP).

Om SSO in ZIVVER te kunnen activeren, heb je de volgende zaken nodig:

SSO instellen in ZIVVER

De eerste stap is om SSO in ZIVVER in te stellen. Dit doe je in de WebApp van ZIVVER. Je hebt beheerdersrechten nodig. 1. Open je browser. 2. Vul de URL van je AD FS-server in de adresbalk in, gevolgd door /FederationMetadata/2007-06/FederationMetadata.xml
(b.v.: https://<adfs.organisatie.nl>/FederationMetadata/2007-06/FederationMetadata.xml).
Het bestand word op je computer opgeslagen. 4. Open het bestand in een teksteditor (bijvoorbeeld Kladblok). 5. Kopieer de volledige inhoud van het bestand naar het klembord. 6. Log in op de ZIVVER WebApp. 7. Klik linksonder in het zijpaneel op de Organisatie-instellingen tune . 8. Ga naar de pagina Single Sign-On vpn_key . 9. Plak de inhoud van het FederationMetaData-bestand in het tekstvak onder Identity Provider XML. 10. Zet onderaan een vinkje voor Zet SSO aan. 11. Klik op OPSLAAN. 12. Klik op Download Metadata om een bestand met informatie over de SAML-verbinding vanuit ZIVVER te downloaden. Dit heb je nodig bij de volgende stap. _You have now properly set up ZIVVER to use Single Sign-On. The next and final procedure is to enter the correct settings in the AD FS Management Console.

Waarschuwing

ZIVVER zal altijd via SSO proberen gebruikers in te loggen wanneer SSO aan staat. Dit kan tot inlogproblemen leiden bij gebruikers wanneer SSO niet is ingericht in AD FS. Schakel SSO tijdelijk uit tot dat SSO in AD FS staat ingesteld. Gebruikers blijven ingelogd wanneer je SSO inschakelt.

SSO instellen in AD FS

  1. Open de AD FS Management Console.
  2. Klik aan de rechterkant op Add Relying Party Trust.
  3. Kies voor Claims aware wanneer je een keuze hebt tussen Claims aware en Non-claims aware.
  4. Klik op Start.
  5. Kies voor Import data about the relying party published online or on a local network OF Kies Import data about the replying party from a file en selecteer het bestand dat u hebt gedownload in stap 12 van SSO instellen in ZIVVER en ga verder vanaf stap 7. hieronder.
  6. Plak onder Federation metadata address (host name or URL) https://app.zivver.com/api/sso/saml/meta.
  7. Klik op Next.
    Tip

    Zie je de foutmelding “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 […]”? Voeg de volgende registersleutel toe aan de AD FS server en reboot vervolgens de server.
    Location: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft.NETFramework\v4.0.30319
    DWORD Value: SchUseStrongCrypto
    Value: 1
    Achtergrondinformatie

  8. Geef ZIVVER op als naam voor de integratie.
  9. Klik op Next.
  10. Kies een Access Control Policy of kies anders voor Permit everyone.
    Met een Access Control Policy stel je in dat alleen gebruikers van een specifieke gebruikersgroep toegang hebben tot ZIVVER.
  11. Klik op Next.
    Je ziet een samenvatting van de ingestelde AD FS-koppeling.
  12. Controleer of alles goed staat ingesteld.
  13. Klik op Next.
  14. Laat bij Open the Edit Claim Rules dialog het vinkje staan.
  15. Klik op Close.

Claim Rules instellen

ZIVVER moet informatie over de gebruiker uit de AD FS ophalen. Hiervoor moet je in de AD FS Management Console de Claim Rules instellen. Deze regels vertalen attributen uit de AD FS naar waarden die ZIVVER kan lezen en gebruiken. Als je net een AD FS-koppeling hebt aangemaakt, kom je vanzelf in het Edit Claim Issuance Policy scherm.
Zie je dit niet? Ga dan naar: Relying Party Trusts > app.zivver.com > Edit Claim Issuance Policy.

  1. Klik op Add Rule.
  2. Zorg dat Send LDAP Attributes as Claims is geselecteerd.
  3. Klik op Next.
  4. Vul bij Claim rule name een naam in, bijvoorbeeld AD Attributen.
  5. Kies onder Attribute Store voor Active Directory.
  6. Vul in het schema daaronder de volgende attributen in:
    • LDAP Attribute: ObjectGUID – Outgoing Claim Type: https://zivver.com/SAML/Attributes/ZivverAccountKey
    • LDAP Attribute: E-Mail Addresses – Outgoing Claim Type: E-Mail Address
      Waarschuwing

      ZIVVER gebruikt ZivverAccountKey in het encryptieproces. Het is daarom belangrijk dat het nummer lang, uniek en willekeurig is. Bij voorkeur is dit nummer zelf gegenereerd en wordt het niet gebruikt in andere koppelingen of systemen.
      Als het niet mogelijk is om dit nummer zelf te genereren, dan is objectGUID een alternatief. Dit nummer wordt echter vaak gebruikt in andere koppelingen en vormt daarmee een veiligheidsrisico. Het gebruik van ObjectSID of andere AD-attributen raden we sterk af, omdat deze waarden makkelijk te raden zijn.


  7. Klik op Finish om de claim rules op te slaan.
  8. Klik op Add Rule om een tweede claim rule toe te voegen.
  9. Kies voor de template Transform an Incoming Claim.
  10. Klik op Next.
  11. Vul bij Claim rule name een naam in, bijvoorbeeld E-mail transform.
  12. Stel nu de volgende transformatie in:
    1. Zet Incoming claim type op E-Mail Address.
    2. Zet Outgoing claim type op Name ID.
    3. Zet Outgoing name ID format op Email.
      Dit zorgt ervoor dat het e-mailadres van de gebruiker als primaire waarde doorgegeven wordt.
  13. Klik op Finish.

Je hebt nu de koppeling tussen ZIVVER en AD FS succesvol gerealiseerd!

Authentication Methods

Een ZIVVER-account is standaard beveiligd met een extra inlogcode (2FA). Ook bij het inloggen via SSO is 2FA vereist. AD FS kan de Authentication Method doorgeven aan ZIVVER, om daarmee de vereiste 2FA af te vangen. In de SAML-standaard heet dit Authentication Context.

Bij de volgende Authentication Methods vraagt ZIVVER bij het inloggen niet om een 2FA:

Waarschuwing

De bovenstaande Authentication Methods zorgen ervoor dat er nooit om 2FA wordt gevraagd bij het inloggen in ZIVVER. Dit is een mogelijk veiligheidsrisico omdat gebruikers nu mogelijk in ZIVVER kunnen inloggen zonder 2FA. Wees vooraf voorzichtig met het toepassen van deze Authentication Methods en denk na over de mogelijke consequenties!

Volg onderstaande stappen om de 2FA vrijstelling voor AD FS in ZIVVER in te stellen:

  1. Log in op de ZIVVER WebApp.
  2. Klik linksonder op de organisatie-instellingen tune .
  3. Klik op Single Sign-On (SSO) vpn_key .
  4. Vul in het veld SAML 2.0 authenticatiecontexten met ZIVVER 2FA vrijstellingen de volgende waarden in:
    • urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos
    • urn:federation:authentication:windows
  5. Klik op OPSLAAN.
    Je hebt nu succesvol een 2FA vrijstelling ingesteld voor AD FS. Wanneer gebruikers nu inloggen via SSO, zal ZIVVER niet om 2FA vragen.

Inloggen in de WebApp met SSO

  1. Ga naar de WebApp.
  2. Vul je e-mailadres in.
  3. Wat is je rol in ZIVVER?
    • Gebruiker: je wordt direct omgeleid naar het inlogscherm van jouw organisatie.
    • Beheerder: je kiest tussen je ZIVVER-wachtwoord en je werkplekinloggegevens om in te loggen.
  4. Log in met de werkplekinloggegevens van jouw organisatie.
    Afhankelijk van een 2FA vrijstelling word je gevraagd om een extra inlogmethode. Bij een 2FA vrijstelling sla je de laatste stap over.
  5. Vul je extra inlogmethode in.
    Je bent ingelogd in onze WebApp.

Inloggen in Outlook met SSO

In de ZIVVER Office Plugin in Outlook log je op de volgende manier in met SSO:

  1. Klik op het tabblad ZIVVER.
  2. Klik op Accounts beheren account_circle .
  3. Klik op de link Voeg een account toe add_circle .
  4. Selecteer het e-mailadres waarmee je wilt inloggen.
  5. Klik op Ja, ik wil nu inloggen.
    Je wordt omgeleid naar het inlogscherm van je organisatie.
  6. Log in met de werkplekinloggegevens van je organisatie.
    Afhankelijk van een 2FA vrijstelling word je gevraagd om een extra inlogmethode. Bij een 2FA vrijstelling sla je de laatste stap over.
  7. Vul je extra inlogmethode in.
    Je bent ingelogd in Outlook.

[Optioneel] Veld Gebruikersnaam op AD FS inlogpagina aanpassen

Toepasbaar: Windows Server 2012 R2 en Windows Server 2016.

Dit zijn geavanceerde aanpassingen.
Lees hier wat je moet weten voordat je deze aanpassingen doorvoert!

AD FS ondersteunt het aanpassen van de inlogervaring op Windows Server 2012 R2 en Windows Server 2016. Hieronder staan drie mogelijkheden aangegeven om het veld Gebruikersnaam aan te passen op de AD FS inlogpagina.

E-mailadres als inlognaam instellen

ZIVVER gebruikt het e-mailadres als inlognaam. Als je inlogt op de WebApp dan wordt je e-mailadres automatisch doorgegeven aan AD FS. Als een gebruiker inlogt in AD FS met een User Principal Name (UPN) zoals contoso\jdoe, dan kan hij niet inloggen met het vooraf ingevulde e-mailadres. Dit kan verwarrend zijn voor gebruikers. Met de volgende stappen stel je AD FS zo in dat ook het e-mailadres als inlognaam wordt geaccepteerd:

  1. Open Powershell op de primaire AD FS server.
  2. Gebruik het volgende commando om een AD-attribuut als alternatief inlognaam in te stellen:
    Set-ADFSClaimsProviderTrust -TargetIdentifier "AD AUTHORITY" -AlternateLoginID <attribute> -LookupForests <forest domain>
    achtergrondinformatie
  3. Geef als <attribute> op mail.
  4. Geef als <forest domain> het desbetreffende AD-domein op.
  5. Na het uitvoeren van het commando kan de gebruiker ook met zijn e-mailadres inloggen in AD FS.
  6. Met het volgende commando verwijder je het alternatief inlognaam weer:
    Set-ADFSClaimsProviderTrust -TargetIdentifier "AD AUTHORITY" -AlternateLoginID $NULL -LookupForests $NULL

Aangepaste inlognaam instellen

Pas de AD FS onload.js aan om een aangepaste inlognaam in te stellen. Zo kan je het veld Gebruikersnaam invullen met een andere waarde dan bijvoorbeeld UPN. Voeg hiervoor document.forms['loginForm'].UserName.value = 'klantdomein.local\\uwgebruikersnaam' toe aan de AD FS onload.js. Je kan Example 2 als voorbeeld gebruiken van dit Microsoft artikel.

Inlognaam standaard leeg laten

Pas de AD FS onload.js aan om het veld Gebruikersnaam standaard leeg te laten. Voeg hiervoor document.forms['loginForm'].UserName.value = '' toe aan de AD FS onload.js. Je kan Example 2 als voorbeeld gebruiken van dit Microsoft artikel.

[Optioneel] Snelkoppeling naar de WebApp aanmaken

Gebruik onderstaande link om een snelkoppeling aan te maken, waarmee de gebruiker direct de WebApp kan openen zonder handmatig in te moeten loggen:

https://adfs.organisatie.nl/adfs/ls/idpinitiatedsignon.aspx?logintorp=https://app.zivver.com/SAML/Zivver

Vervang het deel https://adfs.organisatie.nl door de URL van de AD FS-server.

[Optioneel] Vertrouwde netwerken toevoegen aan AD FS

Toepasbaar op Windows Server 2012 en Windows Server 2012 R2

Waarschuwing

Bepaal voor het instellen of het wenselijk is om gebruikers te beperken in de mogelijkheid om veilig te e-mailen!

Als jouw organisatie gebruik maakt van AD FS voor SSO kan je instellen dat gebruikers alleen kunnen inloggen in ZIVVER binnen een bepaalde IP-range. Wij raden het gebruik van vertrouwde netwerken in ZIVVER sterk af als je ook gebruik maakt van SSO. Stel daarom de IP-range in in AD FS. Lees hier hoe je vertrouwde netwerken instelt in AD FS