Skip to Content

Dynamische clientregistratie

Laat clientapplicaties zichzelf registreren via OAuth 2.0 Dynamic Client Registration, met initial access tokens.

Opmerking: Beschikbaar met het abonnement Advanced en Pro. Open registratie voor AI-agents vereist Pro.

Met dynamische clientregistratie registreert een clientapplicatie zichzelf, in plaats van handmatig in de Admin Console te worden aangemaakt. De client stuurt zijn metadata (naam, redirect-URI's, clientauthenticatie) naar het registratie-endpoint en ontvangt in ruil een client-ID en, voor vertrouwelijke clients, een clientgeheim. Het platform implementeert OAuth 2.0 Dynamic Client Registration (RFC 7591) en het beheerprotocol waarmee de client zijn eigen registratie later kan lezen, bijwerken en verwijderen (RFC 7592).

Standaard vereist elke registratie een initial access token dat u uitgeeft, zodat u bepaalt wie clients mag registreren en hoe vaak. Voor AI-agents en andere public clients kunt u daarnaast open registratie toestaan.

U beheert initial access tokens in de Admin Console onder Integraties → Applicaties → Dynamische registraties.

Hoe het werkt

  1. U geeft een initial access token uit en overhandigt dit aan de partij die de client registreert, bijvoorbeeld een partner of een implementatiepipeline.
  2. De client stuurt een registratieverzoek naar het registratie-endpoint, met het initial access token als Bearer-token.
  3. Het platform toetst de metadata aan de onderstaande regels, maakt de applicatie aan en antwoordt met de clientgegevens plus een registration access token en de eigen beheer-URL van de client.
  4. Met het registration access token kan de client zijn registratie lezen, bijwerken of verwijderen. Elke update geeft een nieuw registration access token uit en maakt het vorige ongeldig.

De geregistreerde client wordt op het tabblad Dynamische registraties vermeld onder Geregistreerde applicaties, samen met de manier waarop hij zich heeft geregistreerd en wanneer hij voor het laatst is gebruikt. De detailpagina is dezelfde als voor elke andere applicatie, gemarkeerd als Dynamisch geregistreerd. Nog niemand kan zich erbij aanmelden: zoals bij elke nieuwe applicatie moet de toegang eerst worden toegewezen.

Een initial access token uitgeven

  1. Ga naar Integraties → Applicaties en open het tabblad Dynamische registraties.
  2. Selecteer Token uitgeven.
  3. Voer een Naam in, bijvoorbeeld de partner of het systeem waarvoor het token bedoeld is. Deze verschijnt in de lijst en in het auditlog.
  4. Stel de Geldigheid in dagen in (1 tot 365). Het token verloopt na deze periode.
  5. Laat Eenmalig geselecteerd als het token precies één registratie moet toestaan. Schakel het uit om een onbeperkt aantal registraties toe te staan totdat het token verloopt.
  6. Selecteer Token uitgeven en kopieer het token. Het wordt slechts één keer getoond en kan later niet worden opgehaald.

De pagina toont ook het Registratie-endpoint dat u samen met het token doorgeeft. Het wordt ook gepubliceerd als registration_endpoint in het OpenID Connect-discoverydocument.

De lijst toont voor elk token het gebruik, het aantal registraties dat ermee is gedaan, de vervaldatum en wie het heeft uitgegeven. Intrekken zorgt ervoor dat een token niet meer voor nieuwe registraties kan worden gebruikt. Applicaties die er al mee zijn geregistreerd, blijven ongemoeid. Verlopen tokens worden automatisch verwijderd.

Open registratie voor AI-agents

Opmerking: Beschikbaar met het abonnement Pro.

AI-agents, bijvoorbeeld clients van het Model Context Protocol (MCP), en opdrachtregeltools registreren zichzelf op het moment dat een gebruiker ze koppelt, zonder dat iemand een token uitdeelt. Elke installatie registreert doorgaans een eigen client. Open registratie staat precies dat toe voor public clients, die geen clientgeheim hebben en gebruikers aanmelden met de authorization code flow en PKCE.

  1. Ga naar Instellingen → Geavanceerd.
  2. Schakel op de kaart Open registratie de optie Open registratie voor public clients in.
  3. Selecteer onder Gebruikers die zich mogen aanmelden de directories waarvan de gebruikers zulke clients mogen gebruiken.
  4. Selecteer Wijzigingen opslaan.

Voor open geregistreerde clients geldt:

  • Alleen public clients worden geaccepteerd. Een registratie zonder initial access token moet "token_endpoint_auth_method": "none" meesturen, en de client blijft public: een latere update kan geen clientgeheim toevoegen. Vertrouwelijke clients hebben nog steeds een initial access token nodig.
  • Toegang komt van de directories. Gebruikers van de geselecteerde directories mogen zich aanmelden nadat ze toestemming hebben gegeven, zonder toewijzing per applicatie. De selectie geldt voor nieuwe registraties; applicaties die al zijn geregistreerd, behouden de directories waarmee ze zijn geregistreerd.
  • Registraties zijn begrensd tot 10 per uur per IP-adres van de client en 200 per uur in totaal (20 tijdens de proefperiode).
  • Ongebruikte registraties worden verwijderd. Een client waarbij zich niemand heeft aangemeld, wordt na 24 uur verwijderd, evenals een client zonder aanmeldingen of tokenverzoeken gedurende 90 dagen. Elke verwijdering wordt in het auditlog vastgelegd.
  • Er is geen eigenaar. Open geregistreerde applicaties worden niet aan een beheerder toegewezen.

Het registratie-endpoint wordt aangekondigd in het discoverydocument, dat wordt aangeboden op /.well-known/openid-configuration en, voor OAuth-clients die daar zoeken, op /.well-known/oauth-authorization-server. Vraagt een agent een access token aan voor een specifieke resource, zoals een MCP-server, registreer die resource dan als API.

Het uitschakelen van open registratie stopt nieuwe anonieme registraties. Clients die al zijn geregistreerd, blijven werken en kunnen hun registratie nog steeds beheren. Zonder het abonnement Pro krijgen gebruikers van de directories niet langer automatisch toegang tot open geregistreerde clients: wijs ze expliciet toe, anders worden de ongebruikte clients na 90 dagen verwijderd.

Een client registreren

De client stuurt zijn metadata als JSON-POST-verzoek:

curl -X POST https://id.example.com/oidc/register \
  -H "Authorization: Bearer <initial access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Partner Portal",
    "redirect_uris": ["https://portal.partner.example/callback"],
    "post_logout_redirect_uris": ["https://portal.partner.example/"],
    "grant_types": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_method": "client_secret_basic"
  }'

