De Directory API is de ruggengraat van geautomatiseerd Workspace-beheer. Waar de admin-console een grafische schil is, geeft deze API je directe, scriptbare toegang tot alles wat je organisatiestructuur vormt: gebruikers, groepen, organisatie-eenheden, aliassen, apparaten en rollen.
In dit artikel verken je de belangrijkste resources en hoe je ze inzet.
De resources op een rij
De Directory API is opgebouwd rond een aantal resources die elk het bekende CRUD-patroon volgen.
- Users: het beheren van individuele accounts.
- Groups: distributielijsten en beveiligingsgroepen.
- Members: het lidmaatschap binnen groepen.
- Orgunits: de boomstructuur van organisatie-eenheden.
- Aliases: extra e-mailadressen voor gebruikers en groepen.
- Roles en RoleAssignments: beheerdersrechten fijnmazig toekennen.
Patch versus update
Elke resource ondersteunt list, get, insert, update, patch en delete. Patch is vaak handiger dan update, omdat je alleen de gewijzigde velden meestuurt in plaats van het hele object. Zo voorkom je dat je per ongeluk bestaande velden leegmaakt.
Authenticatie en scopes
De Directory API werkt vrijwel altijd met domeinbrede delegatie. Een service-account impersoneert een echte beheerder, zodat de API namens die persoon mag handelen.
- Gebruik een service-account met domeinbrede delegatie, ingeschakeld in de admin-console.
- Stel de juiste OAuth-scopes in, bijvoorbeeld
admin.directory.uservoor gebruikersbeheer ofadmin.directory.groupvoor groepen. Lezen kan vaak met een.readonly-variant. - Impersoneer een beheerdersaccount dat de bijbehorende rechten heeft.
Beperk de scopes
Geef het service-account alleen de scopes die het echt nodig heeft. Een token met volledige schrijfrechten op de hele directory is een aantrekkelijk doelwit. Splits desnoods aparte accounts voor lezen en schrijven.
Organisatie-eenheden beheren
Organisatie-eenheden structureren je domein en bepalen welk beleid waar geldt. Je maakt ze aan met een naam en een parentOrgUnitPath.
Zo bouw je je OU-structuur op
- Bepaal de gewenste hierarchie, bijvoorbeeld
/Verkoopen/Verkoop/Binnendienst. - Maak elke OU aan met
orgunits().insert()onder de juiste parent. - Plaats gebruikers in een OU via het veld
orgUnitPathbijusers().update()ofusers().patch(). - Koppel beleid aan de OU in de admin-console of via de relevante API.
Groepen en lidmaatschap
Groepen gebruik je voor e-mail-distributie en voor toegangsbeheer. Het toevoegen van een lid is een aparte call op de members-resource.
service.members().insert(
groupKey='team@jouwdomein.nl',
body={'email': 'jan@jouwdomein.nl', 'role': 'MEMBER'}
).execute()
Groepen als toegangslaag
Gebruik groepen als toegangslaag in plaats van rechten per gebruiker toe te kennen. Door iemand aan of uit een groep te halen, regel je in een handeling toegang tot Drive-mappen, agenda's en applicaties. Dat schaalt veel beter en is makkelijker te auditen.
Beheerdersrollen fijnmazig toekennen
Niet iedereen hoeft superbeheerder te zijn. Met de Roles-resource ken je precies de rechten toe die iemand nodig heeft, en met RoleAssignments koppel je zo'n rol aan een gebruiker of aan een specifieke OU.
Wees zuinig met superbeheerder
Superbeheerderrechten zijn de hoogste privileges in je organisatie. Ken ze spaarzaam toe, beveilig die accounts met sterke verificatie in twee stappen, en gebruik voor dagelijkse taken een rol met minder rechten. Een gecompromitteerd superbeheerdersaccount betekent een volledige overname van je domein.
Aliassen en zoeken
Met aliases geef je gebruikers extra adressen. Met de query-parameter op users().list() filter je gericht, bijvoorbeeld op een OU of op een specifiek veld. Let op de aanhalingstekens: de waarde staat tussen enkele quotes binnen de querystring, wat verplicht is zodra een pad een spatie bevat.
response = service.users().list(
customer='my_customer',
query="orgUnitPath='/Verkoop'",
maxResults=200
).execute()
Bij grote domeinen levert de API resultaten in pagina's. Lees het veld nextPageToken uit de response en geef het mee bij de volgende call om verder te bladeren.
Veelvoorkomende valkuilen
- Geen impersonatie: zonder een geimpersoneerde beheerder krijg je meestal een 403. De delegatie moet in de admin-console staan en de scopes moeten exact kloppen.
- Rate limits: bij grote bewerkingen loop je tegen quota aan. Gebruik exponentiele backoff en spreid het werk in batches.
- Update in plaats van patch: een update zonder alle velden kan bestaande gegevens overschrijven. Kies patch tenzij je het hele object bewust vervangt.
Veelgestelde vragen
Wat is het verschil tussen update en patch?
Update vervangt het hele object en verwacht dat je alle velden meestuurt. Patch wijzigt alleen de velden die je opgeeft en is daardoor veiliger tegen onbedoeld overschrijven.
Kan ik apparaten beheren via de Directory API?
Ja. Via de chromeosdevices- en mobiledevices-resources vraag je apparaten op en voer je acties uit, zoals een toestel op afstand wissen. Voor het wijzigen van de status van ChromeOS-apparaten gebruik je tegenwoordig de batchChangeStatus-methode in de customer.devices.chromeos-resource, omdat de oudere action-methode is afgeschaft.
Hoe verplaats ik veel gebruikers naar een andere OU?
Loop door de gebruikers en roep voor elk een patch aan met het nieuwe orgUnitPath. Gebruik batching en exponentiele backoff bij grote aantallen om binnen de quota te blijven.
Werkt de Directory API ook met Cloud Identity?
Ja, beide delen onderliggende concepten. Voor sommige geavanceerde groepsfuncties, zoals dynamische groepen en geneste lidmaatschappen, is de Cloud Identity Groups API krachtiger.
Welke OAuth-scopes heb ik minimaal nodig?
Dat hangt af van wat je doet. Voor gebruikersbeheer gebruik je admin.directory.user, voor groepen admin.directory.group. Wil je alleen lezen, kies dan de bijbehorende .readonly-scope om de rechten te beperken.
Hoe blader ik door meer dan een pagina resultaten?
List-aanroepen geven een nextPageToken terug zolang er meer resultaten zijn. Geef dat token mee bij de volgende call en herhaal dit tot het token ontbreekt.
Met grip op de Directory API beheer je je hele organisatiestructuur als code: reproduceerbaar en auditeerbaar.