Huidige versie van 28 aug 2023 om 09:54

Inleiding

Entree Federatie wordt gevormd door aanbieders van een educatieve dienst of content (Service Providers), beheerders van identiteiten (Identity Providers) en de applicatie van Kennisnet (Entree Federatie). Samen geven zij gebruikers in het po, vo en mbo toegang tot een groot aantal educatieve diensten met slechts één login (ook wel bekend als Single Sign On of SSO).

Een Identity Provider is de applicatie die voor de school de communicatie met Entree Federatie verzorgt.
De applicatie van Entree Federatie fungeert als het centrale knooppunt waarlangs alle federatieve authenticatie berichten worden afgehandeld. Dit wordt ook wel een federatieve intermediair of hub genoemd.
Een Service Provider is de webapplicatie van een aanbieder van een dienst die gericht is op het onderwijs of educatieve content.

Twee stappen staan in dit proces centraal:

Authenticatie: het vaststellen van de identiteit van de gebruiker.
Autorisatie: op basis van de kenmerken van de gebruiker toegang verlenen tot een dienst of bepaalde content.

De authenticatie wordt door Entree Federatie afgehandeld, de autorisatie wordt door de Service Provider uitgevoerd.

Om een gebruiker te authenticeren worden XML berichten tussen de verschillende partijen uitgewisseld op basis van de open SAML 2.0 standaard (Security Assertion Markup Language). Een technische beschrijving van het authenticatie proces door middel van het SAML 2.0 protocol staat beschreven op Hoe werkt Entree Federatie?

Voorbereiding

Voor het aansluiten op Entree Federatie is het belangrijk om de volgende punten te overwegen:

Welke attributen (persoonsgegevens) heb ik nodig om een gebruiker te kunnen autoriseren?
Welke software library ga ik gebruiken voor het implementeren van de SAML functionaliteit?
Wil ik gebruik maken van aanvullende functionaliteit als: Single Sign On query, scoping of forced authentication?
Sta ik alleen federatieve accounts toe of ook Entree Accounts?

Uiteraard kan je tijdens de voorbereiding contact opnemen met Kennisnet voor meer informatie of als je vragen hebt.

Attributenbeleid

Tijdens het authenticatieproces ontvangt de applicatie van de Service Provider persoonsgegevens van de gebruiker in de vorm van attributen. Dit heeft als doel het identificeren en autoriseren van de persoon die gebruik wil maken van jouw applicatie. Binnen Entree Federatie wordt onderscheid gemaakt tussen twee typen attributen:

Standaard attributen: worden door alle Service Providers ontvangen
Aanvullende attributen: worden alleen ontvangen na expliciete toestemming van de onderwijsinstelling middels een Attribute Release Policy (ARP).

Een overzicht van de attributen is te vinden op de pagina Attributen overzicht voor Service Providers. Een Service Provider die gebruik maakt van aanvullende attributen en dus een ARP van de onderwijsinstelling nodig heeft is zelf verantwoordelijk voor het informeren van de onderwijsinstelling en het verspreiden van het ARP formulier.

Per 25 mei 2018 is de Algemene verordening gegevensbescherming (AVG) van toepassing. Hiermee worden de privacyrechten van gebruikers versterkt en de verantwoordelijkheden van organisaties vergroot. Een belangrijk uitgangspunt binnen deze wetgeving is Privacy by default. Dit houdt in dat u technische en organisatorische maatregelen moet nemen om ervoor te zorgen dat u alléén persoonsgegevens verwerkt die noodzakelijk zijn voor het specifieke doel dat u wilt bereiken. Gebruik dus alleen attributen die functioneel essentieel zijn voor de autorisatie van de gebruiker en de werking van de applicatie.

Software library

Voor het implementeren van authenticatie door middel van SAML 2.0 zijn verschillende software libraries beschikbaar. De keuze voor één van deze libraries is vooral afhankelijk van de gebruikte ontwikkeltaal en persoonlijke voorkeur. Voor een aantal veel gebruikte libraries staan handleidingen op deze wiki. Voor het aansluiten op Entree Federatie worden geen specifieke libraries voorgeschreven door Kennisnet. Het is dus aan de dienstaanbier / ontwikkelaar om hier een keuze in te maken.

Single Sign On in mobiele apps