Een geslaagde registratie antwoordt met 201 Created:

{
  "client_id": "V1StGXR8_Z5jdHi6B-myT",
  "client_secret": "...",
  "client_name": "Partner Portal",
  "redirect_uris": ["https://portal.partner.example/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic",
  "registration_client_uri": "https://id.example.com/oidc/register/V1StGXR8_Z5jdHi6B-myT",
  "registration_access_token": "..."
}

De client bewaart client_secret en registration_access_token veilig. Geen van beide kan opnieuw worden opgehaald.

De registratie beheren

De client beheert zijn registratie op registration_client_uri, geauthenticeerd met zijn huidige registration access token:

VerzoekEffect
GETGeeft de huidige registratie terug.
PUTVervangt de registratie door de verzonden metadata. De body moet client_id bevatten; een weggelaten veld wordt verwijderd. Het antwoord bevat een nieuw registration access token.
DELETEVerwijdert de applicatie. De gebruikers ervan kunnen zich er niet meer bij aanmelden.

Een beheerder kan een dynamisch geregistreerde applicatie in de Admin Console bewerken of verwijderen zoals elke andere. Houd er rekening mee dat de volgende PUT van de client de velden overschrijft die de client beheert (naam, redirect-URI's, grant types, clientauthenticatie, client-URI en clientsleutels). Toewijzingen, beleid, eigenaren en de instelling voor toestemming blijven zoals de beheerder ze heeft ingesteld.

Wat een geregistreerde client kan zijn

MetadataRegel
token_endpoint_auth_methodclient_secret_basic (standaard), client_secret_post, private_key_jwt of none.
ApplicatietypeAfgeleid van de clientauthenticatie: none maakt een single-page-applicatie aan, of een native applicatie wanneer "application_type": "native" wordt meegestuurd of elke redirect-URI een loopbackadres is (http://127.0.0.1, http://[::1], http://localhost) of een app-specifiek schema. Een native loopback-redirect matcht op elke poort. Elke andere methode maakt een webapplicatie aan. Een native client moet none gebruiken.
grant_typesMoet authorization_code bevatten, mag refresh_token toevoegen. Implicit, client credentials, device en token exchange grants worden geweigerd.
response_typesAlleen code.
redirect_uris, post_logout_redirect_urisGeen wildcards, geen URI's op het eigen domein van de identity provider.
client_uriMoet https gebruiken.
jwksAlleen openbare sleutels, RSA met ten minste 2048 bits of EC op de curve P-256. Nodig voor private_key_jwt.
jwks_uri, sector_identifier_uri, backchannel_logout_uri, request_urisGeweigerd, omdat het platform deze URL's zelf zou moeten aanroepen. Een beheerder kan de bijbehorende opties achteraf op de applicatie instellen.
client_nameOptioneel. Zonder naam heet de applicatie "Dynamic client", gevolgd door de client-ID. Aan een naam die al in gebruik is, wordt een deel van de client-ID toegevoegd.
default_max_ageGeaccepteerd.

Alle andere metadata worden genegeerd en maken geen deel uit van het antwoord.

Sommige instellingen worden altijd door het platform bepaald, wat het verzoek ook bevat:

  • Toestemming van gebruiker vereisen is ingeschakeld. Gebruikers bevestigen de aangevraagde toegang bij de eerste aanmelding, en refresh tokens worden alleen uitgegeven wanneer de client de scope offline_access aanvraagt.
  • Er wordt geen beveiligingsprofiel toegepast. Een beheerder kan er achteraf een instellen, zie Financial-grade API-beveiliging.
  • De applicatie wordt niet vermeld in het applicatieportaal van de gebruikers.
  • De beheerder die het initial access token heeft uitgegeven, wordt eigenaar van de applicatie. Open geregistreerde applicaties hebben geen eigenaar.

Registraties tellen mee voor de applicatielimiet van uw abonnement.

Auditlog

GebeurtenisVastgelegd wanneer
INITIAL_ACCESS_TOKEN_CREATEDEen beheerder een initial access token uitgeeft.
INITIAL_ACCESS_TOKEN_REVOKEDEen beheerder een initial access token intrekt.
CONFIGURATION_UPDATEDEen beheerder open registratie in- of uitschakelt of de directories ervan wijzigt.
APPLICATION_REGISTEREDEen client zich registreert. De registrerende client wordt als actor vastgelegd.
APPLICATION_UPDATEDEen client zijn registratie bijwerkt.
APPLICATION_DEREGISTEREDEen client zijn registratie verwijdert, een beheerder de applicatie verwijdert of een ongebruikte open registratie wordt verwijderd.

Zie Auditgebeurtenistypen voor de volledige lijst.

Probleemoplossing

  • invalid_token bij registratie: het initial access token is onbekend, verlopen of ingetrokken, of een eenmalig token is al gebruikt. Geef een nieuw token uit. Zonder token is open registratie uitgeschakeld.
  • 429 bij een anonieme registratie: de rate limit van open registratie is bereikt. Probeer het later opnieuw.
  • invalid_token bij lezen, bijwerken of verwijderen: het registration access token is bij de laatste update vervangen door een nieuwer token, of de applicatie is verwijderd.
  • invalid_client_metadata met "dynamic client registration is not available": het abonnement omvat de functie niet. Registraties en updates worden geweigerd; het lezen en verwijderen van een bestaande registratie blijft werken.
  • invalid_client_metadata: de metadata overtreden een van de bovenstaande regels. De error_description noemt het veld. Een geweigerd verzoek verbruikt geen eenmalig token.
  • Gebruikers kunnen zich na de registratie niet aanmelden: de applicatie heeft nog geen toewijzingen. Wijs gebruikers, groepen of directories toe op het tabblad Toewijzingen van de applicatie. Controleer bij een open geregistreerde client of de gebruiker tot een van de directories ervan behoort.

Zie ook

Op deze pagina