Control API - brugere og authenticator-apps

Brug FoxIDs Control API til at provisionere interne brugere og administrere de authenticator-apps, som hver bruger har registreret. Denne vejledning fokuserer på authenticator-app-operationer, der kan bruges til at synkronisere registreringer mellem FoxIDs-deployments.

Før du kalder operationerne, skal du konfigurere Control API-autentificering og adgangsrettigheder. Swagger er fortsat den præcise reference for alle brugeregenskaber, filtre, valideringsregler og response-skemaer:

• Swagger (OpenAPI) JSON
• Swagger UI

Endpoint-base

Eksemplerne bruger FoxIDs Cloud:

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

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

Bruger- og authenticator-app-operationer kræver en brugeradgangsrettighed til det valgte miljø. Tildel kun den nødvendige read-, create-, update- eller delete-operation gennem Control API-adgangsrettighedshierarkiet.

Brugeridentifikatorer

Hver intern bruger skal have mindst én af disse loginidentifikatorer: e-mail, telefonnummer eller brugernavn. E-mailadresser kan være op til 100 tegn, og brugernavne kan være op til 60 tegn. E-mailadresser og brugernavne normaliseres til små bogstaver, og omgivende blanktegn fjernes fra alle identifikatorer.

Operationerne for en enkelt bruger identificerer brugeren med query-parameteren email, phone eller username. Brugerresponset indeholder også et servergenereret userId. Dette ID er unikt og permanent, også når en loginidentifikator ændres, og bør bruges, når authenticator-apps eller andre ressourcer knyttes til brugeren.

For brugere med Directory Connector skal den stabile binding via directoryUserId bevares ved kontoopdatering. Synkronisering efter behov erstatter katalogets identifikatorer, kontoindstillinger og claims; ændr disse værdier i det autoritative katalog. Registreringer af autentificeringsapps og adgangstildelinger i FoxIDs bevares.

Brugeroperationer

Operationer for enkelte brugere er samlet under tenant users i Swagger.

Brugerdefinerede claims kan have en valgfri valueType: String, Boolean, Number, JsonObject eller JsonArray. Alle poster i values forbliver strenge og deler den valgte type. Udelad valueType for String. API'et afviser værdier, der ikke matcher den valgte type; bevar typen ved læsning og opdatering af claims. De samme valgmuligheder gælder for claims på adgangsstrukturnoder og claims for den første administrator ved oprettelse af en tenant. Se claimværdiers typer for talgrænser og adfærd i JWT/SAML.

Brug phone={phone} eller username={username} i stedet for email={email} i eksemplerne for en enkelt bruger, når det er relevant. Føj hvert endpoint til endpoint-basen.

List og filtrer brugere

GET /!users accepterer filterEmail, filterPhone, filterUsername, filterUserId og filterClaimValue. Hvert filter udfører en søgning, der ikke skelner mellem store og små bogstaver, og matcher delvise værdier. Når flere filtre angives, returneres en bruger, hvis mindst ét filter matcher.

Responset indeholder en data-collection og et uigennemsigtigt paginationToken. Hent næste side ved at gentage samme request og sende den returnerede værdi som paginationToken. Fortsæt, indtil responset ikke længere indeholder en token. Tokenen må ikke fortolkes eller ændres.

Brugerresponset angiver, om et password er konfigureret, og hvornår det sidst blev ændret, men returnerer aldrig passwordet eller dets aktuelle hash.

Opret en bruger

Oprettelsesrequestet understøtter kontostatus, verificerede identifikatorer, brugerdefinerede claims, valg af password-politik, opsætning af password via e-mail eller SMS og MFA-indstillinger pr. bruger. Dette request opretter eksempelvis en bruger uden password og kræver opsætning af password 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"]
    }
  ]
}

Et oprettelsesrequest kan indeholde et password i klartekst, understøttede password-hashfelter eller ingen password-legitimationsoplysninger. Send aldrig begge password-formater. Passwords i klartekst kontrolleres mod den valgte password-politik; importerede hashes kontrolleres ikke mod politikken. Hvis der ikke angives legitimationsoplysninger, kan setPasswordEmail eller setPasswordSms bruges, når brugeren skal oprette et password under login.

Oprettelse af en bruger, der allerede findes, returnerer 409 Conflict, og tenantens plangrænse for brugere gælder. En samtidig brugeroperation kan midlertidigt blokere oprettelsen; gentag et 423 Locked-response efter kort tid.

Opdater en bruger

PUT /!user er en fuld opdatering og ikke en patch. Hent den aktuelle bruger, bevar de egenskaber, der ikke skal ændres, anvend ændringerne, og send hele den redigerbare repræsentation. Claims-collectionen samt konto- og MFA-flag erstattes af værdierne i requestet. Password-legitimationsoplysninger og authenticator-app-registreringer administreres gennem deres dedikerede operationer.