Entree Federatie maakt gebruik van het SAML 2.0 protocol voor authenticatie. Dit protocol is ontworpen voor gebruik in een browser en hierdoor is voor de werking een backend applicatie nodig aan de kant van de Service Provider. Deze applicatie verzorgd de onderliggende communicatie, waarbij tenminste een metadata bestand op een publieke URL beschikbaar is gesteld en een HTTP-POST API beschikbaar is. Dit zijn componenten die niet aansluiten bij de standaardfunctionaliteiten / standaardarchitectuur van een native mobiele applicatie.

Entree Federatie zal voor het authenticatie proces direct met de backend applicatie van de Service Provider communiceren. De mobiele applicatie communiceert vervolgens als een 'client' met de backend applicatie van de Service Provider. De native mobiele applicatie kan gebruik maken van een zogenaamde WebView. Dit is een implementatie van een browser engine binnen de applicatie, zonder dat hierbij standaard browserelementen als de navigatiebalk worden getoond.

Beperkte Single Sign On

Single Sign On zorgt ervoor dat een gebruiker binnen één sessie kan inloggen in meerdere applicatie. Op zowel iOS als Android zijn er beperkingen in het delen van sessies. Het is vanuit veiligheidsoverwegingen niet mogelijk om een sessie te delen met applicaties die niet door dezelfde ontwikkelpartij gemaakt zijn.

Het is op deze wijze echter wel mogelijk om gebruikers via Entree Federatie in de app in te laten loggen met hun federatieve schoolaccount.

Aanvullende functionaliteit

In bepaalde use cases kan een dienstaanbieder er voor kiezen om één van de onderstaande functionaliteiten te implementeren. Deze kunnen het authenticatieproces verbeteren en/of vereenvoudigen.

SSO query

Deze functie biedt de mogelijkheid om te controleren of een gebruiker direct ingelogd kan worden zonder het inlogscherm te tonen. Kijk voor meer informatie op: SSO query

Scoping

In sommige gevallen is het al bekend welke Identity Provider de gebruiker zal gebruiken om zich via Entree Federatie te authenticeren. Dit kan zijn omdat de applicatie van de dienstaanbieder bijvoorbeeld voor een specifieke school is ingericht of omdat de gebruiker in de applicatie van de dienstaanbieder zijn school heeft geselecteerd. In deze gevallen kan er gebruik gemaakt worden van scoping.

In het authenticatie verzoek dat de dienstaanbieder naar Entree Federatie verstuurd wordt de identifier van de Identity Provider meegegeven. Hierdoor kan de gebruiker gelijk worden doorgestuurd naar de Identity Provider en hoeft hij geen school meer te selecteren op het WAYF-scherm (Where Are You From) van Entree Federatie.

Forced authentication

Eén van de voordelen van inloggen via een federatie is, dat als een gebruiker is ingelogd bij een aangesloten dienst en vervolgens een andere aangesloten dienst bezoekt, hij automatisch opnieuw wordt geauthentiseerd en ingelogd. In sommige usecases is automatische herauthenticatie echter niet wenselijk. Denk hierbij aan administratiesystemen of een webapplicatie waarmee betalingen verricht kunnen worden. In deze gevallen kan gebruik gemaakt worden van forced authentication. Ook als de gebruiker al een lopende SSO sessie heeft (de gebruiker is al bij een andere dienst ingelogd via Entree Federatie), zal hij gevraagd worden nogmaals in te loggen als de Service Provider gebruik maakt van forced authentication

Forced authentication levert meer veiligheid op, maar gaat gelijkertijd ten koste van gebruiksgemak. Iedere dienst zal hierin zelf een afweging moeten maken.

Federatieve accounts en Entree Accounts

Binnen Entree Federatie worden twee soorten accounts onderscheiden:

Federatieve accounts: Dit zijn accounts die de gebruiker van zijn school heeft gekregen. Ze worden daarom ook wel schoolaccounts genoemd. De persoonsgegevens worden door de school beheerd en tijdens het authenticatie proces vraagt Entree Federatie deze gegevens op bij de Identity Provider van de school.
Entree accounts: Omdat er ook gebruikers zijn die geen schoolaccount hebben, heeft Kennisnet een eigen Identity Provider, Entree Account. Hier kan iedereen met een geldig e-mailadres een account aanmaken. Deze accounts bevatten minder persoonsgegevens en ze zijn ook niet geverifieerd. Daarom zijn er dienstaanbieders die ervoor kiezen om authenticatie middels een Entree Account niet toe te staan.

Neem contact op met Kennisnet wanneer je geen authenticaties via Entree Accounts wilt toestaan.

