KNF:Google Apps for Education - Identity Provider

Uit Kennisnet Developers Documentatie
Ga naar: navigatie, zoeken

Entree Federatie-symbol.png Entree Federatie: 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.
    GoogleAppsIdP01.png

  2. Ga in de Beheerdersconsole naar ‘Meer besturingslementen’ en klik op ‘Apps’.
    GoogleAppsIdP02.png

  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.
    GoogleAppsIdP03.png

  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’.
    GoogleAppsIdP04.png

  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).
    Entree-federatie.png

  11. Als u klaar bent klikt u op ‘Volgende’.
    GoogleAppsIdP05.png

  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/saml2/sp/sso/web
    Entiteits-ID: 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.
    GoogleAppsIdP06.png

  13. Klik vervolgens op ‘Volgende’.
  14. Klik in het volgende scherm op ‘Voltooien’
    GoogleAppsIdP07.png

  15. Als de koppeling juist geconfigureerd is ziet u de volgende melding:
    GoogleAppsIdP08.png

  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'.
    GoogleAppsIdP010.png

  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:
    My customer 1.PNG

  5. Klik op ‘Execute’, als het goed is krijg je onderstaande melding:.
    GoogleAppsIdP012.png

  6. Indien je deze foutmelding krijgt is het schema al aangemaakt:
    GoogleAppsIdP013.png

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.
    GoogleAppsIdP01.png

  2. In de interface ga naar 'Meer besturingselementen' en klik op 'Apps'.
  3. Klik vervolgens op 'SAML-apps'.
    GoogleAppsIdP017.png

  4. Klik op de SAML-app 'Entree Federatie'.
    GoogleAppsIdP018.png

  5. Klik op 'Attribuuttoewijzing'.
    GoogleAppsIdP019.png

  6. Klik op 'Nieuwe toewijzing toevoegen'.
    GoogleAppsIdP020.png

  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’.
GoogleAppsIdP021.png

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.
    GoogleAppsIdP014.png

  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’.
    GoogleAppsIdP015.png

  5. Klik in het volgende scherm nogmaals op 'Authorize and Execute'.
    GoogleAppsIdP017.png

  6. Als alles goed is gegaan krijg je de volgende melding:
    UserKey5.PNG

  7. 403 melding: de gebruiker bestaat niet, kies de juiste gebruiker:
    UserKey3.PNG

  8. 404 melding: verkeerde gebruiker gekozen, kies de juiste gebruiker:
    UserKey4.PNG

  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.