SCIM-koppeling configureren voor een tenant

Aan het einde van deze gids synchroniseert Azure AD (Entra ID) automatisch gebruikers en group-membership naar één tenant in Tapster. Je hebt gevalideerd dat een testgebruiker met de juiste rollen verschijnt.

Voorwaarden:

  • Je hebt Tapster-admin-rechten (toegang tot de admin-tenant-detail-pagina).
  • De klant heeft een Enterprise Application in Azure AD met SCIM-provisioning beschikbaar, en de klant kan daarop wijzigen (of doet dit samen met jou).
  • Je kent de Azure-tenant-id van de klant (een GUID, optioneel maar handig).
  • De klant heeft een lijst Azure-groups waarvan duidelijk is welke Tapster-rol daarbij hoort.

Voor achtergrond zie de explanation: SCIM-provisioning en ADR 0002. Voor de admin-UI-gids voor jouw klant zelf, verwijs je naar de userdoc bij Beheerder tenant-detail.

1. Mapping-keuzes vooraf afstemmen met de klant

Voor je iets aanzet, maak met de klant samen een lijst:

Azure group-object-id Azure-groupnaam Welke Tapster-rol(len)
aaaa-bbbb-... Tapster-Admins tapster-admin
cccc-dddd-... Tapster-Beheerders tapster-beheerder
eeee-ffff-... Tapster-Gebruikers tapster-gebruiker

De Tapster-rollen die je hier noemt zijn Rbac-records uit de admin-omgeving. Open de RBAC-pagina en noteer per rol de uuid (niet de mongo-_id). De admin-form-select gebruikt al uuid als value, dus je hoeft alleen de juiste rollen in het dropdown te kiezen.

Per Azure-group kun je meerdere Tapster-rollen kiezen, en zit een gebruiker in meerdere gemapte groups, dan tellen de rollen op. Rechten zijn de vereniging van de capabilities van alle toegekende rollen.

Geef ook door welke default-rol een gebruiker krijgt zonder enige groep-match. Geen default? Dan staat de gebruiker op een lege rollenset en kan hij niets in Tapster.

Bespreek ook alvast hoe de gebruikers straks inloggen. SCIM maakt het account direct op status “Actief” aan en stuurt géén uitnodigingsmail. Inloggen gaat dus via Azure SSO (als dat voor de tenant aanstaat) of via een inloglink (“Automagisch inloggen”). Een uitnodiging versturen kan niet meer zodra het account actief is.

2. Maak een Service Account Token voor SCIM aan

In Tapster, ingelogd als beheerder van de doel-tenant:

  1. Ga naar Backoffice > Instellingen > Koppelingen > Service Account Tokens.
  2. Klik Nieuwe token. Geef een naam zoals scim-azure-2026 zodat je later weet waar deze voor is.
  3. Kopieer de tokenwaarde één keer uit de bevestigingsdialog. Daarna is alleen lastFour zichtbaar.
  4. Zet de waarde tijdelijk in een password manager. Je deelt deze met de Azure-admin in stap 4.

3. Schakel SCIM aan in de Tapster admin-tenant-detail

In Tapster, ingelogd als Tapster-admin:

  1. Open Admin > Tenants en klik op de doel-tenant.
  2. Scroll naar SCIM Configuratie.
  3. Zet SCIM ingeschakeld aan.
  4. Vul optioneel Azure tenant id in (alleen ter referentie).
  5. In de tabel Role mapping voeg je per Azure-group een regel toe:
    • Azure group id — het object-id uit Azure (GUID).
    • Azure group name — de leesbare naam (voor audit-logs).
    • Tapster rollen — selecteer één of meer rollen uit de dropdown.
  6. Vul Default roles als je een fallback wil voor gebruikers zonder match.
  7. Klik Opslaan.

De toggle Automatisch rollen toewijzen kun je negeren: geen enkel SCIM-codepad leest hem, rollen worden altijd direct toegekend.