Implementatie

Nadat de voorbereiding is afgerond kan worden begonnen aan de implementatie van de koppeling met Entree Federatie. Dit zal ten eerste bestaan uit het installeren en configureren van de SAML 2.0 software library voor het de communicatie met de applicatie van Entree Federatie. Ten tweede zal er een integratie moeten plaatsvinden van de SAML 2.0 library met de eigen applicatie. Dit laatste valt buiten de scope van de ondersteuning van Kennisnet en wordt dus ook niet beschreven in de documentatie op deze wiki.

Entree Federatie beschikt over een staging en een productie omgeving, de software op deze omgevingen is identiek. Tijdens het implementeren van de koppeling kan gebruik gemaakt worden van de staging omgeving. De productie omgeving is alleen bedoeld voor het koppelen met productie applicaties en dus niet voor test doeleinden.

Aandachtspunten inrichten server

Voor het inrichten van de server zijn een aantal algemene aandachtspunten waar rekening mee gehouden moet worden:

Voor de communicatie met de staging omgeving van Entree Federatie mag via een http verbinding verlopen, zodat ook lokale ontwikkel- en testomgevingen gebruikt kunnen worden. Voor een koppeling met de productie omgeving is https een vereiste.
De server mag maximaal één minuut achterlopen of vijf minuten voorlopen. Maak daarom gebruik van Network Time Protocol (NTP) om de tijd op de server te synchroniseren.
Alle verstuurde XML berichten moeten worden gesigned, momenteel wordt hiervoor alleen SHA-2 versleuteling ondersteund. Voor het signen van berichten kan een self-signed certificaat gebruikt worden.

Uitwisseling metadata

Voor het configureren van de SAML 2.0 software heb je de metadata van Entree Federatie nodig, deze is op de volgende URL's te vinden:

Entree Federatie staging: https://engine.entree-s.kennisnet.nl/authentication/idp/metadata
Entree Federatie productie: https://engine.entree.kennisnet.nl/authentication/idp/metadata

Tijdens de configuratie van de software library wordt er ook een metadata bestand gegenereerd. Zorg ervoor dat dit bestand op een publieke URL beschikbaar is. Gedurende de configuratie moet ook een zogenaamd entityID worden opgegeven. Dit is de identifier van de Service Provider en deze moet uniek zijn binnen Entree Federatie. Om te zorgen dat het entityID uniek is kan daarom het beste de URL van de eigen webapplicatie gebruikt worden.

Als je de installatie en configuratie hebt afgerond geef je deze URL door aan Kennisnet. Vervolgens zal Kennisnet de koppeling in de Entree Federatie applicatie configureren. Wanneer deze configuratie is afgerond kan de koppeling getest worden.

NameIDFormat

De NameIDFormat moet de volgende waarde bevatten: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified NameIDFormat geeft aan een Identity Provider (IdP) de opdracht om de NameID (gebruikersidentificatie) terug te geven in een specifiek formaat. Een Service Provider (SP) kan een specifiek NameID-format aanvragen in het AuthnRequest door het gebruik van het NameIDPolicy - Format element. Of deze aanvraag wordt ingewilligd, is afhankelijk van het beleid.

Testen van de koppeling

Voor het testen kan gebruik gemaakt worden van de Referentie Identity Provider van Entree Federatie. Met behulp van deze applicatie wordt het inloggen van een gebruiker via bijvoorbeeld een Elektronische Leeromgeving gesimuleerd. Het testscenario staat beschreven op: Service provider koppeling testen. Mocht je tijdens het testen tegen foutmeldingen aanlopen neem dan contact op met Kennisnet.

Integratie

Nu de koppeling technisch werkt is het zaak om deze functionaliteit te integreren in de eigen applicatie. Aangezien iedere applicatie uniek is kan Kennisnet in deze fase geen ondersteuning bieden.
Voor het plaatsen van een inlog knop op je website hebben we beeldmateriaal beschikbaar. Hiermee streven we naar uniformiteit bij alle aangesloten websites. Voor eindgebruikers wordt het daarmee duidelijker wanneer ze via Entree Federatie kunnen inloggen.

Overeenkomst

Nu de koppeling op staging geconfigureerd, getest en geïntegreerd is, wordt er een overeenkomst afgesloten tussen de dienstaanbieder en Entree Federatie. Kennisnet zal hiervoor het contract versturen naar de tekenbevoegd administratief contactpersoon van de dienstaanbieder. Nadat Kennisnet de overeenkomst getekend retour heeft ontvangen kan de koppeling met de productie omgeving van Entree Federatie aangemaakt worden.

