Control API - gebruikers en authenticator-apps

Gebruik de FoxIDs Control API om interne gebruikers te provisionen en de authenticator-apps te beheren die elke gebruiker heeft geregistreerd. Deze handleiding richt zich op bewerkingen waarmee registraties tussen FoxIDs-deployments kunnen worden gesynchroniseerd.

Voordat u deze bewerkingen aanroept, configureert u Control API-authenticatie en toegangsrechten. Swagger blijft de exacte referentie voor alle gebruikerseigenschappen, filters, validatieregels en response-schema's:

• Swagger (OpenAPI) JSON
• Swagger UI

Endpoint-basis

De voorbeelden gebruiken FoxIDs Cloud:

https://control.foxids.com/api/{tenant_name}/{track_name}

Vervang {tenant_name} door de tenantnaam en {track_name} door de technische naam van de omgeving. Wijzig de host voor een self-hosted deployment. Stuur het Control API-access token in de header Authorization: Bearer {access_token}.

Gebruikers- en authenticator-appbewerkingen vereisen een gebruikerstoegangsrecht voor de doelomgeving. Verleen via de Control API-hiërarchie voor toegangsrechten alleen de benodigde bewerking read, create, update of delete.

Gebruikersidentificaties

Elke interne gebruiker moet ten minste één aanmeldingsidentificatie hebben: e-mailadres, telefoonnummer of gebruikersnaam. E-mailadressen en gebruikersnamen worden naar kleine letters genormaliseerd en omringende spaties worden uit alle identificaties verwijderd.

Bewerkingen voor één gebruiker identificeren de gebruiker met de queryparameter email, phone of username. De gebruikersresponse bevat ook een door de server gemaakte userId. Deze ID is uniek en permanent, ook wanneer een aanmeldingsidentificatie verandert, en moet worden gebruikt om authenticator-apps of andere resources aan de gebruiker te koppelen.

Gebruikersbewerkingen

Bewerkingen voor afzonderlijke gebruikers zijn in Swagger gegroepeerd onder tenant users.

Gebruik waar nodig phone={phone} of username={username} in plaats van email={email}. Voeg elk endpoint toe aan de endpoint-basis.

Gebruikers weergeven en filteren

GET /!users accepteert filterEmail, filterPhone, filterUsername, filterUserId en filterClaimValue. Elk filter zoekt hoofdletterongevoelig naar gedeeltelijke waarden. Bij meerdere filters wordt een gebruiker geretourneerd als een van de filters overeenkomt.

De response bevat een data-collection en een niet-transparante paginationToken. Herhaal voor de volgende pagina dezelfde request met de geretourneerde waarde als paginationToken. Ga door totdat de response geen token meer bevat. Interpreteer of wijzig het token niet.

De gebruikersresponse meldt of een wachtwoord is ingesteld en wanneer dit voor het laatst is gewijzigd, maar retourneert nooit het wachtwoord of de huidige hash.

Een gebruiker maken

De create-request ondersteunt accountstatus, geverifieerde identificaties, aangepaste claims, keuze van wachtwoordbeleid, wachtwoordinstelling via e-mail of SMS en MFA-instellingen per gebruiker. Dit voorbeeld maakt een gebruiker zonder wachtwoord en vereist wachtwoordinstelling via e-mail:

POST https://control.foxids.com/api/{tenant_name}/{track_name}/!user
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "email": "alice@example.com",
  "emailVerified": true,
  "setPasswordEmail": true,
  "claims": [
    {
      "claim": "role",
      "values": ["employee"]
    }
  ]
}

Een create-request kan een wachtwoord in platte tekst, ondersteunde wachtwoordhashvelden of geen wachtwoordgegevens bevatten. Stuur nooit beide wachtwoordformaten. Wachtwoorden in platte tekst worden aan het gekozen beleid getoetst; geïmporteerde hashes niet. Gebruik zonder gegevens setPasswordEmail of setPasswordSms als de gebruiker tijdens het aanmelden een wachtwoord moet instellen.

Een bestaande gebruiker maken retourneert 409 Conflict en de gebruikerslimiet van het tenantabonnement is van toepassing. Een gelijktijdige gebruikersbewerking kan het maken tijdelijk blokkeren; probeer een 423 Locked-response na korte tijd opnieuw.

