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

När en användare loggar in med användarnamn och lösenord anropar FoxIDs Directory Connector API:et.

Vid lyckad validering skapar eller uppdaterar FoxIDs den interna användaren i miljön baserat på API-svaret. Svaret måste innehålla ett stabilt directoryUserId, som lagras på den interna användaren och används för att knyta FoxIDs-användaren till användaren i den externa katalogen.

directoryUserId är inte en användaridentifierare som slutanvändaren känner till. Det är ett separat stabilt externt katalog-ID. Använd inte e-post, telefon eller användarnamn som directoryUserId, eftersom dessa värden kan ändras. Värdet måste vara stabilt och unikt i den externa katalogen.

Om FoxIDs redan känner till den interna användarens directoryUserId skickas det i Directory Connector-begäran tillsammans med exakt en av användarens identifierare: e-post, telefon eller användarnamn. Detta gör att den externa katalogen kan identifiera användaren även om en identifierare har ändrats.

Om Directory Connector API:et validerar användaren framgångsrikt uppdaterar FoxIDs den interna användaren med identifierare, utvalda egenskaper och claims som returneras från API:et.

Om connectorn rapporterar att användaren är inaktiverad eller borttagen kommer FoxIDs att inaktivera eller ta bort den interna användaren i miljön.

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

Operationer i lösenordets livscykel delegeras till Directory Connector API:et:

  • Lösenordsautentisering anropar endpointen authentication.
  • Login create-user flow calls the create-user endpoint.
  • Ä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.

The API has a base URL and four endpoints:

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.

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.

The API has a base URL and four endpoints:

  • authentication validerar en användares nuvarande lösenord.
  • create-user creates a new user in the external directory and returns the created user.
  • 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.

The API has a base URL and four endpoints:

  • 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 det valda språket i begärans HTTP-header Accept-Language, till exempel Accept-Language: da-DK. I ett inloggningsflöde följer detta det språk som valts via ui_locales eller webbläsaren, med engelska som reservspråk i FoxIDs. API:et kan använda denna header för att lokalisera användarvända meddelanden och måste välja ett eget reservspråk om det begärda språket inte stöds. Denna header skickas till alla fyra endpoints.

Authentication-begäran

Endpointen authentication tar emot användarens lösenord och exakt en användaridentifierare. FoxIDs skickar directoryUserId om den interna användaren finns och värdet är känt.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "password": "testpass1"
}

Fält:

  • directoryUserId är valfritt. FoxIDs skickar det när den interna användaren finns och värdet är känt.
  • Exakt en av email, phone eller username skickas.
  • password är obligatoriskt.

FoxIDs väljer identifieraren utifrån användarens inloggningsinput och de aktiverade identifierarinställningarna. Om till exempel bara användarnamn är aktiverat och användaren skriver in user1@somewhere.org, skickar FoxIDs det värdet som username. FoxIDs tar bort omgivande blanksteg innan användarnamnet skickas till connectorn.

Create-user request

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.

Vid framgång returneras ett normalt lyckat svar. FoxIDs lagrar det returnerade directoryUserId på den interna användare som skapas efter att användaren har skapats i den externa katalogen.

Change-password-begäran

Endpointen change-password tar emot exakt en användaridentifierare, nuvarande lösenord och nytt lösenord. FoxIDs skickar directoryUserId när den interna användaren finns och värdet är känt.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "currentPassword": "oldpass1",
  "newPassword": "newpass1"
}

Fält:

  • directoryUserId är valfritt. FoxIDs skickar det när den interna användaren finns och värdet är känt. Det kan utelämnas vid första inloggningen om den externa katalogen kräver lösenordsändring innan FoxIDs har skapat den interna användaren.
  • Exakt en av email, phone eller username skickas.
  • currentPassword och newPassword är obligatoriska.

Set-password-begäran

Endpointen set-password tar emot användarens stabila katalogkoppling, exakt en användaridentifierare och ett nytt lösenord.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "password": "newpass1"
}

Fält:

  • directoryUserId skickas och bör användas som den stabila katalogkopplingen.
  • Exakt en av email, phone eller username skickas. FoxIDs väljer den första tillgängliga interna användaridentifieraren i denna ordning: e-post, telefon, användarnamn.
  • password är obligatoriskt.

Svarsdata vid lyckat resultat

Vid lyckat resultat måste API:et returnera HTTP-statuskod 200 och ett användarsvar.

