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:

  • Je bent beheerder.

  • Je hebt toegang tot de AD FS management console op de AD FS server.

SSO instellen in ZIVVER

  1. Open je favoriete browser.

  2. Log in op de ZIVVER WebApp.

  3. Klik linksonder in het zijpaneel op de Organisatie-instellingen tune .

  4. Ga naar de pagina Single Sign-On vpn_key .

  5. Voer onder in het tekstvak bij Haal automatisch de SAML metadata op via URL (aangeraden) de AD FS metadata URL in.

    Tip
    Gebruik op de AD FS server het PowerShell cmdlet Get-AdfsEndpoint -AddressPath "/FederationMetadata/2007-06/FederationMetadata.xml om de AD FS metadata URL te achterhalen. De URL zal waarschijnlijk ongeveer in deze vorm opgebouwd zijn: https:///FederationMetadata/2007-06/FederationMetadata.xml
    Note
    Maakt jouw organisatie gebruik van AD FS server welke alleen benaderbaar is vanaf een intern netwerk? Dan kan jouw AD FS server de metadata niet aanleveren via een URL aan ZIVVER, maar alleen via een XML-bestand. Ga naar de handleiding om een AD FS-koppeling in te stellen met ZIVVER voor een interne AD FS server en volg de stappen daar.
  6. Zet onderaan een vinkje voor Gebruik Single sign-on.

  7. Klik op OPSLAAN.

    Note
    ZIVVER is nu ingesteld om te werken met Single Sign-On, maar de koppeling in AD FS is nog niet ingesteld. Wanneer SSO ingeschakeld is in het ZIVVER beheerpaneel, zal ZIVVER altijd gebruikers via SSO proberen in te loggen. Dit kan tot inlogproblemen leiden voor gebruikers die zijn aangemaakt voordat SSO volledig is geconfigureerd omdat AD FS nog niet is ingesteld. Gebruikers blijven wel ingelogd en worden niet uitgelogd wanneer je SSO inschakelt of wijzigt. ZIVVER beheerders kunnen altijd inloggen met een gebruikersnaam en wachtwoord, ook al is AD FS nog niet geconfigureerd voor SSO met ZIVVER.

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. Selecteer Import data about the relying party published online or on a local network.

  6. Plak onder Federation metadata address (host name or URL) de 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 start de server vervolgens opnieuw op.
    Server: WS 2012
    Location: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v2.0.50727
    DWORD name: SchUseStrongCrypto
    Value: 1
    Server: WS 2012 R2; 2016
    Location: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v2.0.50727
    DWORD name: 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 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. Anders ga je naar Relying Party Trusts > ZIVVER > Edit Claim Issuance Policy in de AD FS Management Console om de Claim Rules handmatig te openen.

  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. In de eerste rij, selecteer als LDAP Attribute de waarde E-Mail-Addresses.

  7. In de eerste rij, selecteer als Outgoing Claim Type de waarde E-Mail Address.

  8. In de tweede rij, selecteer als LDAP Attribute de waarde objectGUID.

    Tip
    Selecteer objectGUID uit het dropdown menu. Het overtypen, kopiëren of plakken van de tekst objectGUID werkt niet goed in de AD FS Management Console en resulteert in een ontbrekende objectGUID in de SAML-response.
  9. In de tweede rij, selecteer als Outgoing Claim Type de waarde https://zivver.com/SAML/Attributes/ZivverAccountKey.

    Warning
    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 wordt sterk afgeraden, omdat deze waarden makkelijk te raden zijn.
  10. Klik op Finish om de claim rules op te slaan.

  11. Klik op Add Rule om een tweede claim rule toe te voegen.

  12. Kies voor de template Transform an Incoming Claim.

  13. Klik op Next.

  14. Vul bij Claim rule name een naam in, bijvoorbeeld E-mail transform.

  15. Zet Incoming claim type op E-Mail Address.

  16. Zet Outgoing claim type op Name ID.

  17. Zet Outgoing name ID format op Email.
    Dit zorgt ervoor dat het e-mailadres van de gebruiker als primaire waarde doorgegeven wordt.

  18. Klik op Finish.
    Je hebt nu de koppeling tussen ZIVVER en AD FS succesvol gerealiseerd.

ZIVVER 2FA vrijstelling (optioneel)

Een ZIVVER-account is standaard beveiligd met een extra inlogcode (2FA). Ook bij het inloggen via SSO zal ZIVVER standaard om een 2FA vragen bij inloggen. De 2FA bij het inloggen via SSO kan echter worden vrijgesteld. AD FS kan de Authentication Method doorgeven aan ZIVVER, om aan te tonen dat de inlog veilig genoeg is om geen 2FA te vragen. In de SAML-standaard heet dit Authentication Context.

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

  • urn:oasis:names:tc:SAML:2.0:ac:classes:Kerberos

  • urn:federation:authentication:windows

Warning
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 bedenk vooraf welke veiligheidsrisico’s deze aanpassing met zich mee brengt!

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 met deze twee Authenticatie contexten, 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.

Veld Gebruikersnaam op AD FS inlogpagina aanpassen (optioneel)

Toepasbaar: Windows Server 2012 R2 en Windows Server 2016.

Note
Dit zijn geavanceerde aanpassingen.

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 mail -LookupForests
    Achtergrondinformatie

    Note
    Vervang met het desbetreffende AD domein.
    Na het uitvoeren van het commando kan de gebruiker ook met zijn e-mailadres inloggen in AD FS.

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\\' toe aan de AD FS onload.js.
Gebruik 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.
Gebruik Example 2 als voorbeeld gebruiken van dit Microsoft artikel.

Snelkoppeling naar de WebApp aanmaken (optioneel)

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

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

Vertrouwde netwerken toevoegen aan AD FS (optioneel)

Toepasbaar op Windows Server 2012 R2

Warning
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

Was dit artikel behulpzaam?

thumb_up thumb_down