Control API - brukere og authenticator-apper

Bruk FoxIDs Control API til å provisionere interne brukere og administrere authenticator-appene hver bruker har registrert. Veiledningen fokuserer på operasjoner som kan brukes til å synkronisere registreringer mellom FoxIDs-deployments.

Før du kaller operasjonene, må du konfigurere Control API-autentisering og tilgangsrettigheter. Swagger er fortsatt den nøyaktige referansen for alle brukeregenskaper, filtre, valideringsregler og response-skjemaer:

• Swagger (OpenAPI) JSON
• Swagger UI

Endpoint-base

Eksemplene bruker FoxIDs Cloud:

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

Erstatt {tenant_name} med tenantnavnet og {track_name} med miljøets tekniske navn. Bytt host for et self-hosted deployment. Send Control API-access token i headeren Authorization: Bearer {access_token}.

Bruker- og authenticator-appoperasjoner krever en brukertilgangsrettighet for det valgte miljøet. Tildel bare den nødvendige operasjonen read, create, update eller delete gjennom Control API-hierarkiet for tilgangsrettigheter.

Brukeridentifikatorer

Hver intern bruker må ha minst én av disse påloggingsidentifikatorene: e-postadresse, telefonnummer eller brukernavn. E-postadresser og brukernavn normaliseres til små bokstaver, og innledende og avsluttende mellomrom fjernes fra alle identifikatorer.

Operasjonene for én bruker identifiserer brukeren med query-parameteren email, phone eller username. Brukerresponset inneholder også en servergenerert userId. Denne ID-en er unik og permanent, også når en påloggingsidentifikator endres, og bør brukes når authenticator-apper eller andre ressurser knyttes til brukeren.

Brukeroperasjoner

Operasjoner for enkeltbrukere grupperes under tenant users i Swagger.

Bruk phone={phone} eller username={username} i stedet for email={email} i eksemplene for enkeltbrukere når det passer. Legg hvert endpoint til endpoint-basen.

List og filtrer brukere

GET /!users godtar filterEmail, filterPhone, filterUsername, filterUserId og filterClaimValue. Hvert filter utfører et søk som ikke skiller mellom store og små bokstaver og samsvarer med delstrenger. Når flere filtre oppgis, returneres en bruker hvis minst ett filter samsvarer.

Responset inneholder en data-collection og et ugjennomsiktig paginationToken. Hent neste side ved å gjenta samme request og sende den returnerte verdien som paginationToken. Fortsett til responset ikke lenger inneholder en token. Tokenet skal ikke tolkes eller endres.

Brukerresponset angir om et passord er konfigurert og når det sist ble endret, men returnerer aldri passordet eller den gjeldende hashen.

Opprett en bruker

Opprettingsrequestet støtter kontostatus, verifiserte identifikatorer, egendefinerte claims, valg av passordpolicy, oppsett av passord via e-post eller SMS og MFA-innstillinger per bruker. Følgende request oppretter for eksempel en bruker uten passord og krever oppsett av passord via e-post:

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"]
    }
  ]
}

Et opprettingsrequest kan inneholde et passord i klartekst, støttede passordhashfelt eller ingen passordopplysninger. Send aldri begge passordformatene. Passord i klartekst kontrolleres mot valgt passordpolicy; importerte hasher policykontrolleres ikke. Hvis ingen opplysninger oppgis, kan setPasswordEmail eller setPasswordSms brukes når brukeren skal opprette et passord under pålogging.

Oppretting av en bruker som allerede finnes, returnerer 409 Conflict, og tenantens plangrense for brukere gjelder. En samtidig brukeroperasjon kan midlertidig blokkere opprettingen; prøv igjen etter kort tid ved 423 Locked.

Oppdater en bruker

PUT /!user er en fullstendig oppdatering, ikke en patch. Hent gjeldende bruker, behold egenskapene som ikke skal endres, bruk de ønskede endringene og send hele den redigerbare representasjonen. Claims-collectionen og konto- og MFA-flaggene erstattes av verdiene i requestet. Passordopplysninger og authenticator-appregistreringer administreres gjennom egne operasjoner.

Identifiser eksisterende bruker med email, phone eller username. For å endre en identifikator beholder du gjeldende verdi i feltet og setter updateEmail, updatePhone eller updateUsername til den nye verdien. Sett en update-egenskap til en tom streng for å fjerne identifikatoren; utelat den for å la identifikatoren være uendret. Sørg for at brukeren beholder minst én påloggingsidentifikator.

Når disableAccount endres fra false til true, tilbakekalles brukerens refresh token grants og aktive sesjoner. Reaktivering av kontoen tillater nye pålogginger, men gjenoppretter ikke tilbakekalte sesjoner.

Administrer passord

Bruk PUT /!usersetpassword for administrativ passordsetting eller migrering. Den støtter tre moduser:

• Oppgi password for å bruke valgt passordpolicy og oppdatere passordhistorikken.
• Oppgi passwordHashAlgorithm, passwordHash og passwordHashSalt for å importere en støttet forhåndsberegnet hash uten policyvalidering.
• Utelat begge passordformatene for å fjerne brukerens gjeldende passord.

Den valgfrie verdien passwordLastChanged er Unix-tid i sekunder. Bruk changePassword for å kreve at brukeren velger et nytt passord ved neste relevante pålogging.

Bruk PUT /!userchangepassword når gjeldende passord er kjent. Operasjonen verifiserer gjeldende passord og validerer det nye mot brukerens passordpolicy og historikk.

