Page tree
Skip to end of metadata
Go to start of metadata

Inleiding

Het is vaak gewenst dat gebruikers niet op het portal nog een keer een wachtwoord in hoeven te vullen. Om te zorgen dat gebruikers gelijk ingelogd zijn kunt u gebruik maken van SAML 2.0. Dit wordt ondersteund door bijvoorbeeld ADFS en SimpleSAML. Vanaf release 19.12 is hier ook Service Provider initiated sso aan toegevoegd, hetgeen wordt ondersteund door bijvoorbeeld Azure AD.

Het voordeel van deze methode is het gemak voor gebruikers en het feit dat het wachtwoord van de gebruiker niet in een extern systeem ingevuld hoeft te worden.

Overzicht Single Sign-on met SAML2 (Active Directory)

Bij het gebruik van single-sign-on (SSO) via SAML 2.0 is er een externe server (van uw school) die de identiteit van de gebruiker vaststelt en daar voor instaat.

We gebruiken de volgende terminologie:

TermBetekenis
SAMLSecurity Assertion Markup Language, een specificatie van berichten die servers naar elkaar kunnen sturen om de identiteit en rechten van een persoon vast te stellen.
Single-sign-on (SSO)De gebruiker logt één keer in, op een server/systeem van de school, en hoeft daarna verder nergens meer een wachtwoord in te vullen.
Service provider (SP)De partij waar een gebruiker toegang toe wil. In dit geval het Zermelo portal.
Identity provider (IdP)De partij die gebruikers beheert. Bijvoorbeeld Azure AD of OneLogin.
ClaimEen digitaal ondertekend document waarin een identity provider aangeeft wie een gebruiker is.


Het inlog proces kan bij de service provider of de identity provider beginnen. Als het proces bij de service provider begint wordt de gebruiker direct doorgestuurd naar de identity provider met een verzoek om de gebruiker in te loggen. De service provider authenticeert de gebruiker en stuurt de gebruiker weer naar de service provider met een claim. De service provider controleert of de claim correct is ondertekend, en logt de gebruiker in de claim in.

Om dit geheel te laten werken moeten identity provider en service provider een aantal dingen van elkaar weten. U kunt deze gegevens handmatig invullen, of automatisch in laten lezen. Alle instellingen die in Zermelo instelbaar zijn kunnen ook uit metadata ingelezen worden. Welke gegevens een identity provider automatisch in kan lezen verschilt per partij.


Toch via standaardscherm inloggen

Ook als Single Sign-on geactiveerd is kunt u nog via het standaardscherm inloggen. Ga naar https://schoolnaam.zportal.nl?sso=false

Instellingen

Benodigde gegevens voor de identity provider:

GegevenOmschrijvingWaarde
Metadata URL of bestandEen bestand waar de eigenschappen van de service provider in staan. Als de identity provider een bestand wil kunt u de link openen in uw browser en opslaan.https://schoolnaam.zportal.nl/api/v3/oauth/metadata
Entity IDHoe heet de partij die gaat vragen om gebruikers in te loggen.https://schoolnaam.zportal.nl
Assertion Consumer Service URLDe url waar de service provider gebruikers met een ondertekend certificaat ontvangt.https://schoolnaam.zportal.nl/api/v3/oauth/saml
Login URLDe normale inlogpagina van de service provider.https://schoolnaam.zportal.nl/api/v3/oauth
Logout URLDe url waar de identity provider uitgelogde gebruikers heen kan sturen.https://schoolnaam.zportal.nl/api/v3/oauth/logout
Service provider certificaatHet certificaat waarmee de service provider inlog verzoeken ondertekent.abcdef123456...

Kleuren: groen = vult de andere instellingen automatisch in, blauw = verplicht, wit = optioneel

Benodigde gegevens voor de service provider (Zermelo):

Gegeven (blauw=verplicht)Omschrijving
Metadata URLDe url van een bestand waar de eigenschappen van de identity provider staan. Deze gegevens worden op het moment van inloggen dynamisch ingelezen.https://een-identity-provider.nl/saml_metadata
Entity IDHoe heet de partij die gebruikers in gaat loggen.https://een-identity-provider.nl
Single sign-on URLDe url waar gebruikers die willen inloggen heen gestuurd kunnen worden.https://een-identity-provider.nl/saml
Identity provider certificaatCertificaat waarmee de identity provider claims ondertekent.abcdef123456...
BindingDe manier waarop gebruikers doorgestuurd worden naar de identity provider.Voor bestaande configuraties staat Redirect ingesteld. Meestal is POST wenselijker

