Serviceaccounts¶

Een serviceaccount is een lid van je organisatie dat geen persoon is, maar een programma: een koppeling, een script dat 's nachts draait, een ander systeem dat OS aanroept. Alles wat een persoon in OS kan, kan een serviceaccount via de API, op precies dezelfde manier beslist. Deze pagina is voor beheerders: wie de beheerdersrol van de organisatie heeft.

Een sleutel kan precies wat zijn serviceaccount mag, en niets meer. Wie een sleutel heeft, handelt als het serviceaccount. Geef je een serviceaccount weinig rechten, dan geven zijn sleutels ook weinig rechten. Geef een serviceaccount dus alleen wat het programma echt nodig heeft.

Op het scherm¶

Open Gebruikersbeheer, kies Serviceaccounts en doorloop:

De lijst. Je ziet je serviceaccounts. Kies Maak een nieuw serviceaccount aan om er een te maken.
Maken. Vul Naam en, als je wilt, Beschrijving in, kies de rollen, groepen en eigenschapswaarden die het krijgt (je kunt alleen geven wat je zelf hebt) en kies Serviceaccount aanmaken.
Sleutels. Open het serviceaccount en kies het tabblad Sleutels. Kies Maak een nieuwe API-sleutel aan, vul API-sleutel naam en Vervaldatum in en kies API-sleutel aanmaken. Het scherm toont het Geheim één keer, met de Client-id en het Adres voor het token: bewaar het meteen. Bij elke sleutel zie je de status, wanneer hij verloopt, wanneer hij het laatst is gebruikt en de waarschuwingen. Verloopt een sleutel binnen 14 dagen, dan krijgen de beheerders van de organisatie ook een melding in OS en per e-mail, één keer per verloopdatum. De oude kopie van een vervangen sleutel waarschuwt niet.
Vervangen. Kies bij een actieve sleutel Vervangen, vul de nieuwe vervaldatum en de Overlap in uren in en bevestig. Het scherm toont het nieuwe geheim één keer. Alleen wie alles heeft wat het serviceaccount heeft, krijgt deze knop.
Intrekken. Kies bij een sleutel de prullenbak en bevestig. De sleutel werkt dan niet meer.
Rechten. Het tabblad Rechten toont de rollen, groepen en eigenschapswaarden van het serviceaccount. Kies Rechten toevoegen om rechten te geven, of trek er een in; je kunt alleen geven en intrekken wat je zelf mag.
Toegang. Het tabblad Toegang toont per soort onderdeel wat het serviceaccount mag (Bekijken, Gebruiken, Wijzigen, Verwijderen), en dus ook wat kan wie zijn sleutel heeft. Kijk hier voordat je een sleutel maakt.
Deactiveren en verwijderen. Boven aan de pagina kies je Deactiveren (of Activeren) of Verwijderen.

Een serviceaccount maken¶

Kies een naam (uniek in je organisatie) en, als je wilt, een beschrijving van waarvoor het is.
Kies de rollen, groepen en eigenschapswaarden die het krijgt, zoals bij een uitnodiging. Je kunt alleen geven wat je zelf hebt (waarom).
Het serviceaccount is meteen actief. Er is niemand die een uitnodiging accepteert.

Een serviceaccount staat in dezelfde ledenlijst als de mensen, met dezelfde rollen, groepen en eigenschappen. Alleen wie serviceaccounts beheert, wijzigt ze, op dezelfde manier als bij een persoon; een personenbeheerder ziet een serviceaccount in de lijst, maar wijzigt er niets aan. Een serviceaccount telt niet mee als de laatste beheerder: een organisatie houdt altijd een persoon met de beheerdersrol.

Wat een serviceaccount niet kan¶

Wat een persoon alleen voor zichzelf doet, kan een serviceaccount niet: voorkeuren instellen, zichzelf laten wissen en een uitnodiging accepteren. OS weigert dat met 403. Een serviceaccount wordt beheerd en verwijderd door een beheerder.

Sleutels¶

Een programma meldt zich aan met een sleutel. Een serviceaccount kan meerdere sleutels hebben (standaard hoogstens vijf tegelijk), elk met een eigen naam.

Maak een sleutel met een naam en een verloopdatum. Die is verplicht en ligt hoogstens een jaar vooruit.
OS toont het geheim van de sleutel één keer, met de client-id en het adres waar het programma een token vraagt. Bewaar het geheim meteen op een veilige plek; OS laat het nooit meer zien.
Na enkele seconden werkt de sleutel.

