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 mogen maximaal 100 tekens lang zijn en gebruikersnamen maximaal 60 tekens. E-mailadressen en gebruikersnamen worden naar kleine letters genormaliseerd en omringende witruimte wordt 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.

Behoud bij updates van Directory Connector-gebruikers de stabiele koppeling via directoryUserId. Synchronisatie op aanvraag vervangt directory-identificaties, accountinstellingen en claims; wijzig die waarden in de leidende directory. Authenticator-registraties en FoxIDs toegangstoewijzingen blijven behouden.

Gebruikersbewerkingen

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

Aangepaste claims kunnen een optionele valueType bevatten: String, Boolean, Number, JsonObject of JsonArray. Alle items in values blijven tekenreeksen en delen het geselecteerde type. Laat valueType weg voor String. De API weigert waarden die niet overeenkomen met het geselecteerde type; behoud het type bij het lezen en bijwerken van claims. Dezelfde keuzes gelden voor claims op nodes van toegangsstructuren en claims voor de eerste beheerder bij het maken van een tenant. Zie typen claimwaarden voor getalgrenzen en gedrag in JWT/SAML.

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.

Aangepaste gebruikersclaims kunnen geen beschermde claimnamen gebruiken, zoals sid en auth_time.

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 en passwordHash op, plus passwordHashSalt wanneer het algoritme dit vereist, om een ondersteunde vooraf berekende hash zonder beleidsvalidatie te importeren.
• Laat beide wachtwoordformaten weg om het huidige wachtwoord te verwijderen.

Dezelfde hashformaten worden geaccepteerd bij het aanmaken van een gebruiker of bulkprovisioning:

Dit administratieve wachtwoordverzoek importeert bijvoorbeeld een synthetische bcrypt hash:

{
  "email": "alice@example.com",
  "passwordHashAlgorithm": "bcrypt",
  "passwordHash": "$2b$10$..CA.uOD/eaGAOmJB.yMBu3YunYvFEoaS5IJZ/wiqfQ/EWx.HaqjC"
}

Neem password niet samen met hashvelden op. Een hash of salt zonder bijbehorend algoritme wordt geweigerd. Ongeldig gevormde bcrypt tekenreeksen, niet-ondersteunde varianten, kostenfactoren buiten het ondersteunde bereik en afzonderlijke bcrypt salts worden vóór opslag geweigerd. Zie wachtwoordhashing voor parameters en de wachtwoordlimiet van bcrypt van 72 bytes.

De optionele waarde passwordLastChanged is Unix-tijd in seconden. Gebruik changePassword om de gebruiker bij de volgende toepasselijke aanmelding een nieuw wachtwoord te laten kiezen. Hashimport slaat controles van het wachtwoordbeleid tijdens import over; het gekozen beleid geldt nog steeds bij aanmelding. Aanmelding behoudt de geïmporteerde hash en het wachtwoordwijzigingstijdstip. Het instellen of wijzigen van een wachtwoord in platte tekst gebruikt het standaard PBKDF2-formaat.

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 herstelscenario's. Het accepteert ook bcrypt geschiedenisitems met dezelfde formaat- en kostenfactorlimieten en zonder afzonderlijke salt. Het detailantwoord bevat wachtwoordhashmateriaal en PUT vervangt de volledige geschiedenis. Behandel dit met dezelfde beschermingsmaatregelen als geïmporteerde wachtwoordhashes en log geen verzoek- of antwoordinhoud.

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.

Blokkeringen bij mislukte aanmelding

Gebruik de lijst- en detailbewerkingen voor aanmeldblokkeringen om blokkeringen te onderzoeken en verwijder een blokkering wanneer een beheerder toestemming geeft om deze op te heffen.

Gebruikersgebonden blokkeringen hebben een userIdentifier. Gebruik die waarde en het fouttype om een gebruikersblokkering op te halen of op te heffen. Het lijstfilter filterUserIdentifier vergelijkt identificaties hoofdletterongevoelig.

Blokkeringen van het type DirectorySynchronisation hebben een sequenceId en laten userIdentifier weg. Gebruik de exacte, hoofdlettergevoelige sequenceId en het fouttype om een synchronisatieblokkering op te halen of op te heffen, zonder de parameter userIdentifier. Gebruik filterSequenceId om blokkeringen voor die sequentie te vinden. Samen vinden filterUserIdentifier en filterSequenceId blokkeringen die bij een van de waarden passen; een fouttypefilter blijft op alle resultaten van toepassing. De zoeklimiet wordt gedeeld door alle identificaties in dezelfde sequentie.

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.

Geïmpersoneerde sessies

Actieve sessies behouden de identificatoren van de oorspronkelijk geauthenticeerde gebruiker. Impersonatiedetails identificeren de doelgebruiker afzonderlijk, inclusief subject, subjectformaat, e-mail, telefoon, gebruikersnaam en interne accountverwijzing indien beschikbaar. U kunt een actieve sessie vinden met de identificatoren van beide gebruikers.

Refresh token claims vertegenwoordigen de aan de applicatie uitgegeven identiteit; de impersonatiedetails van de grant identificeren de oorspronkelijk geauthenticeerde gebruiker en het geselecteerde target. Beide gekoppelde accounts worden meegenomen bij het intrekken van toegang. Zie impersonatie voor stroomconfiguratie en sessiegedrag.

Gerelateerde documentatie

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