Kleuren: groen = vraagt de andere instellingen dynamisch op, blauw = verplicht, wit = optioneel

Activeren en afdwingen

Als u SAML2 geactiveerd heeft kunt u nog kiezen in welke situaties u een gebruiker door wil verwijzen.

query parametersSSO forcerenResultaat
-(error)Inlog pagina met een knop Login met Single sign-on 
-(tick)Direct doorverwezen naar identity provider
?sso=true(question)Direct doorverwezen naar identity provider
?sso=false(tick)Inlog pagina met een knop Login met Single sign-on 
?sso=false&hideSso=true(question)Inlog pagina zonder sso knop

Instellen identity provider

Maak in uw identity provider een nieuwe service provider aan. Hieronder staat omschreven hoe dit werkt in Azure AD. In andere systemen zal een soortgelijk proces werken. 

Zermelo biedt een metadata bestand waarin alle gegevens die de identity provider nodig heeft staan. Het verschilt per identity provider welke gegevens precies automatisch uitgelezen kunnen worden.

Instellingen voor de identity provider:


Herkennen van gebruikers

In principe worden gebruikers alleen herkend aan hun emailadres. Dit emailadres moet uniek zijn binnen het portal, en de gebruiker moet Ext. auth. (externe authenticatie) aan hebben staan.

Als u het vinkje Doorverwijzen met redirect (verouderd)  aan heeft staan wordt er in meer velden gezocht:

  1. code
  2. extra gebruikersnaam
  3. emailadres

In de reactie van de identity provider wordt de inlog naam gezocht in het veld NameID, of als ze aanwezig zijn in de attributes "mail" of "email".

Stappenplan instellen Azure AD

Open uw Microsoft Azure portal.

Stap 1: Aanmaken

Kies in Azure voor Azure Active Directory > Enterprise applications  en klik op <New application >

Het opzetten van de koppeling in App services is op dit moment niet mogelijk.


Kies voor <Non-gallery application> en geef deze nieuwe applicatie bijvoorbeeld de naam zermelo

           


Klik op <add >  en kies 2. Set up single sign on en vervolgens > SAML

>


Stap 2: configuratie in Azure

Uit het zermelo portal kunt u een metadatafile opslaan. In uw browser kunt u de volgende link openen: https://schoolnaam.zportal.nl/api/v3/oauth/metadata (waarbij u uiteraard uw eigen portalnaam invoert). U krijgt een soortgelijke output:

Sla deze link op als "Web Page, XML only".

Dit bestand kunt u in Azure importeren <Upload metadata file>.


Voeg vervolgens bij Users and Groups de gebruikers (leerlingen, docenten en eventueel ouders) toe, die het portal met Single Sign-on mogen bereiken.

Stap 3: configuratie in het Zermelo Portal

Kopieer in Azure de App Federation Metadata Url:


En open nu in uw Zermelo portal Beheer > Admin-paneel > Saml Single Sign-on.

Plak in Metadata > Identity provider metadata URL deze uit Azure afkomstige URL.

En zet vervolgens het vinkje bij Activeren > SAML2 SSO gebruiken.

U kunt hier eventueel de Zermelo logout URL kopiëren en invoeren in Azure onder 1. Basic SAML Configuratie om er voor te zorgen dat uitloggen bij Zermelo de gebruiker ook uitlogt bij Azure.


Wanneer u de drie stappen doorlopen heeft is de inrichting voltooid. In beide applicaties kunt u deze testen.


Stappenplan instellen ADFS

Maak een nieuwe Relying Party Trust met de volgende eigenschappen. Op de tabbladen die hier niet bij staan wordt niets ingevuld.

Deze zijn waarschijnlijk niet alle drie nodig.

Nu gaan we naar het tabblad endpoints:

We selecteren het endpoint en klikken op Edit...

We sluiten dit scherm en bewerken dan de Claim Rules:

Als je nummer 1 edit:

En als laatste binnen ADFS:

De standaard URL voor ADFS metadata is https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml. Vul deze URL in, en activeer SAML2 SSO gebruiken.