Alleen wie alles heeft wat het serviceaccount heeft, mag er een sleutel voor maken. Zo kan niemand via een sleutel aan meer rechten komen dan hij al heeft.

Het programma vraagt een token met de client-id en het geheim, en stuurt dat token mee naar OS:

curl -s -X POST "$TOKEN_ENDPOINT" \
  -d grant_type=client_credentials -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET"

Een token is vijf minuten geldig; het programma vraagt daarna een nieuw.

Vervangen zonder onderbreking¶

Draai een sleutel om (roteren): OS maakt een nieuwe sleutel met een nieuw geheim, en de oude blijft nog een overlap werken (standaard 24 uur, hoogstens 30 dagen). Zet het nieuwe geheim in het programma voordat de overlap voorbij is.

Intrekken, verlopen en waarschuwingen¶

Een ingetrokken sleutel werkt vanaf het volgende verzoek niet meer.
Een verlopen sleutel werkt vanaf zijn verloopdatum niet meer.
Bij elke sleutel zie je wanneer OS hem het laatst gebruikt zag (tot op vijf minuten). OS waarschuwt bij een sleutel die binnen 14 dagen verloopt, die 30 dagen niet is gebruikt, of die een week na het maken nog nooit is gebruikt.

Gebruiken via MCP¶

Een eigen agent die MCP spreekt, kan als het serviceaccount met OS werken, met de rechten van het account: elke handeling van de API van OS is dan een tool. Open het serviceaccount; op het tabblad Algemeen staat onder Gebruiken via MCP:

het MCP-adres, waar de agent zijn aanroepen naartoe stuurt;
het Tokenadres, waar de agent een token ophaalt;
Token ophalen en Tools opvragen: twee voorbeelden om te kopiëren.

Gebruik de client-ID van een sleutel op het tabblad Sleutels en het geheim van die sleutel. Vul het geheim in op de plaats van YOUR_CLIENT_SECRET en het token uit de eerste stap op de plaats van ACCESS_TOKEN:

curl -s -X POST '<tokenadres>' \
  -d grant_type=client_credentials \
  -d client_id='<client-id>' \
  -d client_secret='YOUR_CLIENT_SECRET'

curl -s -X POST '<MCP-adres>' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Een token is vijf minuten geldig; haal daarna een nieuw. Heeft het serviceaccount geen actieve sleutel, dan zegt de kaart dat je er eerst een maakt. Staan AI-apps in de organisatie op Uit, dan krijgt de agent elke aanroep geweigerd tot een beheerder het aanzet (Werken vanuit AI-apps); de kaart zegt dat dan ook.

Wat een serviceaccount mag en wat het deed¶

Bij elk serviceaccount zie je per soort onderdeel wat het mag. In het auditlogboek zie je wat het deed en wat met het serviceaccount en zijn sleutels is gedaan. Geheimen staan nooit in het logboek.

Deactiveren en verwijderen¶

Deactiveren: vanaf het volgende verzoek weigert OS het serviceaccount alles in de organisatie, onder elke sleutel; alleen GET /api/v1/me antwoordt nog, zonder lidmaatschap. Heractiveren maakt dezelfde sleutels weer bruikbaar.
Verwijderen: definitief. Alle sleutels worden ingetrokken. Wat het serviceaccount in de AI-functies maakte, blijft van de organisatie, tenzij je kiest om het te wissen.

Als OS weigert¶

401: de sleutel is ingetrokken of verlopen, of het token is van een andere client.
403: je geeft een rol, groep of waarde die je zelf niet hebt, of je maakt een sleutel voor een serviceaccount dat meer heeft dan jij; de melding noemt wat.
409: de naam is al in gebruik, het serviceaccount heeft al het hoogste aantal sleutels, of het serviceaccount is intussen gewijzigd.
422: een verloopdatum die ontbreekt, voorbij is of te ver vooruit ligt.

Via de API¶

POST /api/v1/organisations/{id}/service-accounts met name en, naar keuze, description, roles, groups en attributes, zoals bij een uitnodiging.
GET, PATCH (met If-Match) en DELETE /api/v1/organisations/{id}/service-accounts/{account_id}.
POST /api/v1/organisations/{id}/service-accounts/{account_id}/keys met label en expires_at; het antwoord bevat client_id, client_secret en token_endpoint.
POST …/keys/{key_id}/rotate met expires_at en overlap_hours; DELETE …/keys/{key_id} trekt een sleutel in.
GET /api/v1/organisations/{id}/memberships/{account_id}/access toont wat het mag; GET /api/v1/organisations/{id}/audit-events?actor={account_id} wat het deed.