Een gebruiker bijwerken

PUT /!user is een volledige update, geen patch. Lees de huidige gebruiker, behoud ongewijzigde eigenschappen, pas wijzigingen toe en stuur de volledige bewerkbare representatie. De claims-collection en account- en MFA-vlaggen worden door de requestwaarden vervangen. Wachtwoordgegevens en authenticator-appregistraties hebben eigen bewerkingen.

Identificeer de bestaande gebruiker met email, phone of username. Behoud om een identificatie te wijzigen de huidige waarde in het veld en stel updateEmail, updatePhone of updateUsername in op de nieuwe waarde. Een lege string verwijdert de identificatie; weglaten laat deze ongewijzigd. Zorg dat ten minste één aanmeldingsidentificatie behouden blijft.

Als disableAccount van false naar true verandert, worden refresh token grants en actieve sessies ingetrokken. Opnieuw inschakelen staat nieuwe aanmeldingen toe, maar herstelt ingetrokken sessies niet.

Wachtwoorden beheren

Gebruik PUT /!usersetpassword voor administratieve instelling of migratie. Er zijn drie modi:

• Geef password op om het gekozen wachtwoordbeleid toe te passen en de geschiedenis bij te werken.
• Geef passwordHashAlgorithm, passwordHash en passwordHashSalt op om een ondersteunde vooraf berekende hash zonder beleidscontrole te importeren.
• Laat beide wachtwoordformaten weg om het huidige wachtwoord te verwijderen.

passwordLastChanged is optionele Unix-tijd in seconden. Met changePassword moet de gebruiker bij de volgende toepasselijke aanmelding een nieuw wachtwoord kiezen.

Gebruik PUT /!userchangepassword als het huidige wachtwoord bekend is. De bewerking verifieert dit en valideert het nieuwe wachtwoord tegen beleid en geschiedenis.

Het endpoint voor wachtwoordgeschiedenis is bedoeld voor gecontroleerde migratie en herstel. De detailresponse bevat wachtwoordhashmateriaal en PUT vervangt de volledige geschiedenis. Bescherm dit als geïmporteerde hashes en log geen request- of response-bodies.

Bulkprovisioning

PUT /!users accepteert 1 tot 1.000 gebruikers per request. Maximaal 100 entries mogen wachtwoorden in platte tekst bevatten, omdat elk wachtwoord veilig moet worden gehasht. Requests zonder zulke wachtwoorden, inclusief ondersteunde vooraf berekende hashes, mogen tot 1.000 gebruikers bevatten.

Bulk upload maakt nieuwe gebruikers of vervangt overeenkomende gebruikers; eigenschappen worden niet samengevoegd en e-mail-, telefoon- of gebruikersnaamidentificaties kunnen niet worden hernoemd. Behandel dit als vervangingsimport. Gebruik de update voor één gebruiker bij normale levenscycluswijzigingen waarbij bestaande status en permanente gebruikers-ID behouden moeten blijven.

DELETE /!users accepteert 1 tot 1.000 e-mailadressen, telefoonnummers of gebruikersnamen in userIdentifiers. Zie Veel gebruikers uploaden voor importformaten, prestaties en de seed tool.

Gebruikers verwijderen en toegang intrekken

Bij individuele of bulkverwijdering worden refresh token grants en actieve sessies ingetrokken voordat het account wordt verwijderd. Dit is permanent. Gebruik de delete-bewerkingen voor authenticator-apps als alleen één of alle registraties moeten worden verwijderd en de gebruiker behouden blijft.

Requests voor maken, bijwerken, wachtwoorden en verwijderen worden in het Control-auditlog opgenomen. Leesbewerkingen worden niet als audit-events geschreven.

Authenticator-appregistraties

Authenticator-appbewerkingen zijn in Swagger gegroepeerd onder tenant user authenticator apps. Een lijstbewerking retourneert veilige registratieoverzichten, terwijl de detailbewerking de gevoelige gegevens retourneert die nodig zijn voor gecontroleerde synchronisatie.

Voeg elk endpoint toe aan de endpoint-basis. Bijvoorbeeld:

