Directory Connector

Directory Connector gör att FoxIDs kan använda en extern katalog som auktoritativ källa för interna användares lösenord och utvalda användardata.

Användarna finns fortfarande som interna användare i FoxIDs-miljön. Under lösenordsautentisering och operationer i lösenordets livscykel anropar FoxIDs Directory Connector API:et i stället för att bara validera lösenordet mot den interna FoxIDs-användaren.

Eftersom FoxIDs behåller en intern användarpost kan FoxIDs hantering av multi-factor authentication (MFA) läggas till för användare från det externa repositoriet. Connectorn kan returnera MFA-relaterade användarinställningar, till exempel requireMultiFactor och inaktiverade two-factor-metoder, och FoxIDs tillämpar inställningarna på den interna användaren medan det externa repositoriet förblir auktoritativt för lösenord och utvalda användardata.

För Active Directory innehåller FoxIDs en IIS-distribuerbar Directory Connector för Active Directory-komponent.

Använd Directory Connector när:

  • du vill att användare ska logga in med den vanliga login-autentiseringsmetoden.
  • du vill aktivera användare från en befintlig katalog för OpenID Connect- och SAML 2.0-applikationer via FoxIDs.
  • din externa katalog är auktoritativ för lösenordsvalidering och lösenordsändringar.
  • du vill att FoxIDs ska behålla en intern användarpost med identifierare, egenskaper, claims, multi-factor authentication (MFA)-inställningar, åtkomsttilldelningar och eventuellt en lokal kopia av lösenordet.
  • du vill ha en väg att senare byta till interna användare och lösenordsvalidering i FoxIDs utan att tvinga alla användare att återställa sina lösenord.

Det finns en Directory Connector per miljö. När den är aktiverad gäller den på miljönivå.

Så fungerar det

FoxIDs synkroniserar vid behov när en användare anger en identifierare i ett inloggnings- eller återställningsflöde. FoxIDs anropar synchronise-user innan kontot kontrolleras, skapar vid behov en FoxIDs användare och uppdaterar identifierare, egenskaper och claims som katalogen ansvarar för.

Synkronisering ingår när Directory Connector aktiveras. FoxIDs synkroniserar när inloggning, återställning och kontokontroll av befintliga sessioner inleds samt när en refresh token används för ett katalogbundet konto. Fortsättningar med bekräftelsekoder, MFA och Extended UI använder det valda kontot och de vanliga FoxIDs kontrollerna. Om synkroniseringen misslyckas stoppas flödet.

Svaret måste innehålla ett stabilt, unikt directoryUserId. Använd katalogens permanenta konto-ID i stället för e-post, telefonnummer eller användarnamn. FoxIDs använder kopplingen för att hitta samma konto när identifierare ändras. Registrerade autentiseringsappar och åtkomsttilldelningar i FoxIDs behålls.

När användaren anger en identifierare skickar FoxIDs endast den e-postadressen, det telefonnumret eller det användarnamnet. Vid sessionsåteranvändning och refresh-token-anrop läser FoxIDs in den anslutna användaren och synkroniserar med katalog-ID:t som lagrats på användaren. Även lösenordsoperationer använder katalog-ID:t på den inlästa användaren. Det lagras inte separat i inloggningssekvensen.

Connectorn returnerar en fullständig bild av aktuella användardata. FoxIDs ersätter katalogens identifierare, egenskaper och claims, inklusive kontots inaktiveringsstatus, krav på lösenordsbyte och inställningar för första lösenordsregistrering. Samma konto-, återställnings- och MFA-kontroller som för interna användare används. Interna användare utan katalogkoppling synkroniseras eller kopplas inte automatiskt.

Ett synkroniseringssvar med disableAccount: true inaktiverar användaren i FoxIDs och återkallar aktiva sessioner och refresh-token grants. Om connectorn returnerar felkoden user_deleted vid synkronisering med användarens katalog-ID raderar FoxIDs den interna användaren och återkallar aktiva sessioner och refresh tokens. Om en sökning med enbart identifierare inte hittar något konto kontrollerar FoxIDs eventuell befintlig katalogkoppling innan flödet fortsätter, så att inaktuella lokala kontodata inte kan tillåta inloggning eller återställning. Felkoden user_not_exists raderar inte i sig ett konto.

