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 og brugernavne normaliseres til små bogstaver, og indledende og afsluttende mellemrum 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.

Brugeroperationer

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

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.

Administrer passwords

Brug PUT /!usersetpassword til administrativ password-sætning eller migrering. Den understøtter tre tilstande:

• Angiv password for at anvende den valgte password-politik og opdatere password-historikken.
• Angiv passwordHashAlgorithm, passwordHash og passwordHashSalt for at importere en understøttet, forudberegnet hash uden politikkontrol.
• Udelad begge password-formater for at fjerne brugerens aktuelle password.

Den valgfrie værdi passwordLastChanged er Unix-tid i sekunder. Brug changePassword til at kræve, at brugeren vælger et nyt password ved næste relevante login.

Brug PUT /!userchangepassword, når det aktuelle password er kendt. Operationen verificerer det aktuelle password og validerer det nye password mod brugerens password-politik og historik.

Password-historik-endpointet er beregnet til kontrollerede migrerings- og gendannelsesscenarier. Detailresponset indeholder password-hashmateriale, og PUT erstatter hele historikken. Beskyt det på samme måde som importerede password-hashes, og log ikke request- eller response-bodies.

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.

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.

Relateret dokumentation

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