Identificer den eksisterende bruger med email, phone eller username. For at ændre en identifikator skal den aktuelle værdi bevares i feltet, og updateEmail, updatePhone eller updateUsername sættes til den nye værdi. Sæt en update-egenskab til en tom streng for at fjerne identifikatoren; udelad den for at lade identifikatoren være uændret. Sørg for, at brugeren beholder mindst én loginidentifikator.

Når disableAccount ændres fra false til true, tilbagekaldes brugerens refresh token grants og aktive sessioner. Genaktivering af kontoen tillader nye login, men gendanner ikke tilbagekaldte sessioner.

Brugerdefinerede claims på brugere kan ikke bruge beskyttede claimnavne, såsom sid og auth_time.

Administrér adgangskoder

Brug PUT /!usersetpassword til administrativ ændring eller migrering. Det understøtter tre muligheder:

• Angiv password for at anvende den valgte adgangskodepolitik og opdatere adgangskodehistorikken.
• Angiv passwordHashAlgorithm og passwordHash samt passwordHashSalt, når algoritmen kræver det, for at importere en understøttet, forudberegnet hash uden kontrol af politikken.
• Udelad begge adgangskodeformater for at fjerne brugerens aktuelle adgangskode.

De samme hashformater accepteres ved oprettelse af en bruger og ved masseprovisionering:

Eksempelvis importerer dette administrative adgangskoderequest en syntetisk bcrypt hash:

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

Medtag ikke password sammen med hashfelter. En hash eller et salt uden algoritme afvises. Fejlformaterede bcrypt strenge, ikke-understøttede varianter, cost uden for det understøttede interval og separate bcrypt salte afvises, før data gemmes. Se hashing af adgangskoder for parametre og bcrypts grænse på 72 bytes for adgangskoder.

Den valgfrie værdi passwordLastChanged er Unix-tid i sekunder. Brug changePassword for at kræve, at brugeren vælger en ny adgangskode ved næste relevante login. Import af en hash springer kontrollen af adgangskodepolitikken over under importen; den valgte politik gælder stadig ved login. Login bevarer den importerede hash og tidspunktet for seneste adgangskodeændring. Oprettelse eller ændring af en adgangskode i klartekst bruger standardformatet PBKDF2.

Brug PUT /!userchangepassword, når den aktuelle adgangskode er kendt. Det verificerer den aktuelle adgangskode og validerer den nye mod brugerens adgangskodepolitik og historik.

Endpointet til adgangskodehistorik er beregnet til kontrollerede migrerings- og gendannelsesscenarier. Det accepterer også bcrypt historikposter med samme format og costgrænser og uden separat salt. Detailresponset indeholder adgangskodehashmateriale, og PUT erstatter hele historikken. Beskyt det på samme måde som importerede adgangskodehashes, og log ikke indholdet af requests eller responses.

Masseprovisionering

PUT /!users accepterer mellem 1 og 1.000 brugere pr. request. Højst 100 entries kan indeholde passwords i klartekst, fordi hvert password skal hashes sikkert. Requests uden passwords i klartekst, herunder requests med understøttede forudberegnede hashes, kan indeholde op til 1.000 brugere.

Masseupload opretter nye brugere eller erstatter matchende brugere; den merger ikke enkelte egenskaber og kan ikke omdøbe e-mail-, telefon- eller brugernavnsidentifikatorer. Betragt operationen som en erstatningsimport. Brug operationen til opdatering af en enkelt bruger ved normale livscyklusændringer, hvor eksisterende brugertilstand og det permanente bruger-ID skal bevares.

DELETE /!users accepterer mellem 1 og 1.000 e-mailadresser, telefonnumre eller brugernavne i userIdentifiers. Se Upload mange brugere for importformater, performancevejledning og seed tool.

Slet brugere og tilbagekald adgang

Når en bruger slettes enkeltvis eller som masseoperation, tilbagekaldes brugerens refresh token grants og aktive sessioner, før kontoen slettes. Det er en permanent kontooperation. Brug authenticator-app-operationerne til sletning, hvis kun én eller alle authenticator-app-registreringer skal fjernes, mens brugeren bevares.

Requests til oprettelse, opdatering, passwords og sletning medtages i Control-auditloggen. Læseoperationer skrives ikke som audit-events.

Spærringer ved mislykket login

Brug liste- og detaljeoperationerne for loginspærringer til at undersøge spærringer, og slet en spærring, når en administrator godkender at afslutte den.

Brugerbaserede spærringer har en userIdentifier. Brug denne værdi og fejltypen til at hente eller afslutte en brugerspærring. Listefilteret filterUserIdentifier matcher identifikatorer uden at skelne mellem store og små bogstaver.

