Control API - användare och authenticator-appar

Använd FoxIDs Control API för att provisionera interna användare och hantera de authenticator-appar som varje användare har registrerat. Guiden fokuserar på operationer som kan användas för att synkronisera registreringar mellan FoxIDs-deployments.

Innan du anropar operationerna ska du konfigurera Control API-autentisering och åtkomsträttigheter. Swagger är fortfarande den exakta referensen för alla användaregenskaper, filter, valideringsregler och response-scheman:

• Swagger (OpenAPI) JSON
• Swagger UI

Endpoint-bas

Exemplen använder FoxIDs Cloud:

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

Ersätt {tenant_name} med tenantnamnet och {track_name} med miljöns tekniska namn. Byt host för ett self-hosted deployment. Skicka Control API-access token i headern Authorization: Bearer {access_token}.

Användar- och authenticator-appoperationer kräver en användaråtkomsträttighet för den valda miljön. Tilldela endast den nödvändiga operationen read, create, update eller delete genom Control API-hierarkin för åtkomsträttigheter.

Användaridentifierare

Varje intern användare måste ha minst en av följande inloggningsidentifierare: e-postadress, telefonnummer eller användarnamn. E-postadresser och användarnamn normaliseras till gemener, och inledande och avslutande blanksteg tas bort från alla identifierare.

Operationerna för en enskild användare identifierar användaren med query-parametern email, phone eller username. Användarresponset innehåller också ett servergenererat userId. Detta ID är unikt och beständigt även när en inloggningsidentifierare ändras och bör användas när authenticator-appar eller andra resurser kopplas till användaren.

Användaroperationer

Operationer för enskilda användare grupperas under tenant users i Swagger.

Använd phone={phone} eller username={username} i stället för email={email} i exemplen för en enskild användare när det passar. Lägg varje endpoint efter endpoint-basen.

Lista och filtrera användare

GET /!users accepterar filterEmail, filterPhone, filterUsername, filterUserId och filterClaimValue. Varje filter gör en sökning som inte skiljer mellan stora och små bokstäver och matchar delsträngar. När flera filter anges returneras en användare om något filter matchar.

Responset innehåller en data-collection och ett ogenomskinligt paginationToken. Hämta nästa sida genom att upprepa samma request och skicka det returnerade värdet som paginationToken. Fortsätt tills responset inte längre innehåller en token. Tolka eller ändra inte tokenen.

Användarresponset anger om ett lösenord är konfigurerat och när det senast ändrades, men returnerar aldrig lösenordet eller dess aktuella hash.

Skapa en användare

Requestet för att skapa stöder kontostatus, verifierade identifierare, anpassade claims, val av lösenordspolicy, lösenordsinställning via e-post eller SMS och MFA-inställningar per användare. Följande request skapar till exempel en användare utan lösenord och kräver lösenordsinställning 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"]
    }
  ]
}

Ett create-request kan innehålla ett lösenord i klartext, stödda lösenordshashfält eller inga lösenordsuppgifter. Skicka aldrig båda lösenordsformaten. Lösenord i klartext kontrolleras mot den valda lösenordspolicyn; importerade hashar policykontrolleras inte. Om inga uppgifter anges kan setPasswordEmail eller setPasswordSms användas när användaren ska skapa ett lösenord under inloggning.

Om en användare redan finns returneras 409 Conflict, och tenantens plangräns för användare gäller. En samtidig användaroperation kan tillfälligt blockera skapandet; försök igen efter en kort stund vid 423 Locked.

Uppdatera en användare

PUT /!user är en fullständig uppdatering, inte en patch. Läs den aktuella användaren, bevara egenskaper som inte ska ändras, tillämpa ändringarna och skicka hela den redigerbara representationen. Claims-collectionen samt konto- och MFA-flaggorna ersätts av värdena i requestet. Lösenordsuppgifter och authenticator-appregistreringar hanteras genom sina särskilda operationer.

Identifiera den befintliga användaren med email, phone eller username. För att ändra en identifierare behåller du dess aktuella värde i fältet och anger det nya värdet i updateEmail, updatePhone eller updateUsername. Ange en tom sträng för en update-egenskap för att ta bort identifieraren; utelämna den för att lämna identifieraren oförändrad. Se till att användaren behåller minst en inloggningsidentifierare.

När disableAccount ändras från false till true återkallas användarens refresh token grants och aktiva sessioner. Återaktivering av kontot tillåter nya inloggningar men återställer inte återkallade sessioner.

Hantera lösenord

Använd PUT /!usersetpassword för administrativ lösenordssättning eller migrering. Den stöder tre lägen:

• Ange password för att tillämpa vald lösenordspolicy och uppdatera lösenordshistoriken.
• Ange passwordHashAlgorithm, passwordHash och passwordHashSalt för att importera en stödd förberäknad hash utan policyvalidering.
• Utelämna båda lösenordsformaten för att ta bort användarens aktuella lösenord.

Det valfria värdet passwordLastChanged är Unix-tid i sekunder. Använd changePassword för att kräva att användaren väljer ett nytt lösenord vid nästa tillämpliga inloggning.

Använd PUT /!userchangepassword när det aktuella lösenordet är känt. Operationen verifierar det aktuella lösenordet och validerar det nya mot användarens lösenordspolicy och historik.

