Google-integratie instellen

Met de Google-koppeling melden leerkrachten en leerlingen zich aan met hun Google Workspace-schoolaccount:

• Leerlingen — bij lessen met Aanmelden met Google ziet de leerkracht gegarandeerd de échte naam (essentieel bij toetsen en examens).
• Leerkrachten — accounts worden automatisch aangemaakt op basis van je schooldomein en (optioneel) een Google-groep; geen handmatig accountbeheer meer.
• De vrije flow (code + zelfgekozen naam) blijft altijd beschikbaar — de leerkracht kiest per voorbereiding.

De setup bestaat uit drie stappen (plus een optionele vierde) en kost een half uur. Je hebt toegang nodig tot de Google Cloud Console en — voor stap 4 — tot de Workspace Admin Console van de school.

Hoe het werkt (in het kort)

De aanmelding loopt volledig via je eigen server (authorization-code flow): de browser of extensie opent een server-URL, de server praat met Google en geeft het resultaat terug. Google-tokens verlaten de server nooit, en elke installatie — ook on-premise — gebruikt haar eigen OAuth-client. Zonder Google-configuratie in de omgeving draait de server gewoon door met alleen de vrije flow.

Stap 1 — OAuth-client aanmaken (Google Cloud Console)

1. Ga naar console.cloud.google.com en maak een project aan (bv. coolbx-focus).
2. Open APIs & services → OAuth consent screen (de wizard heet tegenwoordig Google Auth Platform):
   • App-naam, bv. "Coolbx Focus", en een support-e-mailadres.
   • Audience: kies Internal als alleen accounts van je eigen Workspace-domein aanmelden (eenvoudigst — geen verificatie nodig). Kies External als meerdere domeinen moeten kunnen aanmelden; in Testing-modus moet je dan elke tester als test user toevoegen.
   • Extra scopes zijn niet nodig: de koppeling gebruikt enkel openid email profile.
3. Open Clients → Create client:
   • Type Web application.
   • Authorized redirect URI — exact: https://<jouw-api-adres>/api/v1/auth/sso/google/callback (bv. https://focus-api.school.be/api/v1/auth/sso/google/callback).
4. Noteer het client-ID en client-secret.

Stap 2 — Server configureren

Zet in de omgeving van de server:

PUBLIC_SERVER_URL=https://focus-api.school.be
GOOGLE_CLIENT_ID=xxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...

Herstart de server. In de log verschijnt:

ee/sso geregistreerd (provider: google)

Vanaf nu toont het dashboard-loginscherm automatisch de knop Aanmelden met Google, en herkent de student-extensie Google-lessen.

Stap 3 — School configureren in het dashboard

Meld aan als platform-admin en ga naar Beheer → Scholen. Maak een school aan (of open de bestaande) en stel in:

Veld	Betekenis
Leerkracht-domeinen	Workspace-domeinen waaruit leerkrachten mogen aanmelden, bv. school.be. Let op: zitten leerlingen in hetzelfde domein, stel dan ook de leerkrachtengroep in (stap 4) — anders kan elke leerling een leerkracht-account aanmaken.
Leerling-domeinen	Domeinen die mogen deelnemen aan Google-lessen, bv. leerling.school.be. Leeg = geen domeinrestrictie.
Provisioning	Automatisch (JIT): wie aan domein + groep voldoet krijgt meteen een account. JIT met wachtrij: wie buiten de groep valt, komt in een goedkeuringswachtrij. Altijd goedkeuren: elk nieuw account wacht op een school-admin.
Toegelaten login-methodes	Zet Wachtwoord uit als je school volledig op Google wil werken.
Standaard sessie-aanmelding	De voorgestelde keuze (Vrij of Google) voor nieuwe voorbereidingen.

Test daarna meteen: meld in een privévenster aan met een leerkracht-schoolaccount — het account wordt automatisch aangemaakt en verschijnt op de tab Leerkrachten.

Stap 4 (optioneel) — Leerkrachtengroep via de Directory API

Wil je het leerkracht/leerling-onderscheid maken met een Google-groep (bv. leerkrachten@school.be), dan heeft de server leestoegang tot de Directory API nodig:

1. Service account (Google Cloud Console, zelfde project): APIs & services → enable de Admin SDK API; maak onder Credentials een service account aan en genereer een JSON-sleutel.
2. Zet uit de JSON-sleutel in de server-omgeving:

   GOOGLE_SA_CLIENT_EMAIL=focus-directory@<project>.iam.gserviceaccount.com
   GOOGLE_SA_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

3. Domain-wide delegation (Workspace Admin Console van de school): Beveiliging → Toegangs- en gegevensbeheer → API-besturingselementen → Domeinbrede delegatie → voeg het numerieke client-ID van het service account toe met exact deze scope:

   https://www.googleapis.com/auth/admin.directory.group.readonly

4. Vul in de schoolconfiguratie in het dashboard in:
   • Google Group (leerkrachten) — het groepsadres, bv. leerkrachten@school.be.
   • Workspace-admin (impersonatie) — een admin-account van het domein namens wie de server de Directory API bevraagt.

Het lidmaatschap wordt bij elke aanmelding opnieuw gecontroleerd: wie uit de groep verdwijnt, wordt automatisch geblokkeerd. Is de Directory API tijdelijk onbereikbaar, dan mogen bestaande leerkrachten blijven aanmelden (fail-open, met logmelding); alleen nieuwe accounts worden dan geweigerd — één Google-storing legt het lesgeven nooit plat.

Problemen oplossen

Symptoom	Oorzaak / oplossing
redirect_uri_mismatch bij Google	De redirect-URI in de OAuth-client komt niet exact overeen met PUBLIC_SERVER_URL + /api/v1/auth/sso/google/callback.
Foutcode NO_SCHOOL na aanmelden	Er bestaat geen school waarvan de leerkracht-domeinen het domein van het account dekken. Controleer stap 3.
Foutcode DOMAIN_REJECTED	Verkeerd Google-account gekozen (bv. privé-Gmail) of het domein staat niet in de lijst.
Foutcode GROUP_REJECTED	Het account zit niet in de geconfigureerde leerkrachtengroep.
Foutcode DIRECTORY_UNAVAILABLE	Delegation niet (correct) ingesteld, service-account-sleutel fout, of Admin SDK API niet enabled.
Account "wacht op goedkeuring"	Provisioning staat op een wachtrij-modus — keur het account goed op Beheer → Scholen → Leerkrachten.
Google-knop verschijnt niet	GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET/PUBLIC_SERVER_URL ontbreken, of de server is niet herstart. Check de logregel uit stap 2.

Privacy

Bij Google-lessen bewaart de server per leerling naam, e-mailadres en account-ID. Inactieve leerlingprofielen worden automatisch geanonimiseerd na de retentieperiode uit de schoolconfiguratie (standaard 12 maanden). Neem de verwerking op in je verwerkingsregister; Coolbx Focus stuurt zelf niets naar externe diensten buiten de Google-aanmelding zelf.