Refresh-token-anrop kontrollerar både det ursprungliga kontot och ett impersonerat lokalt konto när de är katalogbundna. Om synkroniseringen hittar ett inaktiverat eller raderat konto återkallar FoxIDs aktiva sessioner och refresh-token grants och nekar den aktuella tokenförnyelsen. Den vanliga kontrollen av aktiva sessioner validerar sessionstillståndet i FoxIDs; den kontaktar inte katalogen. En applikation som validerar en utfärdad access token lokalt följer tokenens utgångstid i stället för återkallelsen av sessionen i FoxIDs.

Ändringar blir tillgängliga vid nästa kontokontroll på begäran. Det finns ingen synkroniseringsprocess i bakgrunden.

Directory Connector kan användas som en permanent integration, där användare och lösenord hanteras i den externa katalogen, eller för att gradvis migrera användare till FoxIDs. Vid migrering ska connectorn vara aktiverad medan användare etableras. Aktivera lokal lösenordskopia för att spara lösenord efter lyckad autentisering, ändring eller återställning genom FoxIDs.

När migreringen är klar inaktiveras Directory Connector och användare och lösenord hanteras direkt i FoxIDs. Skapa först användare som ännu inte etablerats och ordna lösenordsregistrering eller återställning för användare utan en aktuell lokal lösenordskopia. Kopian återspeglar den senaste lyckade lösenordsautentiseringen, ändringen eller återställningen genom FoxIDs; senare lösenordsändringar enbart i den externa katalogen ingår inte.

Skydd för uppslagningar

När en användare anger e-post, telefonnummer eller användarnamn i gränssnittet för inloggning eller återställning räknas kataloguppslagningen mot en gemensam gräns för alla identifierare i den aktuella inloggningssekvensen. Gränsen använder miljöns inställningar för Failed login attempt limit, räknarens livslängd och observationsperiod. Både lyckade uppslagningar och misslyckade connectoranrop räknas; lyckad lösenordsautentisering återställer inte räknaren. När gränsen nås måste observationsperioden inväntas eller en ny inloggningssekvens startas. Synkronisering vid sessionsåteranvändning och refresh-token-anrop använder inte denna räknare. Skyddet för lösenord och bekräftelsekoder använder fortsatt sina separata befintliga räknare.

Inloggningsidentifierare och katalogkoppling

Användare kan logga in med sin aktuella e-postadress, sitt telefonnummer eller sitt användarnamn enligt de identifierartyper som är aktiverade på inloggningsmetoden. Före lösenordsautentisering måste den angivna identifieraren matcha en aktuell identifierare som connectorn returnerar. FoxIDs tar bort omgivande blanktecken. Jämförelser av e-post och användarnamn är skiftlägesokänsliga. Telefonnummer använder det obligatoriska internationella formatet.

Inloggning efter ändrade identifierare

När användare anger en identifierare synkroniserar FoxIDs deras e-post, telefonnummer och användarnamn från katalogen. Det stabila katalog-ID:t kopplar dem till samma FoxIDs konto även om en eller alla identifierare ändras. Registrerade autentiseringsappar och åtkomsttilldelningar behålls, och befintliga åtkomstbegränsningar och MFA-krav gäller fortsatt.

Situation Vad händer under synkronisering?
Användaren loggar in med ett oförändrat användarnamn medan e-post eller telefonnummer har ändrats i katalogen. FoxIDs uppdaterar samma konto med de aktuella identifierarna från connectorn.
Användaren loggar in med en ny identifierare som FoxIDs ännu inte känner till. Om katalogen returnerar den nya identifieraren och samma stabila katalog-ID fortsätter användaren med sitt befintliga FoxIDs konto. Detta fungerar även när alla identifierare har ändrats.
Användaren loggar in med en gammal identifierare som connectorn inte längre returnerar. Inloggningen nekas med det vanliga inloggningsfelet, även om användaren fortfarande känner till lösenordet. Användaren måste ange en aktuell identifierare av en aktiverad typ.
Connectorn slutar returnera e-post, telefonnummer eller användarnamn. Identifieraren tas bort från FoxIDs kontot under synkroniseringen. Connectorn måste returnera minst en aktuell identifierare.

En användare vars e-post ändras från old@example.org till new@example.org kan exempelvis logga in med new@example.org innan FoxIDs känner till adressen. Connectorn måste returnera new@example.org och användarens oförändrade katalog-ID. Användaren behåller samma konto och registrerade autentiseringsappar. Alternativt kan ett oförändrat användarnamn användas om inloggning med användarnamn är aktiverad.

Connectorn måste returnera samtliga aktuella identifierare som FoxIDs ska behålla. Utelämnade eller tomma värden behandlas som borttagna identifierare, och tidigare värden sparas inte som inloggningsalias. Endast identifierartyper som är aktiverade på inloggningsmetoden kan användas för inloggning.