Endpointen för lösenordshistorik är avsedd för kontrollerade migrerings- och återställningsscenarier. Detaljresponset innehåller lösenordshashmaterial och PUT ersätter hela historiken. Skydda det på samma sätt som importerade lösenordshashar och logga inte request- eller response-bodies.

Bulkprovisionering

PUT /!users accepterar mellan 1 och 1 000 användare per request. Högst 100 poster kan innehålla lösenord i klartext eftersom varje lösenord måste hashas säkert. Requests utan lösenord i klartext, inklusive requests med stödda förberäknade hashar, kan innehålla upp till 1 000 användare.

Bulkuppladdning skapar nya användare eller ersätter matchande användare; den slår inte samman enskilda egenskaper och kan inte byta namn på identifierare för e-post, telefon eller användarnamn. Behandla den som en ersättningsimport. Använd uppdateringen för en enskild användare vid normala livscykeländringar där befintligt användartillstånd och det beständiga användar-ID:t måste bevaras.

DELETE /!users accepterar mellan 1 och 1 000 e-postadresser, telefonnummer eller användarnamn i userIdentifiers. Se Ladda upp många användare för importformat, prestandavägledning och seed tool.

Ta bort användare och återkalla åtkomst

När en användare tas bort, enskilt eller i bulk, återkallas användarens refresh token grants och aktiva sessioner innan kontot tas bort. Det är en permanent kontooperation. Använd authenticator-appens delete-operationer när endast en eller alla registreringar ska tas bort och användaren ska behållas.

Requests för skapande, uppdatering, lösenord och borttagning ingår i Controls auditlogg. Läsoperationer skrivs inte som audit-events.

Authenticator-appregistreringar

Authenticator-appoperationer grupperas under tenant user authenticator apps i Swagger. En listoperation returnerar säkra registreringsöversikter medan detaljoperationen returnerar känsliga data som krävs för kontrollerad synkronisering.

Lägg till varje endpoint till endpoint-basen. Exempel:

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

Registreringsresurs

Skapa och uppdatera använder hela registreringsresursen:

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

Egenskaperna har följande beteende:

• userId är användarens stabila FoxIDs-ID.
• id är ett beständigt registrerings-ID som klienten anger vid skapande. Det väljer registreringen vid uppdatering och kan inte ändras.
• createTime anges i Unix-sekunder. Det är valfritt vid skapande och får aktuell tid som standard. Om det utelämnas vid uppdatering behålls det befintliga värdet.
• secret är den delade TOTP-secreten och krävs vid skapande och uppdatering.
• recoveryCode innehåller recovery code-hashdata och utelämnas när ingen recovery code är konfigurerad.

En användare kan ha högst fem authenticator-appregistreringar. Skapande med ett registrerings-ID som redan finns returnerar 409 Conflict; skapande efter att gränsen har nåtts returnerar 400 Bad Request.

Synkronisera registreringar

En synkroniseringstjänst kan kombinera det interaktiva Authenticator App notification API med dessa Control API-operationer:

1. Ta emot notificationen registered som innehåller user_id och registration_id.
2. Hämta registreringen från source deployment med detaljoperationen.
3. Skapa registreringen i target deployment eller uppdatera den om samma registrerings-ID redan finns.

Control API-operationer för skapande, uppdatering och borttagning anropar inte Authenticator App notification API. Synkronisering skapar därför ingen notification-loop.

Säkerhet

Detalj-, skapa- och uppdateringsoperationerna exponerar eller tar emot en authenticator-appsecret och recovery code-hashdata. Ge den nödvändiga användaråtkomsträtten endast till betrodda klienter, använd TLS, skydda payloads vid lagring och logga inte request- eller response-bodies.

Använd listoperationen när endast registrerings-ID:n och skapandetider behövs. Den returnerar inte secret eller recovery code-hashdata.

Kompatibilitetsegenskap

Egenskapen activeTwoFactorApp i det allmänna användar-API:t är deprecated och planeras att tas bort efter 1 augusti 2027. I en update-request tar false fortfarande bort alla authenticator-appregistreringar av kompatibilitetsskäl; true eller ett utelämnat värde lämnar registreringarna oförändrade. Nya integrationer bör använda authenticator-appendpoints.

Felresponses

Vanliga felresponses för användar- och authenticator-appoperationer är:

• 400 Bad Request när identifierare, uppgifter, filter eller resursdata är ogiltiga, eller registreringsgränsen har nåtts.
• 401 Unauthorized när access token saknas eller är ogiltig.
• 403 Forbidden när klienten saknar nödvändig användaråtkomsträttighet för miljön.
• 404 Not Found när användaren eller vald authenticator-appregistrering inte finns.
• 409 Conflict när användaren redan finns eller ett registrerings-ID återanvänds.
• 423 Locked när skapande eller bulkimport är tillfälligt låst. Försök igen efter en kort stund.

Använd response-body för valideringsdetaljer. Se Swagger UI för de responses som deklareras för varje operation.

Relaterad dokumentation

• Control API-autentisering och åtkomsträttigheter
• Översikt över FoxIDs Control
• Interna användare
• Tvåfaktors- och multifaktorautentisering
• Ladda upp många användare