KNF:Google Apps for Education - Identity Provider

Deze handleiding bevat een stappenplan om een Google Apps for Education omgeving in te zetten als Identity Provider en aan Entree Federatie te koppelen.

Om aan de hand van deze handleiding een koppeling te kunnen realiseren moet aan de volgende voorwaarden worden voldaan:

1. U heeft een werkende Google Apps for Education omgeving
2. U heeft ervaring met het beheren van een Google Apps for Education omgeving
3. U heeft zich als Identity Provider bij Entree Federatie aangemeld. U kunt zich aanmelden door het invullen van het formulier op: https://www.kennisnet.nl/entree-federatie/aanmelden/
4. Voor het geautomatiseerd vullen van attributen voor meerdere gebruikers moet u zelf een script maken dat communiceert met de Google Directory API. In deze handleiding wordt alleen beschreven hoe u dit voor een enkele gebruiker handmatig kunt doen.

Stap 1: Configuratie van de koppeling

De eerste stap is om de koppeling met Entree Federatie te configureren in Google Apps for Education. Op deze manier wordt er een vertrouwde verbinding, ook wel trustrelatie genoemd, opgezet.

1. Log in op de Beheerconsole van de Google Apps omgeving (https://admin.google.com) met een beheerders account.
   
   
   
2. Ga in de Beheerdersconsole naar ‘Meer besturingslementen’ en klik op ‘Apps’.
   
   
   
3. Klik vervolgens op ‘SAML-apps’.
4. Klik op de link ‘Een service/app toevoegen aan uw domein’.
5. Er verschijnt nu een pop-up scherm ‘SSO inschakelen voor SAML-applicatie’.
   Klik op ‘Mijn eigen aangepaste app instellen’ onderaan dit scherm.
   
   
   
6. In het volgende scherm kunt u een metadata bestand van uw Google Apps for Education downloaden. Kennisnet heeft dit bestand een latere stap nodig om een vertrouwde verbinding te configureren tussen uw Google Apps omgeving en Entree Federatie.
   Klik onder ‘Optie 2’ op de knop ‘Downloaden’.
   
   
   
7. Klik op ‘Volgende’ als het downloaden voltooid is.
8. Vul in het volgende scherm bij ‘Applicatienaam’ ‘Entree Federatie’ in.
9. Indien gewenst kunt u het veld 'Omschrijving' invullen, maar u mag dit veld ook leeg laten.
10. U kunt eventueel onderstaand logo toevoegen (niet verplicht).
    
    
    
11. Als u klaar bent klikt u op ‘Volgende’.
    
    
    
12. In het volgende scherm geeft u de gegevens van Entree Federatie op om de Single Sign On verbinding te configureren.
    Voor een koppeling met de productie omgeving van Entree Federatie gebruikt u:
    ASC-URL: https://aselect.entree.kennisnet.nl/openaselect/profiles/saml/sp/sso/web
    Entiteits-ID: https://aselect.entree.kennisnet.nl
    De overige velden hoeven niet te worden ingevuld of gewijzigd.
    Onderstaand voorbeeld is een configuratie voor de productie omgeving van Entree Federatie.
    
    
    
13. Klik vervolgens op ‘Volgende’.
14. Klik in het volgende scherm op ‘Voltooien’
    
    
    
15. Als de koppeling juist geconfigureerd is ziet u de volgende melding:
    
    
    
16. Klik op ‘Ok’

Stap 2: Versturen metadata

In stap 1.6 heeft u een metadata bestand gedownload. Kennisnet heeft dit bestand nodig om de koppeling tussen uw Google Apps for Education omgeving en Entree Federatie te configureren. U kunt dit bestand versturen naar de Servicedesk van Kennisnet. Dit kan door te antwoorden op de mail die u heeft ontvangen na het invullen van het aanmeldformulier of u kunt u gebruik maken van onze Support tool: https://support.kennisnet.org/. Klik vervolgens op ‘Stel een vraag’.

Stap 3: Definiëren van door te geven attributen

Voor een goede werking van Entree Federatie is het nodig om een minimale set aan standaard attributen te versturen (zie voor meer informatie over attributen: Overzicht van Federatieve attributen. Om deze attributen door te geven naar Entree Fedratie moet er in de Google Apps for Education omgeving een apart schema worden gemaakt, waarin deze attributen gedefinieerd worden.

Het aanmaken van een dergelijk schema kan uitsluitend via de Google Directory API, zoals beschreven in de stappen hieronder.

1. Ga naar https://developers.google.com/admin-sdk/directory/v1/reference/schemas/insert#try-it.
2. Als u nog niet bent ingelogd, log dan in met uw Google Apps for Education beheerders account.
3. Vul bij het veld 'customerId' de volgende waarde in: 'my_customer'.
   
   
   
4. Bij het veld "Request body" vervang je de reeds ingevulde tekst met de onderstaande tekst:

   {
     "fields": 
     [
       {
         "fieldName": "BRIN",
         "fieldType": "STRING"
       },
       {
         "fieldName": "Schoolnaam",
         "fieldType": "STRING"
       },
       {
         "fieldName": "Leerlingnummer",
         "fieldType": "STRING"
       },
       {
         "fieldName": "Rol",
         "fieldType": "STRING"
       }
     ],
     "schemaName": "EntreeFederatie"
   }

   In een later stap zullen we dit schema gebruiken bij het toewijzen van attributen die worden doorgegeven aan Entree Federatie.
   Dat ziet er als volgt uit:
   
   
   
5. Klik op ‘Execute’, als het goed is krijg je onderstaande melding:.
   
   
   
6. Indien je deze foutmelding krijgt is het schema al aangemaakt:
   
   
   

Stap 4: Toewijzen van de aan Entree Federatie door te geven attributen

We hebben nu de attributen die niet standaard door Google Apps for Education gedefinieerd in stap 3 door middel van een attributenschema. In deze stap gaan we de attributen die aan Entree Federatie moeten worden doorgegeven configureren.

1. Log in op de admin omgeving van Google Apps (https://admin.google.com) met een beheerders account.
   
   
   
2. In de interface ga naar 'Meer besturingselementen' en klik op 'Apps'.
3. Klik vervolgens op 'SAML-apps'.
   
   
   
4. Klik op de SAML-app 'Entree Federatie'.
   
   
   
5. Klik op 'Attribuuttoewijzing'.
   
   
   
6. Klik op 'Nieuwe toewijzing toevoegen'.
   
   
   
7. Bij ‘Applicatiekenmerk’ vult u de naam van het attribuut zoals Entree Federatie die verwacht. Bij ‘Categorie’ kiest u het attributenschema dat het attribuut bevat dat u wilt doorgeven. Bij ‘Gebruikersveld’ kiest u het attribuut dat u wilt doorgeven. Voeg alle onderstaande regels op deze wijze toe.
   

Applicatiekenmerk	Categorie	Gebruikersveld
uid	Algemene informatie	Primair emailadres
employeeNumber	EntreeFederatie	Leerlingnummer
givenName	Algemene informatie	Voornaam
sn	Algemene informatie	Achternaam
mail	Algemene informatie	Primair emailadres
eduPersonAffiliation	EntreeFederatie	Rol
nlEduPersonHomeOrganizationId	EntreeFederatie	BRIN
nlEduPersonHomeOrganization	EntreeFederatie	Schoolnaam

Klik op ‘Opslaan’.

Stap 5: Attributen per gebruiker vullen

We hebben nu de koppeling met Entree Federatie geconfigureerd en een schema gedefinieerd voor attributen die moeten worden doorgegeven. Vervolgens hebben we in de vorige stap aangegeven welke attributen aan Entree Federatie moeten worden doorgegeven. In deze stap gaan we deze attributen vullen met waarden van gebruikers.

Let op:
Zoals vermeld aan het begin van deze handleiding beschrijven we hier hoe u de attributen voor een gebruiker handmatig kan vullen. Voor grotere hoeveelheden gebruikers is het aan te bevelen om dit te automatiseren. Dit valt echter buiten de scope van deze handleiding en ook buiten de ondersteuning van Kennisnet. Voor meer informatie kunt u de documentatie over Google Directory API raadplegen: https://developers.google.com/api-client-library/

1. Ga naar https://developers.google.com/admin-sdk/directory/v1/reference/users/patch#try-it.
   
   
   
2. Als u nog niet bent ingelogd, log dan in met uw Google Apps for Education beheerders account.
3. Vul bij het veld 'userKey' de inlognaam van de gebruiker waarvoor de attributen moeten worden aangepast, in dit voorbeeld: 'gebruiker@apps.kennisnet.nl'.
4. Vervang in de onderstaande tekst de waarden brin, schoolnaam, student en 12345 met de juiste waarden voor de gebruiker.

   {
     "customSchemas":
     {
       "EntreeFederatie":
       {
         "BRIN": "brin",
         "Schoolnaam": "schoolnaam",
         "Rol": "student",
         "Leerlingnummer": "12345"
       }
     }
   }

   Vervang daarna de in het screenshot hieronder reeds ingevulde tekst met de aangepaste tekst. De attributen zijn nu gevuld voor ‘gebruiker@apps.kennisnet.nl’. Klik op ‘Execute’.
   
   
   
5. Klik in het volgende scherm nogmaals op 'Authorize and Execute'.
   
   
   
6. Als alles goed is gegaan krijg je de volgende melding:
   
   
   
7. 403 melding: de gebruiker bestaat niet, kies de juiste gebruiker:
   
   
   
8. 404 melding: verkeerde gebruiker gekozen, kies de juiste gebruiker:
   
   
   
9. Ga terug naar https://admin.google.com/ kies APPS, SAML-apps, kies instellingen, kies "Ingeschakeld voor iedereen".

Stap 6: Testen van de koppeling en attribuutdoorgifte

Als u de vorige stappen succesvol heeft doorlopen en van de Kennisnet servicedesk bericht heeft ontvangen dat de koppeling is aangemaakt kunt u testen.

1. Ga naar Referentie omgeving van Entree Federatie. Voor de productie omgeving is dit http://kn.nu/refsp.
2. Kies voor ‘Log in met je schoolaccount’.
3. Selecteer in het scherm de school waarvoor u de Google Apps for Education koppeling heeft aangemaakt.
4. Log op het volgende scherm (Google Apps for Education) in met de gebruiker waarvoor u eerder de attributen heeft aangepast.
5. Na het inloggen krijgt u een scherm te zien met daarin de attributen zoals die van uw Google Apps for Education scherm zijn doorgegeven aan Entree Federatie.

Als u de melding ‘Authenticatie mislukt’ krijgt, worden niet de juiste attributen doorgegeven en/of lege attributen doorgegeven.