Kontokonflikter

Varje kataloganvändare måste ha ett stabilt, unikt katalog-ID och identifierare som inte tillhör ett annat FoxIDs konto. FoxIDs slår först upp den angivna identifieraren i katalogen och använder sedan returnerat katalog-ID för att hitta eller skapa det lokala kontot. Om identifierarna vid lagring kolliderar med ett annat konto stoppas flödet. En administratör måste rätta katalog- eller kontokonfigurationen; konton sammanfogas eller omfördelas inte automatiskt.

En befintlig intern användare utan katalogkoppling kan inte logga in genom Directory Connector. Aktivering kopplar inte automatiskt ett befintligt konto till en kataloganvändare enbart för att e-post, telefonnummer eller användarnamn matchar.

Lokal lösenordskopia

Den externa katalogen är auktoritativ så länge Directory Connector är aktiverad. FoxIDs faller inte tillbaka till den lokala lösenordshashen om Directory Connector API:et tillfälligt inte är tillgängligt.

Som standard sparar FoxIDs en lokal kopia av lösenordet på den interna användaren efter en lyckad lösenordsvalidering eller en operation i lösenordets livscykel via connectorn. Detta kan stängas av i miljöinställningarna.

Den lokala lösenordskopian används inte medan Directory Connector är aktiverad. Den finns för att stödja ett senare byte till interna användare och lösenordsvalidering i FoxIDs utan att tvinga alla användare att återställa sina lösenord.

Lösenordets livscykel

Användarskapande och åtgärder i lösenordets livscykel delegeras till API:et för Directory Connector:

  • Lösenordsautentisering anropar endpointen authentication.
  • Flödet för att skapa användare vid inloggning anropar endpointen create-user.
  • Ändring av användarens lösenord anropar endpointen change-password.
  • Flöden för att sätta lösenord och återställa lösenord anropar endpointen set-password.

Lösenordsendpoints tar emot stabilt directoryUserId från den inlästa användaren. Katalogen kontrollerar aktuellt kontotillstånd och autentiseringsuppgifter under operationen. Autentisering, lösenordsbyte och återställning returnerar framgång eller ett fel. Användarskapande returnerar det skapade kontots katalog-ID, som FoxIDs använder för separat synkronisering.

Lösenordsoperationer använder katalog-ID:t på den inlästa FoxIDs användaren. Connectorn kontrollerar kontotillstånd och de autentiseringsuppgifter eller den återställningsbehörighet som operationen kräver, utför åtgärden och returnerar framgång eller fel. Identifierare, attribut och claims returneras endast genom synkronisering.

Efter lyckat lösenordsbyte eller återställning sparar FoxIDs den aktuella tidpunkten och tar bort kraven på att ändra eller ange lösenord. En lokal lösenordskopia sparas också om detta är konfigurerat. Den aktiva sekvensen fortsätter med normal konto-, återställnings- och MFA-hantering i FoxIDs.

Om en åtgärd misslyckas eller FoxIDs inte kan spara kända lösenordsändringar stoppas flödet. En lösenordsändring som katalogen redan godkänt återställs inte, och FoxIDs upprepar inte automatiskt åtgärden efter timeout eller ett misslyckat svar. Nästa synkronisering uppdaterar det lokala kontot.

När Enable password policy är aktiverat verifierar FoxIDs det aktuella kataloglösenordet innan kontrollerna av det nya lösenordet utförs. Det kan kräva ett extra autentiseringsanrop före change-password.

FoxIDs uppdaterar inte sin interna lösenordshistorik när Directory Connector används, eftersom FoxIDs inte nödvändigtvis känner till alla lösenordsändringar i den externa katalogen.

Registrering och återställning av lösenord

Vid första inloggningen kan en kataloganvändare ange ett lösenord med en bekräftelsekod via e-post eller SMS, antingen för att lösenordet glömts eller för att ett nytt måste väljas.

För att använda Forgot your password? anges en aktuell katalogidentifierare av en typ som är aktiverad på inloggningsmetoden. FoxIDs synkroniserar och etablerar kontot innan bekräftelsekoden skickas. Återställning via e-post eller SMS måste vara aktiverad och användaren måste ha åtkomst till den aktuella återställningskontakt som katalogen returnerar.

När användaren verifierat koden och skickat ett nytt lösenord anropar FoxIDs set-password med stabilt katalog-ID. Returnera setPasswordEmail eller setPasswordSms och motsvarande kontaktidentifierare för att kräva lösenordsregistrering genom flödet. FoxIDs använder sitt vanliga flöde för lösenordsregistrering.

