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 kan vara upp till 100 tecken långa och användarnamn upp till 60 tecken långa. E-postadresser och användarnamn normaliseras till gemener, och omgivande 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.

För användare med Directory Connector ska den stabila kopplingen via directoryUserId behållas vid kontouppdatering. Synkronisering vid behov ersätter katalogens identifierare, kontoinställningar och claims; ändra dessa värden i den auktoritativa katalogen. Registrerade autentiseringsappar och åtkomsttilldelningar i FoxIDs behålls.

Användaroperationer

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

Anpassade claims kan ha en valfri valueType: String, Boolean, Number, JsonObject eller JsonArray. Alla poster i values förblir strängar och delar den valda typen. Utelämna valueType för String. API:et avvisar värden som inte matchar den valda typen; bevara typen när claims läses och uppdateras. Samma val gäller för claims på åtkomststrukturnoder och claims för den första administratören när en tenant skapas. Se typer för claimvärden för talgränser och beteende i JWT/SAML.

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.

Anpassade användarclaims kan inte använda skyddade claimnamn, som sid och auth_time.

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 och passwordHash, samt passwordHashSalt när algoritmen kräver det, för att importera en förberäknad hash som stöds utan policyvalidering.
• Utelämna båda lösenordsformaten för att ta bort användarens aktuella lösenord.

Samma hashformat accepteras vid skapande av en användare eller massetablering:

Detta administrativa lösenordsanrop importerar exempelvis en syntetisk bcrypt hash:

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

Ta inte med password tillsammans med hashfält. En hash eller ett salt utan tillhörande algoritm avvisas. Felaktigt formaterade bcrypt strängar, varianter som inte stöds, kostnader utanför intervallet och separata bcrypt salter avvisas före lagring. Se lösenordshashning för parametrar och bcrypt gränsen på 72 byte för 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. Import av en hash hoppar över lösenordspolicykontroller under importen; vald policy gäller fortfarande vid inloggning. Inloggning bevarar den importerade hashen och tidpunkten för lösenordsändring. När ett lösenord i klartext anges eller ändras används standardformatet PBKDF2.

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. Den accepterar även historikposter med bcrypt med samma format- och kostnadsgränser och utan separat salt. Detaljsvaret innehåller lösenordshashmaterial och PUT ersätter hela historiken. Hantera den med samma skyddsåtgärder som importerade lösenordshashar och logga inte anrops- eller svarsinnehåll.

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.

Spärrar vid misslyckad inloggning

Använd list- och detaljoperationerna för inloggningsspärrar för att granska spärrar, och radera en spärr när en administratör godkänner att den avslutas.

Användarbaserade spärrar har en userIdentifier. Använd detta värde och feltypen för att hämta eller avsluta en användarspärr. Listfiltret filterUserIdentifier matchar identifierare utan att skilja på stora och små bokstäver.

Spärrar av typen DirectorySynchronisation har ett sequenceId och utelämnar userIdentifier. Använd exakt, skiftlägeskänsligt sequenceId och feltyp för att hämta eller avsluta en synkroniseringsspärr och utelämna parametern userIdentifier. Använd filterSequenceId för att hitta sekvensens spärrar. Både filterUserIdentifier och filterSequenceId hittar spärrar som matchar något av värdena; ett feltypsfilter gäller fortfarande alla resultat. Uppslagsgränsen delas av alla identifierare som anges i samma sekvens.

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.

Impersonerade sessioner

Aktiva sessioner behåller den ursprungligen autentiserade användarens identifierare. Impersoneringsuppgifter identifierar målanvändaren separat, inklusive subject, subjectformat, e-post, telefon, användarnamn och intern kontoreferens när dessa finns. Du kan hitta en aktiv session med båda användarnas identifierare.

Refresh token claims representerar identiteten som utfärdats till applikationen; grantens impersoneringsuppgifter identifierar den ursprungligen autentiserade användaren och den valda målanvändaren. Båda kopplade kontona omfattas av åtkomståterkallelse. Se impersonering för flödeskonfiguration och sessionsbeteende.

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