Na opslaan toont de pagina onder de SCIM-sectie de Tenant URL met de tenant-uuid erin (https://api.tapster.app/scim/v2/<uuid>) en een kopieer- knop. Die URL deel je in de volgende stap met Azure.

4. Configureer de Azure SCIM-applicatie

In Azure AD bij de klant:

  1. Open Azure AD > Enterprise Applications en kies de juiste applicatie (of maak een nieuwe aan).
  2. Ga naar Provisioning.
  3. Zet Provisioning Mode op Automatic.
  4. Tenant URL — plak de URL uit stap 3.
  5. Secret Token — plak het Service Account Token uit stap 2.
  6. Klik Test Connection. Verwacht: The supplied credentials are authorized.
  7. Bij Mappings, controleer dat ten minste userName, name.givenName, name.familyName, active en emails[type eq "work"].value aanwezig zijn. Voor groups: zorg dat group-membership naar groups mapt op de user.
  8. Bewaar.

5. Start provisioning en valideer

In Azure, op dezelfde provisioning-pagina:

  1. Klik Start provisioning.
  2. Wacht 5 tot 10 minuten op de eerste cycle (Azure batcht).
  3. In Tapster: open Backoffice > Gebruikers en zoek de testgebruiker op naam of e-mailadres. De lijst heeft geen filter op SCIM-herkomst; die zie je pas op de detailpagina.
  4. Open de testgebruiker en controleer:
    • Status is Actief (SCIM maakt accounts direct actief aan).
    • Onder Herkomst staat accounttype SCIM (Azure AD) met het External ID uit Azure.
    • De toegekende rollen kloppen met de mapping.
  5. Wil je de onderliggende velden zien (scimGroups, scimRoleMapping.source, mappedGroups), kijk dan in de tenant-database op het user-document. De UI toont daarvan alleen de herkomst en het External ID.

Vond je niets terug? Check de SCIM-logs:

kubectl logs -n tapster -l app=api --tail=200 | grep '\[SCIM\]'

Veelvoorkomende meldingen:

Logregel Oorzaak Oplossing
Azure group "..." heeft geen mapping configuratie Een Azure-group die de user heeft staat niet in roleMapping. Voeg de mapping toe of accepteer dat default-rollen worden gebruikt.
Onbekende rbac-referentie "..." in role-mapping De tapsterRoles verwijst naar een Rbac die niet bestaat. Corrigeer de uuid in de admin-UI.
Legacy rbac._id-waarden in role-mapping De mapping bevat nog mongo-_id-strings van vóór de switch naar rbac.uuid. Werkt nog wel, maar selecteer de rollen opnieuw in de admin-UI.
Geen Azure groups en geen default roles geconfigureerd Gebruiker had geen group-membership en er staan geen defaults. Voeg een default toe of pas de Azure-scope aan.

Krijgt Azure 429-antwoorden? Dat is de bedoelde rem: 60 requests per minuut en maximaal 3 gelijktijdige schrijfacties per tenant. Entra smeert de cycle daarna zelf uit. Alleen bij structureel vastlopen zijn SCIM_RATE_LIMIT_MAX en SCIM_CONCURRENCY_MAX te verhogen.

6. Documenteer en handover

Leg in het klant-CRM vast:

  • Datum dat SCIM aanstaat.
  • Naam van de SAT en de vervaldatum (365 dagen na aanmaak).
  • Welke Azure-groups gemapt zijn, en op welke Tapster-rollen.
  • Welke afspraak je maakte over hoe gebruikers de eerste keer inloggen.

Plan in je agenda een notificatie ~30 dagen vóór SAT-expiry om een nieuwe token aan te maken en in Azure te wisselen.

Offboarding: wat er gebeurt bij uit dienst

Zet Azure een gebruiker uit scope, dan stuurt Entra standaard een PATCH met active=false (soft delete). Tapster zet die gebruiker dan op status Inactief; inloggen lukt daarna niet meer, ook niet via SSO. Komt de gebruiker terug in scope (active=true), dan gaat het account weer naar Actief. Verwijdert Entra de gebruiker met een DELETE, dan volgt een soft delete van het account.

Twee dingen die SCIM bewust niet aanraakt:

  • Een account in Uitgenodigd/ Nog niet geactiveerd of In de wacht wordt niet alsnog op Actief gezet. De uitnodigingsflow blijft leidend.
  • Een account dat wordt geanonimiseerd of geblokkeerd is, blijft dat. Een directory-sync draait die beheerdersactie niet terug. In de logs zie je dan een [SCIM] active=... genegeerd-regel.

Achtergrond staat in explanation: SCIM-provisioning.

Een SCIM-koppeling uitschakelen

In Tapster admin-tenant-detail:

  1. Zet SCIM ingeschakeld uit.
  2. Opslaan.

Daarmee weigert het endpoint nieuwe Azure-requests met 403. De bestaande roleMapping en defaultRoles blijven bewaard (we overschrijven niets bij disable), zodat re-enable later geen herconfiguratie vraagt.

Wil je de SAT ook intrekken? Verwijder hem op de Service Account Tokens-pagina. Dat is sterker dan SCIM uitzetten en blokkeert ook andere gebruik van het token.

Verwante documenten