Bekräftelsekoder är bundna till det konto de utfärdades för. Konton som hanteras genom en katalogconnector använder samma kodverifiering som andra interna användare. FoxIDs behåller den vanliga felhanteringen vid återställning utan att visa connectordiagnostik.

Lösenordspolicy och felmeddelanden

Den externa katalogen upprätthåller lösenordspolicyn. FoxIDs använder miljöns lösenordspolicy när felmeddelanden om lösenordspolicy som returneras från connectorn visas.

Konfigurera miljöns lösenordspolicy så att den matchar lösenordspolicyn i den externa katalogen. Om de inte matchar kan användarna se lösenordshjälp som inte speglar de faktiska kraven i den externa katalogen.

Om den externa katalogen till exempel avvisar ett lösenord eftersom det är för kort använder FoxIDs miljöns minsta lösenordslängd när felmeddelandet visas.

Implementera API

Du implementerar ett Directory Connector API och konfigurerar FoxIDs med dess bas-URL och secret.

API:t har en bas-URL och fem endpoints:

  • synchronise-user slår upp en användare och returnerar aktuellt kontotillstånd, identifierare och claims.
  • authentication validerar en användares nuvarande lösenord.
  • create-user skapar en användare i den externa katalogen och returnerar dess permanenta katalog-ID.
  • change-password validerar det nuvarande lösenordet och ändrar det till ett nytt lösenord.
  • set-password sätter ett nytt lösenord utan att validera det nuvarande lösenordet.

Om bas-URL:en är https://somewhere.org/directory är endpointsen:

  • https://somewhere.org/directory/synchronise-user
  • https://somewhere.org/directory/authentication
  • https://somewhere.org/directory/create-user
  • https://somewhere.org/directory/change-password
  • https://somewhere.org/directory/set-password

FoxIDs Cloud anropar ditt API från IP 57.128.60.142. IP-adresser kan ändras eller utökas.

Säkerhet

Begäranden skyddas med HTTP Basic authentication:

  • Användarnamn: directory_connector
  • Lösenord: det konfigurerade API-secretet

Anropet är HTTP POST med en JSON-body.

FoxIDs skickar valt språk i request-headern Accept-Language, exempelvis Accept-Language: da-DK. Vid inloggning följer detta språket från ui_locales eller webbläsaren, med engelska som reservspråk i FoxIDs. API:t kan använda headern för att lokalisera användarmeddelanden och måste välja ett eget reservspråk när önskat språk inte stöds. Headern skickas till alla fem endpoints.

Synkroniseringsanrop

Endpointen synchronise-user tar emot antingen en användaridentifierare eller ett känt katalog-ID. Första uppslagningen vid inloggning eller återställning använder angiven identifierare. FoxIDs använder lagrat directoryUserId för befintliga sessionskontroller och refresh-token-anrop samt returnerat katalog-ID efter create-user.

En inledande uppslagning med e-post:

{
  "email": "user1@somewhere.org"
}

En efterföljande kontokontroll:

{
  "directoryUserId": "a1b2c3d4"
}

Använd directoryUserId som auktoritativ uppslagsnyckel när det anges. Slå annars upp exakt en av email, phone eller username. Returnera HTTP 200 med fullständiga användardata, även för inaktiverade konton. Returnera felkoden user_deleted när känt ID saknas och user_not_exists när en uppslagning med enbart identifierare inte hittar ett konto. Godta aldrig en angiven identifierare som bevis på kontoägarskap.

FoxIDs väljer identifieraren i anropet utifrån aktiverade inloggningsidentifierare. Om endast användarnamn är aktiverat skickas indata i e-postformat som username. Omgivande blanktecken tas bort. Indata måste matcha en aktuell svarsidentifierare av en aktiverad typ; det antagna request-fältet begränsar inte vilket svarsfält som kan matcha.

För fel, se Felsvar.

Svar vid framgång

Endpointen synchronise-user returnerar HTTP 200 med fullständiga aktuella användardata. Om anropet anger katalog-ID måste svaret innehålla samma ID. FoxIDs verifierar detta innan data sparas. HTTP 204 eller ofullständiga användardata avvisas.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "phone": "+4511223344",
  "username": "user1",
  "confirmAccount": true,
  "disableAccount": false,
  "changePassword": false,
  "setPasswordEmail": false,
  "setPasswordSms": false,
  "disableSetPasswordEmail": false,
  "disableSetPasswordSms": false,
  "passwordLastChanged": 1760000000,
  "emailVerified": true,
  "phoneVerified": true,
  "disableTwoFactorApp": false,
  "disableTwoFactorSms": false,
  "disableTwoFactorEmail": false,
  "requireMultiFactor": false,
  "claims": [
    { "type": "name", "value": "User One" },
    { "type": "role", "value": "employee" }
  ]
}

