Een eigen inlogprovider instellen met een sleutel¶

Wat een eigen inlogprovider is en voor wie hij werkt, staat in Organisaties en klanten.

Een sleutel met de capability management laat de beheerders van zijn eigen organisatie inloggen in de console via de identity provider van die organisatie: OpenID Connect, Google Workspace of Microsoft Entra ID. Hoe je management aanzet, staat in Je organisatie beheren met een sleutel. Zonder die capability antwoordt elke route op deze pagina 404.

De routes gaan alleen over de eigen organisatie van de sleutel. Voor een organisatie onder je stel je het in in de console, of met een sleutel die je in die organisatie registreert (Werken in een organisatie onder je).

Vier regels gelden bij elke provider:

• Niemand krijgt een account door in te loggen. Alleen wie de organisatie al als beheerder heeft uitgenodigd kan zo inloggen, herkend aan het e-mailadres dat de provider heeft geverifieerd.
• De tweede factor van de provider telt. Vraagt de provider om een code, dan vraagt de console er geen tweede.
• Wie beheerder is van meer dan één organisatie, kan via de provider van geen enkele organisatie inloggen en logt in met een wachtwoord.
• Een provider verwijderen verwijdert geen accounts. Wie ook een wachtwoord heeft, logt daar nog mee in.

Een e-maildomein bewijzen¶

Een provider laat alleen adressen inloggen in een e-maildomein waarvan de organisatie heeft bewezen dat het van haar is. Een provider registreren voor een organisatie die nog geen domein bewees, wordt geweigerd. Claim eerst het domein:

curl -s -X POST "$CORE_URL/organisation/email-domains" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"domain": "example.com"}'

Het antwoord (201) noemt het TXT-record dat het domein bewijst:

{
  "object": "email_domain",
  "domain": "example.com",
  "verified": false,
  "proof_record_name": "_artific-challenge.example.com",
  "proof_record_value": "<willekeurige waarde>",
  "verified_at": null,
  "created_at": "2026-10-07T09:12:00Z"
}

Publiceer bij wie de DNS van je domein beheert een TXT-record op proof_record_name met proof_record_value als waarde. Vraag daarna om de controle:

curl -s -X POST "$CORE_URL/organisation/email-domains/example.com/verify" \
    -H "Authorization: Bearer $CORE_KEY"

Het antwoord is hetzelfde domein met verified: true en verified_at ingevuld. Een domein dat al bewezen is, opnieuw laten controleren verandert niets. GET /organisation/email-domains toont alle geclaimde domeinen in één pagina; een organisatie claimt er hoogstens vijftig.

DELETE /organisation/email-domains/example.com geeft het domein op (204). Je provider laat daar meteen niemand meer inloggen; accounts blijven bestaan. Antwoordt het 503, dan staat de claim nog; stuur hetzelfde verzoek later opnieuw.

De hosts van de provider toestaan¶

De inlogdienst praat namens je organisatie met de provider, dus de organisatie moet de hosts van de provider toestaan voordat je hem registreert:

Voeg elke host toe met POST /organisation/allowed-hosts:

curl -s -X POST "$CORE_URL/organisation/allowed-hosts" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"host": "login.microsoftonline.com"}'

Dat antwoordt 403 zolang de organisatie erboven het sleutelbeheer voor zichzelf houdt (Voorbehouden sleutelbeheer); vraag die organisatie dan de host toe te staan.

Een provider registreren¶

PUT /organisation/sign-in-providers/{name} maakt de provider met die naam aan, of vervangt hem. De naam bestaat uit kleine letters, cijfers en koppeltekens, hoogstens 32 tekens, niet aan het begin of einde een koppelteken. Hij komt in het redirect-adres, dus kies hem eenmalig.

curl -s -X PUT "$CORE_URL/organisation/sign-in-providers/entra" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{
          "kind": "entra",
          "directory_id": "8c1f5a2e-3b4d-4e6f-9a0b-1c2d3e4f5a6b",
          "client_id": "<client-id bij je provider>",
          "client_secret": "<client secret bij je provider>",
          "display_name": "Jansen"
        }'

kind bepaalt welk ene veld de body daarnaast draagt:

client_id en client_secret zijn die van de client die je bij je provider voor deze console aanmaakte; display_name is optioneel. Het secret komt nooit terug in een antwoord. Een vervanging draagt het opnieuw mee: zonder client_secret wordt de body geweigerd.

Het antwoord (200) is de provider zoals hij nu staat:

{
  "object": "sign_in_provider",
  "name": "entra",
  "kind": "entra",
  "issuer": "https://login.microsoftonline.com/8c1f5a2e-3b4d-4e6f-9a0b-1c2d3e4f5a6b/v2.0",
  "hosted_domain": null,
  "directory_id": "8c1f5a2e-3b4d-4e6f-9a0b-1c2d3e4f5a6b",
  "client_id": "<client-id bij je provider>",
  "display_name": "Jansen",
  "enabled": true,
  "sign_in_hint": "org.ten_8f2c41.entra",
  "redirect_uri": "https://login.example.com/realms/artific/broker/org.ten_8f2c41.entra/endpoint"
}

Het redirect-adres registreren en de link delen¶

Het antwoord geeft twee dingen die je verder nodig hebt:

• redirect_uri registreer je bij je client van de provider als toegestaan redirect-adres. De provider werkt pas zodra dat is gebeurd. Vroeg de provider om een redirect-adres voordat je de client kon aanmaken, maak hem dan aan met een tijdelijk adres, registreer de provider hier en vervang het tijdelijke adres door redirect_uri.
• sign_in_hint maakt de inloglink. De gewone inlogpagina toont de providers van geen enkele organisatie, dus geef je beheerders het inlogadres van de console met de hint erin: https://<adres-van-de-console>/nl/login?provider=org.ten_8f2c41.entra (of /en/ voor de Engelse console). Wie de link opent, gaat rechtstreeks naar je provider (Inloggen).

Providers lezen, wijzigen en verwijderen¶

Elke registratie en verwijdering komt als beheergebeurtenis op het spoor van de organisatie (Beheergebeurtenissen), zonder het secret.