Endpointet for passordhistorikk er beregnet for kontrollerte migrerings- og gjenopprettingsscenarier. Detaljresponset inneholder passordhashmateriale, og PUT erstatter hele historikken. Beskytt det på samme måte som importerte passordhasher, og ikke logg request- eller response-bodies.

Masseprovisionering

PUT /!users godtar mellom 1 og 1 000 brukere per request. Maksimalt 100 entries kan inneholde passord i klartekst fordi hvert passord må hashes sikkert. Requests uten passord i klartekst, inkludert requests med støttede forhåndsberegnede hasher, kan inneholde opptil 1 000 brukere.

Masseopplasting oppretter nye brukere eller erstatter samsvarende brukere; den slår ikke sammen enkeltegenskaper og kan ikke endre navn på e-post-, telefon- eller brukernavnidentifikatorer. Behandle den som en erstatningsimport. Bruk oppdateringsoperasjonen for én bruker ved normale livssyklusendringer der eksisterende brukertilstand og den permanente bruker-ID-en må beholdes.

DELETE /!users godtar mellom 1 og 1 000 e-postadresser, telefonnumre eller brukernavn i userIdentifiers. Se Last opp mange brukere for importformater, ytelsesveiledning og seed tool.

Slett brukere og tilbakekall tilgang

Når en bruker slettes enkeltvis eller i bulk, tilbakekalles brukerens refresh token grants og aktive sesjoner før kontoen slettes. Dette er en permanent kontooperasjon. Bruk authenticator-appens delete-operasjoner når bare én eller alle registreringer skal fjernes mens brukeren beholdes.

Requests for oppretting, oppdatering, passord og sletting inkluderes i Control-auditloggen. Leseoperasjoner skrives ikke som audit-events.

Authenticator-appregistreringer

Authenticator-appoperasjoner grupperes under tenant user authenticator apps i Swagger. En listeoperasjon returnerer sikre registreringsoversikter, mens detaljoperasjonen returnerer sensitive data som kreves for kontrollert synkronisering.

Legg hvert endpoint til endpoint-basen. Eksempel:

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

Registreringsressurs

Opprett og oppdater bruker hele registreringsressursen:

{
  "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"
  }
}

Egenskapene har følgende oppførsel:

• userId er brukerens stabile FoxIDs-ID.
• id er en permanent registrerings-ID som klienten angir ved oppretting. Den velger registreringen ved oppdatering og kan ikke endres.
• createTime angis i Unix-sekunder. Den er valgfri ved oppretting og får gjeldende tid som standard. Hvis den utelates ved oppdatering, beholdes eksisterende verdi.
• secret er den delte TOTP-secreten og kreves ved oppretting og oppdatering.
• recoveryCode inneholder recovery code-hashdata og utelates når ingen recovery code er konfigurert.

En bruker kan ha maksimalt fem authenticator-appregistreringer. Oppretting med en registrerings-ID som allerede finnes returnerer 409 Conflict; oppretting etter at grensen er nådd returnerer 400 Bad Request.

Synkroniser registreringer

En synkroniseringstjeneste kan kombinere det interaktive Authenticator App notification API med disse Control API-operasjonene:

1. Motta notificationen registered som inneholder user_id og registration_id.
2. Hent registreringen fra source deployment med detaljoperasjonen.
3. Opprett registreringen i target deployment, eller oppdater den hvis samme registrerings-ID allerede finnes.

Control API-operasjoner for oppretting, oppdatering og sletting kaller ikke Authenticator App notification API. Synkronisering skaper derfor ikke en notification-loop.

Sikkerhet

Detalj-, opprettings- og oppdateringsoperasjonene eksponerer eller mottar en authenticator-appsecret og recovery code-hashdata. Gi nødvendig brukertilgang bare til betrodde klienter, bruk TLS, beskytt payloads ved lagring og ikke logg request- eller response-bodies.

Bruk listeoperasjonen når bare registrerings-ID-er og opprettingstidspunkter er nødvendige. Den returnerer ikke secret eller recovery code-hashdata.

Kompatibilitetsegenskap

Egenskapen activeTwoFactorApp i det generelle bruker-API-et er deprecated og planlagt fjernet etter 1. august 2027. I en update-request sletter false fortsatt alle authenticator-appregistreringer av kompatibilitetshensyn; true eller en utelatt verdi lar registreringene være uendret. Nye integrasjoner bør bruke authenticator-appendpoints.

Feilresponses

Vanlige feilresponses for bruker- og authenticator-appoperasjoner er:

• 400 Bad Request når identifikatorer, opplysninger, filtre eller ressursdata er ugyldige, eller registreringsgrensen er nådd.
• 401 Unauthorized når access token mangler eller er ugyldig.
• 403 Forbidden når klienten mangler nødvendig brukertilgangsrettighet for miljøet.
• 404 Not Found når brukeren eller valgt authenticator-appregistrering ikke finnes.
• 409 Conflict når brukeren allerede finnes eller en registrerings-ID brukes på nytt.
• 423 Locked når oppretting eller masseimport er midlertidig låst. Prøv igjen etter kort tid.

Bruk response-body for valideringsdetaljer. Se Swagger UI for responsene som er deklarert for hver operasjon.

Relatert dokumentasjon

• Control API-autentisering og tilgangsrettigheter
• Oversikt over FoxIDs Control
• Interne brukere
• To-faktor- og multi-faktorautentisering
• Last opp mange brukere