FoxIDs använder svaret för att skapa eller uppdatera den interna användaren i miljön.

Fält:

  • directoryUserId är obligatoriskt. Det måste vara stabilt och unikt i den externa katalogen och lagras på den interna FoxIDs-användaren.
  • email, phone och username är valfria var för sig, men minst ett måste finnas. FoxIDs sparar de returnerade värdena som identifierare för den interna användaren. Returnerade användaridentifierarvärden måste entydigt identifiera en användare i den externa katalog som connectorn använder.
  • phone måste innehålla landskod i internationellt format, till exempel +4511223344.
  • confirmAccount styr om FoxIDs ska köra ett bekräftelseflöde för att bekräfta den interna användaren.
  • disableAccount styr kontots direkta inaktiveringsstatus. Övergång till inaktiverat återkallar användarens FoxIDs sessioner och refresh-token grants.
  • changePassword kräver lösenordsbyte efter lyckad verifiering av autentiseringsuppgifterna.
  • setPasswordEmail och setPasswordSms kräver lösenordsregistrering genom motsvarande bekräftelsekodsflöde. Kontaktidentifieraren måste finnas och återställningsmetoden vara aktiverad.
  • disableSetPasswordEmail och disableSetPasswordSms inaktiverar motsvarande återställningsmetoder.
  • passwordLastChanged är en valfri icke-negativ Unix-tidsstämpel i sekunder. När den anges vid synkronisering uppdateras lösenordsåldern i FoxIDs. Om den utelämnas behålls befintlig tidsstämpel. Lyckat lösenordsbyte eller återställning sparar aktuell tid i FoxIDs; senare synkronisering kan ange katalogens auktoritativa tidsstämpel.
  • emailVerified styr om den interna användarens e-post markeras som verifierad.
  • phoneVerified styr om den interna användarens telefonnummer markeras som verifierat.
  • disableTwoFactorApp inaktiverar tvåfaktorsautentisering med authenticator-app för den interna användaren.
  • disableTwoFactorSms inaktiverar SMS-baserad tvåfaktorsautentisering för den interna användaren.
  • disableTwoFactorEmail inaktiverar e-postbaserad tvåfaktorsautentisering för den interna användaren.
  • requireMultiFactor styr om den interna användaren måste använda multifaktorautentisering.
  • claims är valfritt. FoxIDs sparar de returnerade claims på den interna användaren.

Claims stöder en valfri valueType: String, Boolean, Number, JsonObject eller JsonArray. Fältet value förblir text; utelämna valueType för String. FoxIDs bevarar den valda typen och loggar en varning innan ett ogiltigt värde återgår till text. Se typer för claimvärden för exempel och talgränser. Samma representation används för claims som skickas i begäranden om att skapa användare och returneras i synkroniseringssvar.

FoxIDs ignorerar claims där type eller value saknas, är null, är tomt eller bara innehåller blanktecken. När trace-loggning av meddelanden är aktiverad visar svarets trace mottagna claims innan de filtreras. Långa trace-meddelanden kortas ned.

Skyddade claims, exempelvis sid och auth_time, tas också bort från synkroniseringssvar.

Authentication-begäran

Endpointen authentication tar emot obligatoriskt stabilt katalog-ID och aktuellt lösenord.

{
  "directoryUserId": "a1b2c3d4",
  "password": "testpass1"
}

Kontrollera aktuellt katalogkontotillstånd och lösenord innan framgång returneras. Verifiera lösenordet innan kontospecifik vägledning om lösenordspolicy returneras.

För fel, se Felsvar.

Svar vid framgång

Vid framgång returneras HTTP 204 utan svarsinnehåll.

Begäran om att skapa användare

Endpointen create-user tar emot exakt en användaridentifierare, ett obligatoriskt lösenord, valda create-user-egenskaper och claims som samlats in under FoxIDs create-user-flödet.

{
  "email": "user1@somewhere.org",
  "password": "testpass1",
  "confirmAccount": true,
  "requireMultiFactor": false,
  "claims": [
    { "type": "given_name", "value": "User" },
    { "type": "family_name", "value": "One" }
  ]
}