GET https://control.foxids.com/api/{tenant_name}/{track_name}/!userauthenticatorapps?userId=e061ed17-7b44-48a8-b224-ecdb800ed5cc
Authorization: Bearer {access_token}

Registratieresource

Maken en bijwerken gebruiken de volledige registratieresource:

{
  "userId": "e061ed17-7b44-48a8-b224-ecdb800ed5cc",
  "id": "7a772286-76a2-4f17-a0f8-4e927bb1772d",
  "createTime": 1785769200,
  "secret": "TOTP-SHARED-SECRET",
  "recoveryCode": {
    "hashAlgorithm": "P2HS512:10",
    "hash": "RECOVERY-CODE-HASH",
    "hashSalt": "RECOVERY-CODE-SALT"
  }
}

De eigenschappen gedragen zich als volgt:

• userId is de stabiele FoxIDs-gebruikers-ID.
• id is een permanente registratie-ID die de client bij het maken opgeeft. Deze selecteert de registratie bij bijwerken en kan niet worden gewijzigd.
• createTime wordt uitgedrukt in Unix-seconden. Bij maken is deze optioneel en standaard de huidige tijd. Wanneer deze bij bijwerken wordt weggelaten, blijft de bestaande waarde behouden.
• secret is het gedeelde TOTP-secret en is vereist bij maken en bijwerken.
• recoveryCode bevat recovery code-hashgegevens en wordt weggelaten wanneer geen recovery code is geconfigureerd.

Een gebruiker kan maximaal vijf authenticator-appregistraties hebben. Maken met een bestaande registratie-ID retourneert 409 Conflict; maken nadat de limiet is bereikt retourneert 400 Bad Request.

Registraties synchroniseren

Een synchronisatieservice kan de interactieve Authenticator App notification API combineren met deze Control API-bewerkingen:

1. Ontvang de notification registered met user_id en registration_id.
2. Haal de registratie op uit de source deployment met de detailbewerking.
3. Maak de registratie in de target deployment of werk deze bij als dezelfde registratie-ID al bestaat.

Control API-bewerkingen voor maken, bijwerken en verwijderen roepen de Authenticator App notification API niet aan. Synchroniseren veroorzaakt daarom geen notification-lus.

Beveiliging

De detail-, maak- en bijwerkbewerkingen tonen of accepteren een authenticator-appsecret en recovery code-hashgegevens. Verleen het vereiste gebruikerstoegangsrecht alleen aan vertrouwde clients, gebruik TLS, bescherm payloads bij opslag en log geen request- of response-bodies.

Gebruik de lijstbewerking wanneer alleen registratie-ID's en aanmaaktijden nodig zijn. Deze retourneert geen secret of recovery code-hashgegevens.

Compatibiliteitseigenschap

De eigenschap activeTwoFactorApp van de algemene gebruikers-API is deprecated en gepland voor verwijdering na 1 augustus 2027. In een update-request verwijdert false om compatibiliteitsredenen nog steeds alle authenticator-appregistraties; true of een weggelaten waarde laat registraties ongewijzigd. Nieuwe integraties moeten de authenticator-appendpoints gebruiken.

Foutresponses

Veelvoorkomende foutresponses voor gebruikers- en authenticator-appbewerkingen zijn:

• 400 Bad Request wanneer identificaties, gegevens, filters of resourcegegevens ongeldig zijn, of de registratielimiet is bereikt.
• 401 Unauthorized wanneer het access token ontbreekt of ongeldig is.
• 403 Forbidden wanneer de client niet het vereiste gebruikerstoegangsrecht voor de omgeving heeft.
• 404 Not Found wanneer de gebruiker of authenticator-appregistratie niet bestaat.
• 409 Conflict wanneer de gebruiker al bestaat of een registratie-ID opnieuw wordt gebruikt.
• 423 Locked wanneer maken of bulkimport tijdelijk is vergrendeld. Probeer het na korte tijd opnieuw.

Gebruik de response-body voor validatiedetails. Raadpleeg Swagger UI voor de responses die voor elke bewerking zijn gedeclareerd.

Gerelateerde documentatie

• Control API-authenticatie en toegangsrechten
• Overzicht van FoxIDs Control
• Interne gebruikers
• Twee-factor- en multi-factor-authenticatie
• Veel gebruikers uploaden