Spærringer af typen DirectorySynchronisation har et sequenceId og udelader userIdentifier. Brug det præcise sequenceId, som skelner mellem store og små bogstaver, og fejltypen til at hente eller afslutte en synkroniseringsspærring, og udelad parameteren userIdentifier. Brug filterSequenceId til at finde sekvensens spærringer. Angives både filterUserIdentifier og filterSequenceId, findes spærringer, som matcher en af værdierne; et filter på fejltype gælder stadig alle resultater. Opslagsgrænsen deles af alle identifikatorer indtastet i samme sekvens.

Authenticator-app-registreringer

Authenticator-app-operationer er samlet under tenant user authenticator apps i Swagger. En listeoperation returnerer sikre registreringsoversigter, mens detailoperationen returnerer de følsomme data, der kræves til kontrolleret synkronisering.

Føj 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}

Registreringsressource

Opret og opdater bruger hele registreringsressourcen:

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

Egenskaberne har følgende adfærd:

• userId er brugerens stabile FoxIDs-ID.
• id er et permanent registrerings-ID, som klienten angiver ved oprettelse. Det vælger registreringen ved opdatering og kan ikke ændres.
• createTime angives i Unix-sekunder. Det er valgfrit ved oprettelse og sættes som standard til det aktuelle tidspunkt. Hvis det udelades ved opdatering, bevares den eksisterende værdi.
• secret er den delte TOTP-secret og er påkrævet ved oprettelse og opdatering.
• recoveryCode indeholder recovery code-hashdata og udelades, når der ikke er konfigureret en recovery code.

En bruger kan højst have fem authenticator-app-registreringer. Oprettelse med et registrerings-ID, der allerede findes, returnerer 409 Conflict; oprettelse efter grænsen er nået returnerer 400 Bad Request.

Synkroniser registreringer

En synkroniseringsservice kan kombinere det interaktive Authenticator App notification API med disse Control API-operationer:

1. Modtag notificationen registered, som indeholder user_id og registration_id.
2. Hent registreringen fra source deployment med detailoperationen.
3. Opret registreringen i target deployment, eller opdater den, hvis samme registrerings-ID allerede findes.

Control API-operationer til oprettelse, opdatering og sletning kalder ikke Authenticator App notification API. Synkronisering af en registrering skaber derfor ikke et notification-loop.

Sikkerhed

Detail-, oprettelses- og opdateringsoperationerne udstiller eller modtager en authenticator-app-secret og recovery code-hashdata. Giv kun den nødvendige brugeradgangsrettighed til betroede klienter, brug TLS, beskyt payloads ved lagring, og log ikke request- eller response-bodies.

Brug listeoperationen, når kun registrerings-ID'er og oprettelsestidspunkter er nødvendige. Den returnerer ikke secret eller recovery code-hashdata.

Kompatibilitetsegenskab

Egenskaben activeTwoFactorApp i det generelle bruger-API er deprecated og planlagt fjernet efter 1. august 2027. I en update-request sletter false fortsat alle authenticator-app-registreringer af kompatibilitetshensyn; true eller en udeladt værdi lader registreringerne være uændrede. Nye integrationer bør bruge authenticator-app-endpoints.

Fejlresponses

Almindelige fejlresponses for bruger- og authenticator-app-operationer omfatter:

• 400 Bad Request, når identifikatorer, legitimationsoplysninger, filtre eller ressourcedata er ugyldige, eller registreringsgrænsen er nået.
• 401 Unauthorized, når access token mangler eller er ugyldig.
• 403 Forbidden, når klienten mangler den nødvendige brugeradgangsrettighed til miljøet.
• 404 Not Found, når brugeren eller den valgte authenticator-app-registrering ikke findes.
• 409 Conflict, når brugeren allerede findes, eller et registrerings-ID genbruges.
• 423 Locked, når oprettelse eller masseimport er midlertidigt låst. Prøv igen efter kort tid.

Brug response-body til valideringsdetaljer. Se Swagger UI for de responses, der er deklareret for hver operation.

Impersonerede sessioner

Aktive sessioner bevarer den oprindeligt autentificerede brugers identifikatorer. Impersoneringsoplysninger identificerer målbrugeren separat, inklusive subject, subjectformat, e-mail, telefon, brugernavn og intern kontoreference, når de findes. Du kan finde en aktiv session med begge brugeres identifikatorer.

Refresh token claims repræsenterer den identitet, der er udstedt til applikationen; grantets impersoneringsoplysninger identificerer den oprindeligt autentificerede bruger og målbrugeren. Begge tilknyttede konti indgår i tilbagekaldelse af adgang. Se impersonering for konfiguration af flow og sessionsadfærd.

Relateret dokumentation

• Control API-autentificering og adgangsrettigheder
• FoxIDs Control-oversigt
• Interne brugere
• To-faktor- og multi-faktor-autentificering
• Upload mange brugere