Fält:

  • Exakt en av email, phone eller username skickas.
  • password är obligatoriskt. Skapa användare utan lösenord stöds inte med Directory Connector, eftersom Directory Connector API:t autentiserar användare med lösenord.
  • confirmAccount och requireMultiFactor är de begärda inställningarna för att skapa användaren i FoxIDs.
  • claims innehåller de claims som inte är identifierare och som samlas in när användaren skapas i FoxIDs.

För fel, se Felsvar.

Svar vid framgång

Vid framgång returneras HTTP 200 med det skapade kontots permanenta katalog-ID:

{
  "directoryUserId": "a1b2c3d4"
}

FoxIDs anropar sedan synchronise-user med detta ID för att hämta hela kontot och skapa den interna FoxIDs användaren.

Change-password-begäran

Endpointen change-password tar emot obligatoriskt katalog-ID, aktuellt och nytt lösenord. Verifiera aktuellt lösenord innan kontospecifik policyvägledning returneras.

{
  "directoryUserId": "a1b2c3d4",
  "currentPassword": "oldpass1",
  "newPassword": "newpass1"
}

För fel, se Felsvar.

Svar vid framgång

Vid framgång returneras HTTP 204 utan svarsinnehåll. Lösenordsbytet måste uppfylla katalogens lösenordskrav.

Set-password-begäran

Endpointen set-password tar emot obligatoriskt katalog-ID och nytt lösenord. FoxIDs anropar den efter godkänd återställning eller registrering, inklusive kodverifiering i återställningsflöden. Connectorn måste kontrollera aktuellt kontotillstånd igen innan lösenordet ändras.

{
  "directoryUserId": "a1b2c3d4",
  "password": "newpass1"
}

För fel, se Felsvar.

Svar vid framgång

Vid framgång returneras HTTP 204 utan svarsinnehåll. Återställningen eller registreringen måste uppfylla katalogens lösenordskrav.

Felsvar

Alla endpoints använder samma JSON-felformat. Returnera en felkod som endpointen stöder i error och diagnostiska detaljer i errorMessage. Exempelvis ett avvisat lösenord från authentication:

{
  "error": "invalid_password",
  "errorMessage": "Invalid password."
}

Använd dessa HTTP-statuskoder:

  • 401 med felkoden invalid_api_id_secret när HTTP Basic-autentisering avvisas.
  • 400, 401 eller 403 för andra felkoder som stöds enligt endpointtabellen nedan.
  • 500 vid tekniska fel i connectorn.

Fältet errorMessage är diagnostisk text för loggarna i FoxIDs och visas inte för slutanvändaren. Ange orsaken till felet, men inkludera aldrig lösenord, API-hemligheter eller privata nycklar.

Endast endpointen authentication kan returnera felkoden login_rejected, efter verifiering av användarens identifierare och lösenord. Den kan innehålla valfri uiErrorMessage, som FoxIDs visar som vanlig text i inloggningsformuläret. API:t levererar meddelandet på språket valt via Accept-Language:

{
  "error": "login_rejected",
  "errorMessage": "Credentials verified; login rejected by directory policy.",
  "uiErrorMessage": "You cannot log in here. Contact support."
}

Om uiErrorMessage utelämnas, är null, tom eller bara innehåller blanktecken visar FoxIDs samma lokaliserade allmänna inloggningsmeddelande som för invalid_password och operation_rejected. För andra stödda felkoder ignorerar FoxIDs uiErrorMessage och väljer användarmeddelandet ur egna lokaliserade texter. Diagnostisk errorMessage används aldrig som reserv för ett användarmeddelande. Se Autentiseringsfel och användarintegritet för verifieringskrav.

Fel från authentication, change-password och set-password returnerar inte användardata, ändrar inte det interna kontot och återkallar inte befintliga sessioner eller refresh tokens. Synkronisering tillämpar katalogens kontoändringar. Avvisade autentiserings- och lösenordsbytesförsök räknas fortsatt mot befintlig gräns för misslyckade inloggningar.

Felkoder som stöds per endpoint:

Felkod synchronise-user authentication create-user change-password set-password Betydelse
invalid_api_id_secret Ja Ja Ja Ja Ja API-användarnamnet eller hemligheten för HTTP Basic authentication är ogiltigt.
user_exists Nej Nej Ja Nej Nej En användare med den angivna identifieraren finns redan i den externa katalogen.
user_not_exists Utan katalog-ID Nej Nej Nej Nej Ingen kataloganvändare matchade uppslagningen med enbart identifierare.
invalid_password Nej Ja Nej Nej Nej Katalogen avvisade lösenordet i en autentiseringsbegäran.
login_rejected Nej Ja Nej Nej Nej Inloggningen avvisades efter att användaridentifieraren och lösenordet verifierats. Ett valfritt uiErrorMessage visas i inloggningsformuläret.
invalid_current_password Nej Nej Nej Ja Nej Katalogen avvisade det nuvarande lösenordet i en begäran om lösenordsändring.
create_user_not_supported Nej Nej Ja Nej Nej Connectorn stöder inte skapande av användare i den externa katalogen.
operation_rejected Nej Ja Nej Ja Ja Åtgärden kan inte slutföras, exempelvis för att kontot inte är tillgängligt. FoxIDs loggar errorMessage, ignorerar uiErrorMessage och visar ett generellt lokaliserat fel utan att ändra kontotillståndet.
user_deleted Med katalog-ID Nej Nej Nej Nej Ett känt katalog-ID finns inte längre. FoxIDs återkallar åtkomst och raderar användaren under synkronisering.
password_not_accepted Nej Ja Ja Ja Ja Lösenordet som valideras, används för att skapa en användare, ändras eller anges avvisades av en lösenordsregel i katalogen som inte motsvarar en mer specifik kod.
password_min_length Nej Ja Ja Ja Ja Lösenordet som valideras, används för att skapa en användare, ändras eller anges är kortare än katalogens minimilängd för lösenord.
password_max_length Nej Ja Ja Ja Ja Lösenordet som valideras, används för att skapa en användare, ändras eller anges är längre än katalogens maximilängd för lösenord.
password_banned_characters Nej Ja Ja Ja Ja Lösenordet som valideras, används för att skapa en användare, ändras eller anges innehåller ett eller flera tecken eller ord som katalogen avvisar.
password_complexity Nej Ja Ja Ja Ja Äldre fel för teckenkomplexitet som FoxIDs tolkar som password_character_variation. Använd någon av de två specifika teckenfelkoderna för nya integrationer.
password_character_repeat Nej Ja Ja Ja Ja Lösenordet som valideras, används för att skapa en användare, ändras eller anges innehåller för många upprepningar av tecken.
password_character_variation Nej Ja Ja Ja Ja Lösenordet som valideras, används för att skapa en användare, ändras eller anges innehåller inte tillräcklig variation av tecken.
password_email_text_complexity Nej Ja Ja Ja Ja Lösenordet som valideras, används för att skapa en användare, ändras eller anges innehåller användarens e-postadress eller en del av den.
password_phone_text_complexity Nej Ja Ja Ja Ja Lösenordet som valideras, används för att skapa en användare, ändras eller anges innehåller användarens telefonnummer eller en del av det.
password_username_text_complexity Nej Ja Ja Ja Ja Lösenordet som valideras, används för att skapa en användare, ändras eller anges innehåller användarens användarnamn eller en del av det.
password_url_text_complexity Nej Ja Ja Ja Ja Lösenordet som valideras, används för att skapa en användare, ändras eller anges innehåller text relaterad till URL:en för FoxIDs.
password_risk Nej Ja Ja Ja Ja Lösenordet som valideras, används för att skapa en användare, ändras eller anges är känt för att vara riskabelt, komprometterat eller på annat sätt osäkert.
password_history Nej Nej Nej Ja Ja Det nya lösenordet avvisades eftersom det har använts tidigare.
password_expired Nej Ja Nej Nej Nej Det angivna lösenordet har verifierats men gått ut; användaren måste ändra det innan autentiseringen kan fortsätta.
new_password_equals_current Nej Nej Nej Ja Nej Det nya lösenordet är detsamma som det nuvarande. set-password kan inte returnera detta fel eftersom endpointen inte tar emot det nuvarande lösenordet.

När FoxIDs behöver kontrollera sin egen lösenordspolicy före ett lösenordsbyte anropas först authentication för att verifiera aktuellt lösenord. Om connectorn returnerar password_expired från autentiseringen kan bytet fortsätta. Endpointen change-password måste acceptera ett verifierat utgånget aktuellt lösenord och endast returnera fel som stöds för bytesoperationen.

Vid fel i lösenordspolicyn använder FoxIDs miljöns lösenordspolicy för att visa det användarvända felmeddelandet. Se Lösenordspolicy och felmeddelanden.

Returnera endast en felkod som stöds av endpointen och angivet directoryUserId enligt ovan. En kod som inte stöds, ett felaktigt svar eller oväntad HTTP-status är ett integrationsfel och leder till den allmänna felsidan. Se Felsökning av webbläsarfel för diagnostik med identifierarna på felsidan.