Livegang

Voor de livegang worden dezelfde technische stappen doorlopen als voor de koppeling met de staging omgeving:

Inrichten en configuratie van de eigen productie omgeving
Uitwisseling van de metadata
Configuratie van de koppeling door Kennisnet
Testen van de koppeling

Ten slotte kan op de website van Kennisnet eenmalig een bericht geplaatst worden over de nieuwe aansluiting. Hiervoor moet een korte beschrijving van de dienst aangeleverd worden.

@@ Regel 1: / Regel 1: @@
+{{Talen}}
-==Introductie==
+<br/>
+__TOC__
+=Inleiding=
-Deze handleiding legt uit hoe je kunt koppelen met Entree Federatie als Service Provider via SAML 2.0.
+Entree Federatie wordt gevormd door aanbieders van een educatieve dienst of content ('''Service Providers'''), beheerders van identiteiten ('''Identity Providers''') en de applicatie van Kennisnet ('''Entree Federatie'''). Samen geven zij gebruikers in het po, vo en mbo toegang tot een groot aantal educatieve diensten met slechts één login (ook wel bekend als '''Single Sign On''' of '''SSO''').
+* Een Identity Provider is de applicatie die voor de school de communicatie met Entree Federatie verzorgt.
+* De applicatie van Entree Federatie fungeert als het centrale knooppunt waarlangs alle federatieve authenticatie berichten worden afgehandeld. Dit wordt ook wel een federatieve intermediair of hub genoemd.
+* Een Service Provider is de webapplicatie van een aanbieder van een dienst die gericht is op het onderwijs of educatieve content.
+[[File:Entree_Federatie_overview.png|600px|left]]<br clear="all">
+Twee stappen staan in dit proces centraal:
-=== Beschrijving Entree Federatie ===
+* '''Authenticatie:''' het vaststellen van de identiteit van de gebruiker.
+* '''Autorisatie:''' op basis van de kenmerken van de gebruiker toegang verlenen tot een dienst of bepaalde content.
+De authenticatie wordt door Entree Federatie afgehandeld, de autorisatie wordt door de Service Provider uitgevoerd.
+Om een gebruiker te authenticeren worden XML berichten tussen de verschillende partijen uitgewisseld op basis van [https://wiki.oasis-open.org/security de open SAML 2.0 standaard] ('''S'''ecurity '''A'''ssertion '''M'''arkup '''L'''anguage). Een technische beschrijving van het authenticatie proces door middel van het SAML 2.0 protocol staat beschreven op [[KNF:Hoe_werkt_Entree_Federatie%3F | Hoe werkt Entree Federatie?]]
-Entree Federatie fungeert als hub tussen alle aangesloten Service Providers (SP) en alle Identity Providers (IdP). Hieronder staat schematisch weergegeven wat de rol van Entree Federatie is.
+=Voorbereiding=
-[[Bestand:authenticatie.jpg]]
+Voor het aansluiten op Entree Federatie is het belangrijk om de volgende punten te overwegen:
+# Welke attributen (persoonsgegevens) heb ik nodig om een gebruiker te kunnen autoriseren?
+# Welke software library ga ik gebruiken voor het implementeren van de SAML functionaliteit?
+# Wil ik gebruik maken van aanvullende functionaliteit als: Single Sign On query, scoping of forced authentication?
+# Sta ik alleen federatieve accounts toe of ook Entree Accounts?
+Uiteraard kan je tijdens de voorbereiding contact opnemen met Kennisnet voor meer informatie of als je vragen hebt.
+==Attributenbeleid==
-# Een gebruiker gaat naar de dienst (SP) om in te loggen
+Tijdens het authenticatieproces ontvangt de applicatie van de Service Provider persoonsgegevens van de gebruiker in de vorm van attributen. Dit heeft als doel het identificeren en autoriseren van de persoon die gebruik wil maken van jouw applicatie. Binnen Entree Federatie wordt onderscheid gemaakt tussen twee typen attributen:
-# De dienst stuurt de gebruiker naar Entree Federatie om te authentiseren.
+* Standaard attributen: worden door alle Service Providers ontvangen
-# Entree Federatie bepaalt de organisatie (IdP) waar de gebruiker bij hoort via het WAYF inlogscherm (Where are you from), of via het uitlezen van het SSO cookie.
+* Aanvullende attributen: worden alleen ontvangen na expliciete toestemming van de onderwijsinstelling middels een Attribute Release Policy (ARP).
-# De IdP wordt gekozen.
+Een overzicht van de attributen is te vinden op de pagina [[KNF:Attributen_overzicht_voor_Service_Providers | Attributen overzicht voor Service Providers]]. Een Service Provider die gebruik maakt van aanvullende attributen en dus een ARP van de onderwijsinstelling nodig heeft is zelf verantwoordelijk voor het informeren van de onderwijsinstelling en het verspreiden van het ARP formulier.
-# Entree Federatie stuurt de gebruiker naar de IdP
-# De IdP authentiseert de gebruiker en stuurt de gebruiker terug naar Entree Federatie met een set attributen (persoonsgegevens).
-# Entree Federatie controleert het resultaat, en bepaalt welke attributen mogen worden doorgestuurd naar de SP o.b.v. de ARP (Attribute Release Policy) en stuurt dit door naar de SP.
-# De SP verwerkt het resultaat, de gebruiker is nu ingelogd.
+Per 25 mei 2018 is de [https://autoriteitpersoonsgegevens.nl/nl/onderwerpen/avg-nieuwe-europese-privacywetgeving/algemene-informatie-avg Algemene verordening gegevensbescherming (AVG)] van toepassing. Hiermee worden de privacyrechten van gebruikers versterkt en de verantwoordelijkheden van organisaties vergroot. Een belangrijk uitgangspunt binnen deze wetgeving is '''Privacy by default'''. Dit houdt in dat u technische en organisatorische maatregelen moet nemen om ervoor te zorgen dat u alléén persoonsgegevens verwerkt die noodzakelijk zijn voor het specifieke doel dat u wilt bereiken. Gebruik dus alleen attributen die functioneel essentieel zijn voor de autorisatie van de gebruiker en de werking van de applicatie.
-=== Staging en productie omgeving ===
+==Software library==
-De productie omgeving is alleen bedoeld voor productie omgevingen en is niet bedoeld voor test doeleinde.
+Voor het implementeren van authenticatie door middel van SAML 2.0 zijn verschillende software libraries beschikbaar. De keuze voor één van deze libraries is vooral afhankelijk van de gebruikte ontwikkeltaal en persoonlijke voorkeur. Voor een aantal veel gebruikte libraries staan handleidingen op deze wiki. Voor het aansluiten op Entree Federatie worden geen specifieke libraries voorgeschreven door Kennisnet. Het is dus aan de dienstaanbier / ontwikkelaar om hier een keuze in te maken.
+==Single Sign On in mobiele apps==
-De software van de staging omgeving is identiek aan de productie omgeving en kan gebruikt worden voor ontwikkelpartijen om tegen te testen.
+Entree Federatie maakt gebruik van het SAML 2.0 protocol voor authenticatie. Dit protocol is ontworpen voor gebruik in een browser en hierdoor is voor de werking een backend applicatie nodig aan de kant van de Service Provider. Deze applicatie verzorgd de onderliggende communicatie, waarbij tenminste een metadata bestand op een publieke URL beschikbaar is gesteld en een HTTP-POST API beschikbaar is. Dit zijn componenten die niet aansluiten bij de standaardfunctionaliteiten / standaardarchitectuur van een native mobiele applicatie.
+Entree Federatie zal voor het authenticatie proces direct met de backend applicatie van de Service Provider communiceren. De mobiele applicatie communiceert vervolgens als een 'client' met de backend applicatie van de Service Provider. De native mobiele applicatie kan gebruik maken van een zogenaamde WebView. Dit is een implementatie van een browser engine binnen de applicatie, zonder dat hierbij standaard browserelementen als de navigatiebalk worden getoond.
-=== Implementatie voorbereiding ===
+===Beperkte Single Sign On===
-# Bepaal hoe je wilt koppelen met Entree Federatie, op de  wiki staan meerdere standaard pakketten die gebruikt kunnen worden.
+Single Sign On zorgt ervoor dat een gebruiker binnen één sessie kan inloggen in meerdere applicatie. Op zowel iOS als Android zijn er beperkingen in het delen van sessies. Het is vanuit veiligheidsoverwegingen niet mogelijk om een sessie te delen met applicaties die niet door dezelfde ontwikkelpartij gemaakt zijn.
-# Na het installeren en configureren van de software, stuur je de metadata url van de omgeving naar Kennisnet.
-# Kennisnet maakt in eerste instantie een koppeling met de staging omgeving.
-# Maak een test project waarmee je een authenticatie verzoek naar Entree Federatie kunt sturen.
-# Implementeer authenticatie in de software van de dienst.
-# Test of het authentiseren werkt, hiervoor kun je gebruik maken van de Referentie diensten
-# ? Implement and test passive authentication (optionally)
+Het is op deze wijze echter wel mogelijk om gebruikers via Entree Federatie in de app in te laten loggen met hun federatieve schoolaccount.
-==== SSO Query ====
+==Aanvullende functionaliteit==
-=== SAML support ===
+In bepaalde use cases kan een dienstaanbieder er voor kiezen om één van de onderstaande functionaliteiten te implementeren. Deze kunnen het authenticatieproces verbeteren en/of vereenvoudigen.
-Een korte uitleg over het SAML protocol kun je hier vinden:
-https://blog.surf.nl/en/saml-for-dummies/
+===SSO query===
-Op deze website kun je verschillende SAML tools en ondersteuning vinden:
+Deze functie biedt de mogelijkheid om te controleren of een gebruiker direct ingelogd kan worden zonder het inlogscherm te tonen. Kijk voor meer informatie op: [[KNF:Single_Sign_On_query|SSO query]]
-https://www.samltool.com/online_tools.php
+===Scoping===
-Een overzicht van standaard pakketten om te koppelen kun je hier vinden:
+In sommige gevallen is het al bekend welke Identity Provider de gebruiker zal gebruiken om zich via Entree Federatie te authenticeren. Dit kan zijn omdat de applicatie van de dienstaanbieder bijvoorbeeld voor een specifieke school is ingericht of omdat de gebruiker in de applicatie van de dienstaanbieder zijn school heeft geselecteerd. In deze gevallen kan er gebruik gemaakt worden van scoping.
-http://developers.wiki.kennisnet.nl/index.php?title=KNF:Hoofdpagina
+In het authenticatie verzoek dat de dienstaanbieder naar Entree Federatie verstuurd wordt de identifier van de Identity Provider meegegeven. Hierdoor kan de gebruiker gelijk worden doorgestuurd naar de Identity Provider en hoeft hij geen school meer te selecteren op het WAYF-scherm ('''W'''here '''A'''re '''Y'''ou '''F'''rom) van Entree Federatie.
-Een volledige uitleg van het SAML protocol kun je hier vinden:
-http://docs.oasis-open.org/security/saml/v2.0/
+===Forced authentication===
+Eén van de voordelen van inloggen via een federatie is, dat als een gebruiker is ingelogd bij een aangesloten dienst en vervolgens een andere aangesloten dienst bezoekt, hij automatisch opnieuw wordt geauthentiseerd en ingelogd. In sommige usecases is automatische herauthenticatie echter niet wenselijk. Denk hierbij aan administratiesystemen of een webapplicatie waarmee betalingen verricht kunnen worden. In deze gevallen kan gebruik gemaakt worden van forced authentication. Ook als de gebruiker al een lopende SSO sessie heeft (de gebruiker is al bij een andere dienst ingelogd via Entree Federatie), zal hij gevraagd worden nogmaals in te loggen als de Service Provider gebruik maakt van forced authentication
+Forced authentication levert meer veiligheid op, maar gaat gelijkertijd ten koste van gebruiksgemak. Iedere dienst zal hierin zelf een afweging moeten maken.
-== Koppelen met Entree Federatie ==
-=== Metadata URL's ===
-De metadata van Entree Federatie bevat zowel SP als IdP metadata.
+== Federatieve accounts en Entree Accounts ==
-* Productie: https://hub.entree.kennisnet.nl/openaselect/profiles/saml2/
+Binnen Entree Federatie worden twee soorten accounts onderscheiden:
-of https://aselect.entree.kennisnet.nl/openaselect/profiles/saml2/
+* '''Federatieve accounts:''' Dit zijn accounts die de gebruiker van zijn school heeft gekregen. Ze worden daarom ook wel schoolaccounts genoemd. De persoonsgegevens worden door de school beheerd en tijdens het authenticatie proces vraagt Entree Federatie deze gegevens op bij de Identity Provider van de school.
+* '''Entree accounts:''' Omdat er ook gebruikers zijn die geen schoolaccount hebben, heeft Kennisnet een eigen Identity Provider, [https://entree-account.kennisnet.nl Entree Account]. Hier kan iedereen met een geldig e-mailadres een account aanmaken. Deze accounts bevatten minder persoonsgegevens en ze zijn ook niet geverifieerd. Daarom zijn er dienstaanbieders die ervoor kiezen om authenticatie middels een Entree Account niet toe te staan.
+<strong>Neem contact op met [https://support.kennisnet.org/Tickets/Submit Kennisnet] wanneer je <span style="color:#FF0000">geen</span> authenticaties via Entree Accounts wilt toestaan.</strong>
+=Implementatie=
-* Staging: https://hub-s.entree.kennisnet.nl/openaselect/profiles/saml2/
+Nadat de voorbereiding is afgerond kan worden begonnen aan de implementatie van de koppeling met Entree Federatie. Dit zal ten eerste bestaan uit het installeren en configureren van de SAML 2.0 software library voor het de communicatie met de applicatie van Entree Federatie. Ten tweede zal er een integratie moeten plaatsvinden van de SAML 2.0 library met de eigen applicatie. Dit laatste valt buiten de scope van de ondersteuning van Kennisnet en wordt dus ook niet beschreven in de documentatie op deze wiki.
-of https://aselect-s.entree.kennisnet.nl/openaselect/profiles/saml2/
+Entree Federatie beschikt over een staging en een productie omgeving, de software op deze omgevingen is identiek. Tijdens het implementeren van de koppeling kan gebruik gemaakt worden van de staging omgeving. De productie omgeving is alleen bedoeld voor het koppelen met productie applicaties en dus niet voor test doeleinden.
-=== Protocol & bindings ===
-Entree Federatie ondersteund de volgende bindings:
+==Aandachtspunten inrichten server==
-* HTTP-Redirect, HTTP-Artifact and HTTP-POST for all incoming messages,
+Voor het inrichten van de server zijn een aantal algemene aandachtspunten waar rekening mee gehouden moet worden:
-* HTTP-Redirect and HTTP-POST for outgoing messages.
+* Voor de communicatie met de staging omgeving van Entree Federatie mag via een http verbinding verlopen, zodat ook lokale ontwikkel- en testomgevingen gebruikt kunnen worden. Voor een koppeling met de productie omgeving is https een vereiste.
+* De server mag maximaal één minuut achterlopen of vijf minuten voorlopen. Maak daarom gebruik van Network Time Protocol (NTP) om de tijd op de server te synchroniseren.
+* Alle verstuurde XML berichten moeten worden gesigned, momenteel wordt hiervoor alleen SHA-2 versleuteling ondersteund. Voor het signen van berichten kan een self-signed certificaat gebruikt worden.
+==Uitwisseling metadata==
+Voor het configureren van de SAML 2.0 software heb je de metadata van Entree Federatie nodig, deze is op de volgende URL's te vinden:
+* '''Entree Federatie staging:''' https://engine.entree-s.kennisnet.nl/authentication/idp/metadata
+* '''Entree Federatie productie:''' https://engine.entree.kennisnet.nl/authentication/idp/metadata
+Tijdens de configuratie van de software library wordt er ook een metadata bestand gegenereerd. Zorg ervoor dat dit bestand op een publieke URL beschikbaar is.
+Gedurende de configuratie moet ook een zogenaamd '''entityID''' worden opgegeven. Dit is de identifier van de Service Provider en deze moet uniek zijn binnen Entree Federatie. Om te zorgen dat het entityID uniek is kan daarom het beste de URL van de eigen webapplicatie gebruikt worden.
+Als je de installatie en configuratie hebt afgerond geef je deze URL door aan Kennisnet. Vervolgens zal Kennisnet de koppeling in de Entree Federatie applicatie configureren.
+Wanneer deze configuratie is afgerond kan de koppeling getest worden.
+==='''NameIDFormat'''===
+De NameIDFormat moet de volgende waarde bevatten:
+urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
+NameIDFormat geeft aan een Identity Provider (IdP) de opdracht om de NameID (gebruikersidentificatie) terug te geven in een specifiek formaat. Een Service Provider (SP) kan een specifiek NameID-format aanvragen in het AuthnRequest door het gebruik van het NameIDPolicy - Format element. Of deze aanvraag wordt ingewilligd, is afhankelijk van het beleid.
+==Testen van de koppeling==
+Voor het testen kan gebruik gemaakt worden van de Referentie Identity Provider van Entree Federatie. Met behulp van deze applicatie wordt het inloggen van een gebruiker via bijvoorbeeld een Elektronische Leeromgeving gesimuleerd. Het testscenario staat beschreven op: [[KNF:Service_provider_koppeling_testen | Service provider koppeling testen]]. Mocht je tijdens het testen tegen foutmeldingen aanlopen neem dan contact op met Kennisnet.
+==Integratie==
+Nu de koppeling technisch werkt is het zaak om deze functionaliteit te integreren in de eigen applicatie. Aangezien iedere applicatie uniek is kan Kennisnet in deze fase geen ondersteuning bieden.<br/>
+Voor het plaatsen van een inlog knop op je website hebben we [[KNF:Beeldmateriaal | beeldmateriaal]] beschikbaar. Hiermee streven we naar uniformiteit bij alle aangesloten websites. Voor eindgebruikers wordt het daarmee duidelijker wanneer ze via Entree Federatie kunnen inloggen.
+==Overeenkomst==
+Nu de koppeling op staging geconfigureerd, getest en geïntegreerd is, wordt er een overeenkomst afgesloten tussen de dienstaanbieder en Entree Federatie. Kennisnet zal hiervoor het contract versturen naar de tekenbevoegd administratief contactpersoon van de dienstaanbieder. Nadat Kennisnet de overeenkomst getekend retour heeft ontvangen kan de koppeling met de productie omgeving van Entree Federatie aangemaakt worden.
+==Livegang==
+Voor de livegang worden dezelfde technische stappen doorlopen als voor de koppeling met de staging omgeving:
+* Inrichten en configuratie van de eigen productie omgeving
+* Uitwisseling van de metadata
+* Configuratie van de koppeling door Kennisnet
+* Testen van de koppeling
+Ten slotte kan op de website van Kennisnet eenmalig een bericht geplaatst worden over de nieuwe aansluiting. Hiervoor moet een korte beschrijving van de dienst aangeleverd worden.
+<!--
+Op deze website kun je verschillende SAML tools en ondersteuning vinden:
+https://www.samltool.com/online_tools.php
-Entree Federatie stuurt alleen <AuthnRequest>’s naar IdP's. Er worden geen andere SAML requests verstuurd. Daarom bevat het antwoord een <AuthnStatement> en een <AttributeStatement>, als de authenticatie succesvol is.
 === Name ID Format ===
@@ Regel 71: / Regel 125: @@
 * De waarde is als volgt opgebouwd (username)@(realm). De Name ID heeft hetzelfde formaat als een e-mailadres, maar is het niet.
 * De waarde voor de realm is uniek binnen Entree Federatie en bevat bij voorkeur een schooldomein.
-* Het SAML2 Name ID format is urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
+* Het SAML Name ID format is urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
@@ Regel 79: / Regel 133: @@
 * De uid is en blijft uniek binnen de hele Federatie voor alle partijen. De uid verwijst altijd naar dezelfde gebruiker ongeacht datum/tijd waarop het ID is gebruikt.
-=== Gegevens van de gebruiker ===
-Standaard stuurt Entree Federatie alleen de standaard set attributen naar de dienst. Deze attributen bevatten geen privacy gevoelige informatie over de gebruiker. Een overzicht van de attributen kun je hier vinden: http://developers.wiki.kennisnet.nl/index.php?title=KNF:Attributen_overzicht_voor_Service_Providers
-Indien je als dienst meer informatie nodig hebt van een gebruiker, bijvoorbeeld voor autorisatie, dan kan de school hier schriftelijk toestemming voor geven met een ARP (Attribute Release Policy) formulier. Hiervoor hebben we templates die je kan gebruiken als dienst.
-=== Federatieve accounts & Entree Accounts ===
-Entree Federatie heeft 2 soorten accounts, federatieve accounts van alle aangesloten IdP's ook wel schoolaccounts genoemd. Daarnaast heeft Kennisnet een eigen IdP Entree Account, waar gebruikers zelf een individueel account kunnen aanmaken.
+-->
-Het belangrijkste verschil tussen deze accounts is dat Federatieve accounts daadwerkelijk van een school komen en ook alle attributen bevatten en Entree Accounts niet gekoppeld zijn aan een school en de waardes voor de attributen eduPersonAffiliation, nlEduPersonHomeOrganization en nlEduPersonHomeOrganizationId en standaard waarde bevatten.
+[[Categorie:Entree Federatie]]

KNF:SAML-sp: verschil tussen versies