{
  "directoryUserId": "a1b2c3d4",
  "email": "user1@somewhere.org",
  "phone": "+4511223344",
  "username": "user1",
  "confirmAccount": true,
  "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.
  • 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.

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.

Felsvar

Om Basic authentication avvisas, returnera HTTP-statuskod 401 och invalid_api_id_secret.

{
  "error": "invalid_api_id_secret",
  "errorMessage": "Invalid API ID or secret."
}

Om användaren inte finns vid anrop till endpointen authentication utan ett directoryUserId, returnera HTTP-statuskod 400, 401 eller 403 och user_not_exists.

{
  "error": "user_not_exists",
  "errorMessage": "User not found."
}

Om lösenordet avvisas av endpointen authentication, returnera HTTP-statuskod 400, 401 eller 403 och invalid_password.

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

Om användaridentifieraren och lösenordet är giltiga men inloggningen avvisas av en annan anledning ska authentication returnera HTTP-statuskod 400, 401 eller 403 och login_rejected. Det stöds både med och utan directoryUserId. Det valfria uiErrorMessage visas som vanlig text i inloggningsformuläret. API:et tillhandahåller det översatta meddelandet utifrån 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, tomt eller endast innehåller blanktecken visar FoxIDs samma lokaliserade generella inloggningsmeddelande som för invalid_password, user_not_exists, user_disabled och user_deleted. En avvisad inloggning räknas med i det befintliga skyddet mot upprepade misslyckade inloggningsförsök. Den skapar, uppdaterar, inaktiverar eller tar inte bort den interna användaren.

Om det nuvarande lösenordet avvisas av endpointen change-password, returnera HTTP-statuskod 400, 401 eller 403 och invalid_current_password.

{
  "error": "invalid_current_password",
  "errorMessage": "Invalid current password."
}

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.

FoxIDs visar ett returnerat uiErrorMessage endast för login_rejected. För andra felkoder som stöds väljer FoxIDs det användarvända meddelandet från sina egna lokaliserade textresurser. Diagnostisk text i errorMessage används aldrig som reserv för ett användarvänt meddelande.

Felkoder som stöds per endpoint:

Felkod authentication create-user change-password set-password Betydelse
invalid_api_id_secret Ja Ja Ja Ja API-användarnamnet eller hemligheten för HTTP Basic authentication är ogiltigt.
user_exists Nej Ja Nej Nej En användare med den angivna identifieraren finns redan i den externa katalogen.
user_not_exists Ja, utan directoryUserId Nej Ja, utan directoryUserId Nej Ingen användare i den externa katalogen matchade de angivna användaridentifierarna.
invalid_password Ja Nej Nej Nej Katalogen avvisade lösenordet i en autentiseringsbegäran.
login_rejected 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 Ja Nej Katalogen avvisade det nuvarande lösenordet i en begäran om lösenordsändring.
create_user_not_supported Nej Ja Nej Nej Connectorn stöder inte skapande av användare i den externa katalogen.
user_disabled Ja Nej Ja Ja Användaren finns i katalogen men är inaktiverad. FoxIDs inaktiverar den interna användaren.
user_deleted Ja, med directoryUserId Nej Ja, med directoryUserId Ja, med directoryUserId Användaren i den externa katalogen som är kopplad via directoryUserId finns inte längre eller har tagits bort. FoxIDs tar bort den interna användaren.
password_not_accepted 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 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 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 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 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 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 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 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 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 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 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 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 Ja Ja Ja Ja Lösenordet som valideras, används för att skapa en användare, ändras eller anges avvisades eftersom det har använts tidigare.
password_expired Ja Ja Ja Ja Lösenordet som valideras, används för att skapa en användare, ändras eller anges har gått ut och måste ändras innan autentiseringen kan fortsätta.
new_password_equals_current 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.

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 det angivna directoryUserId, enligt tabellen ovan. En kod som inte stöds, ett felaktigt formaterat svar eller en oväntad HTTP-status är ett integrationsfel och leder till den generella felsidan. Returnera HTTP-statuskod 500 vid ett tekniskt fel i connectorn. Se Felsökning av webbläsarfel för att hitta diagnostiska uppgifter med hjälp av 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, user_not_exists, user_disabled eller user_deleted 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 via detta inloggningsflöde ska den angivna användaridentifieraren och lösenordet först valideras. Returnera en avvisning baserad på denna begränsning först efter att båda har 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 den diagnostiska orsaken i errorMessage och lägg vid behov till säker vägledning för användaren i uiErrorMessage. Om inloggningsuppgifterna inte kan verifieras ska det vanliga autentiseringsfelet returneras utan att begränsningen avslöjas.

FoxIDs förlitar sig på att connectorn verifierar inloggningsuppgifterna innan den returnerar login_rejected; en lyckad kontosökning eller kännedom om directoryUserId räcker inte. Innan inloggningsuppgifterna har verifierats ska eventuella instruktioner eller knappar för alternativa inloggningsmetoder visas oberoende av om den angivna identifieraren matchar ett konto.

Använd endast user_disabled och user_deleted för att rapportera motsvarande kontotillstånd i katalogen. De inaktiverar eller tar också bort den interna användaren och återkallar användarens åtkomst; de är inte generella koder för att avvisa inloggning.

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.

Exemplet innehåller: The API has a base URL and four endpoints:

  • HTTP Basic authentication med API-användarnamnet directory_connector.
  • en liten in-memory-katalog med demoanvändare och stabila directoryUserId-värden.
  • exempel på fel i lösenordspolicyn som password_min_length, password_banned_characters och new_password_equals_current.
  • ett exempel på en inaktiverad användare som returnerar user_disabled.

Postman-samlingen directory-connector-api.postman_collection.json kan användas för att anropa och testa exempel-API:et med Postman.

Active Directory-komponent

FoxIDs innehåller en Directory Connector för Active Directory-komponent som kan distribueras till IIS. Komponenten implementerar Directory Connector API:et för en AD/LDAP-domän och kan validera lösenord, ändra lösenord, sätta lösenord, returnera konfigurerade AD-attribut som claims och returnera konfigurerade nästlade AD-gruppmedlemskap som claims.

Konfigurera

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

  1. Välj fliken Settings.
  2. Välj fliken Environment.
  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