Autentiseringsfel och användarnas integritet

En oautentiserad anropare får inte kunna avgöra om ett användarnamn eller en e-postadress finns utifrån ett inloggningsfel. Vid lösenordsautentisering hanterar FoxIDs de fel som stöds enligt följande:

Connectorfel Resultat för användaren
invalid_password, operation_rejected eller ett otillgängligt konto som upptäckts vid synkronisering Samma generella inloggningsmeddelande, till exempel Fel e-post eller lösenord., översatt till det aktiva språket och anpassat till de aktiverade inloggningsidentifierarna.
login_rejected Det angivna uiErrorMessage, eller samma generella inloggningsmeddelande om det saknas eller är blankt, på samma plats i inloggningsformuläret.
password_not_accepted Sidan för lösenordsändring med allmän vägledning om lösenordspolicyn.
password_expired eller ett annat specifikt lösenordspolicyfel Sidan för lösenordsändring med motsvarande lokaliserad vägledning om lösenordspolicyn.

Connectorn måste verifiera det angivna nuvarande lösenordet innan den returnerar ett lösenordspolicyfel från authentication. Annars kan en annan sida eller ett annat meddelande göra det möjligt för en angripare att upptäcka användare och bekräfta deras identifierare genom att gissa användarnamn eller e-postadresser. För change-password ska det nuvarande lösenordet verifieras innan kontospecifik vägledning om det nya lösenordet returneras. Allmänna formatkontroller får inte avslöja om ett konto finns.

Om en användare av någon anledning inte får logga in genom flödet ska angiven identifierare och lösenord först valideras. Returnera en avvisning baserad på begränsningen först efter att båda verifierats, så att begränsningen inte avslöjar om en gissad identifierare tillhör en verklig användare. Returnera login_rejected från authentication, ange diagnostisk orsak i errorMessage och eventuellt säker användarvägledning i uiErrorMessage. Kan uppgifterna inte verifieras returneras vanligt autentiseringsfel utan att begränsningen avslöjas.

FoxIDs förlitar sig på att connectorn verifierar autentiseringsuppgifter innan login_rejected returneras; en lyckad kontouppslagning eller kännedom om directoryUserId räcker inte. Före verifiering ska instruktioner och knappar för alternativa inloggningsmetoder visas oberoende av om angiven identifierare matchar ett konto.

Endast synchronise-user rapporterar kontotillstånd: returnera fullständiga användardata med disableAccount: true för ett inaktiverat konto eller felkoden user_deleted när känt katalog-ID inte längre finns. Lösenordsendpoints returnerar operation_rejected om kontot är otillgängligt. Till skillnad från login_rejected kräver detta fel inget verifierat lösenord eftersom det aldrig ger webbläsaren kontospecifik vägledning.

Hantera fel konsekvent för kända och okända identifierare, inklusive observerbara svarstider och skydd mot upprepade försök. Ett generellt meddelande räcker inte för att förhindra upptäckt av användare om en annan omdirigering, status eller svarstid avslöjar resultatet. Följ OWASP:s vägledning om autentiseringsfel när connectorn implementeras.

API-exempel

Exemplet DirectoryConnectorApiSample visar hur du implementerar Directory Connector API:et i ASP.NET Core.

Implementationer och testklienter måste följa kontrakten ovan: HTTP 200 med fullständiga användardata för synchronise-user, HTTP 200 med skapat katalog-ID för create-user och HTTP 204 utan innehåll för lyckade lösenordsoperationer.

Active Directory-komponent

FoxIDs innehåller en IIS-distribuerbar Directory Connector för Active Directory. Komponenten implementerar Directory Connector API:t för en AD/LDAP-domän och kan synkronisera konton, validera, ändra och ange lösenord samt returnera konfigurerade AD-attribut och nästlade AD-gruppmedlemskap som claims.

Konfigurera

Konfigurera Directory Connector i miljöinställningarna i FoxIDs Control Client.

  1. Välj fliken Inställningar.
  2. Välj fliken Miljö.
  3. Leta upp avsnittet Directory Connector.
  4. Aktivera Directory Connector.
  5. Lägg till API:ets bas-URL utan endpointmappen i API URL.
  6. Lägg till API secret.
  7. Bestäm om en lokal kopia av lösenordet ska sparas.
  8. Konfigurera miljöns lösenordspolicy så att den matchar lösenordspolicyn i den externa katalogen.
  9. Klicka på Update.

Inställningar för Directory Connector