Directory Connector
Met Directory Connector kan FoxIDs een externe directory gebruiken als gezaghebbende bron voor wachtwoorden van interne gebruikers en geselecteerde gebruikersgegevens.
De gebruikers bestaan nog steeds als interne gebruikers in de FoxIDs-omgeving. Tijdens wachtwoordauthenticatie en bewerkingen in de wachtwoordlevenscyclus roept FoxIDs de Directory Connector API aan in plaats van het wachtwoord alleen te valideren tegen de interne FoxIDs-gebruiker.
Omdat FoxIDs een intern gebruikersrecord bewaart, kan FoxIDs multi-factor-authenticatie (MFA)-afhandeling worden toegevoegd aan gebruikers uit de externe repository. De connector kan MFA-gerelateerde gebruikersinstellingen retourneren, zoals requireMultiFactor en uitgeschakelde two-factor-methoden, en FoxIDs past deze instellingen toe op de interne gebruiker terwijl de externe repository gezaghebbend blijft voor wachtwoorden en geselecteerde gebruikersgegevens.
Voor Active Directory bevat FoxIDs een op IIS deploybare Directory Connector voor Active Directory-component.
Gebruik Directory Connector wanneer:
- gebruikers zich moeten aanmelden met de normale login-authenticatiemethode.
- u gebruikers uit een bestaande directory wilt inschakelen voor OpenID Connect- en SAML 2.0-applicaties via FoxIDs.
- uw externe directory gezaghebbend is voor wachtwoordvalidatie en wachtwoordwijzigingen.
- u wilt dat FoxIDs een intern gebruikersrecord bewaart met identifiers, eigenschappen, claims, multi-factor-authenticatie (MFA)-instellingen, toegangstoewijzingen en optioneel een lokale kopie van het wachtwoord.
- u later wilt kunnen overstappen naar interne gebruikers en wachtwoordvalidatie in FoxIDs zonder alle gebruikers door een wachtwoordreset te dwingen.
Er is één Directory Connector per omgeving. Wanneer deze is ingeschakeld, geldt deze op omgevingsniveau.
Hoe het werkt
FoxIDs synchroniseert op aanvraag wanneer een gebruiker een identificatie invoert tijdens aanmelden of herstel. Het roept synchronise-user aan voordat het account wordt gecontroleerd, maakt zo nodig een FoxIDs gebruiker aan en werkt identificaties, eigenschappen en claims bij die door de directory worden beheerd.
Synchronisatie hoort bij het inschakelen van Directory Connector. FoxIDs synchroniseert aan het begin van aanmelden, herstel en accountcontroles bij bestaande sessies, en wanneer een refresh token wordt gebruikt voor een aan de directory gekoppeld account. Vervolgstappen met bevestigingscodes, MFA en Extended UI gebruiken het geselecteerde account en de normale FoxIDs controles. Mislukte synchronisatie stopt de flow.
Het antwoord moet een stabiele, unieke directoryUserId bevatten. Gebruik de permanente account-ID van de directory in plaats van e-mail, telefoonnummer of gebruikersnaam. Met deze koppeling vindt FoxIDs hetzelfde account na wijzigingen in identificaties. Geregistreerde authenticator-apps en FoxIDs toegangstoewijzingen blijven behouden.
Wanneer een gebruiker een identificatie invoert, verstuurt FoxIDs uitsluitend dat e-mailadres, telefoonnummer of die gebruikersnaam. Bij sessiehergebruik en refresh-tokenverzoeken laadt FoxIDs de gekoppelde gebruiker en synchroniseert met de directory-ID die daarop is opgeslagen. Ook wachtwoordbewerkingen gebruiken de directory-ID van de geladen gebruiker. Deze wordt niet apart in de aanmeldsequentie opgeslagen.
De connector retourneert de volledige actuele gebruikersgegevens. FoxIDs vervangt identificaties, eigenschappen en claims van de directory, inclusief accountuitschakeling, verplichte wachtwoordwijziging en instellingen voor het eerste wachtwoord. Dezelfde account-, herstel- en MFA-controles als voor interne gebruikers worden toegepast. Interne gebruikers zonder directorykoppeling worden niet gesynchroniseerd of automatisch gekoppeld.
Een synchronisatieantwoord met disableAccount: true schakelt de FoxIDs gebruiker uit en trekt actieve sessies en refresh-token grants in. Retourneert de connector de foutcode user_deleted bij synchronisatie via de directory-ID, dan verwijdert FoxIDs de interne gebruiker en trekt actieve sessies en refresh tokens in. Vindt een zoekopdracht uitsluitend op identificatie geen account, dan controleert FoxIDs een eventuele bestaande directorykoppeling voordat de flow doorgaat, zodat verouderde lokale accountgegevens geen aanmelding of herstel toestaan. De foutcode user_not_exists alleen verwijdert geen account.
Refresh-tokenverzoeken controleren zowel het oorspronkelijke account als een lokaal account dat via impersonatie wordt gebruikt, indien ze aan de directory zijn gekoppeld. Ontdekt de synchronisatie een uitgeschakeld of verwijderd account, dan trekt FoxIDs actieve sessies en refresh-token grants in en weigert de huidige tokenvernieuwing. De gewone controle van actieve sessies valideert de FoxIDs sessiestatus; deze benadert de directory niet zelf. Een applicatie die een uitgegeven access token lokaal valideert, volgt het verlopen van het token in plaats van het intrekken van de FoxIDs sessie.
Wijzigingen worden beschikbaar bij de volgende accountcontrole op aanvraag. Er is geen synchronisatieproces op de achtergrond.
Directory Connector kan dienen als permanente integratie, met beheer van gebruikers en wachtwoorden in de externe directory, of om gebruikers geleidelijk naar FoxIDs te migreren. Houd bij migratie de connector ingeschakeld terwijl gebruikers worden aangemaakt en schakel de lokale wachtwoordkopie in om wachtwoorden op te slaan na succesvolle authenticatie, wijziging of herstel via FoxIDs.
Schakel na de migratie Directory Connector uit en beheer gebruikers en wachtwoorden rechtstreeks in FoxIDs. Maak vooraf gebruikers aan die nog niet bestaan en regel het instellen of herstellen van wachtwoorden voor gebruikers zonder actuele lokale wachtwoordkopie. De kopie weerspiegelt de laatste succesvolle wachtwoordauthenticatie, wijziging of reset via FoxIDs; latere wijzigingen uitsluitend in de externe directory zijn niet opgenomen.
Bescherming van zoekopdrachten
Wanneer een gebruiker een e-mailadres, telefoonnummer of gebruikersnaam invoert in de aanmeld- of herstelinterface, telt de directoryzoekopdracht mee voor een gezamenlijke limiet van alle ingevoerde identificaties in de huidige aanmeldsequentie. Deze gebruikt de omgevingsinstellingen voor Failed login attempt limit, de levensduur van de teller en de observatieperiode. Succesvolle zoekopdrachten en mislukte connectoraanroepen tellen beide mee; succesvolle wachtwoordauthenticatie stelt de teller niet opnieuw in. Bij de limiet moet de observatieperiode worden afgewacht of een nieuwe aanmeldsequentie worden gestart. Synchronisatie bij sessiehergebruik en refresh-tokenverzoeken gebruikt deze teller niet. Wachtwoord- en bevestigingscodebeveiliging blijven hun bestaande afzonderlijke tellers gebruiken.
Aanmeldingsidentifiers en directorykoppeling
Gebruikers kunnen zich aanmelden met hun huidige e-mailadres, telefoonnummer of gebruikersnaam, afhankelijk van de identificatietypen die op de aanmeldmethode zijn ingeschakeld. Vóór wachtwoordauthenticatie moet de ingevoerde identificatie overeenkomen met een actuele identificatie uit het connectorantwoord. FoxIDs verwijdert omliggende witruimte. E-mailadressen en gebruikersnamen worden hoofdletterongevoelig vergeleken. Telefoonnummers gebruiken het vereiste internationale formaat.
Aanmelden na gewijzigde identificaties
Wanneer gebruikers een identificatie invoeren, synchroniseert FoxIDs hun e-mailadres, telefoonnummer en gebruikersnaam vanuit de directory. De stabiele directory-ID koppelt hen aan hetzelfde FoxIDs account, ook als één of alle identificaties wijzigen. Geregistreerde authenticator-apps en toegangstoewijzingen blijven behouden en bestaande toegangsbeperkingen en MFA-eisen blijven gelden.
| Situatie | Wat gebeurt er tijdens synchronisatie? |
|---|---|
| De gebruiker meldt zich aan met een ongewijzigde gebruikersnaam terwijl het e-mailadres of telefoonnummer in de directory is gewijzigd. | FoxIDs werkt hetzelfde account bij met de actuele identificaties van de connector. |
| De gebruiker meldt zich aan met een nieuwe identificatie die FoxIDs nog niet kent. | Als de directory de nieuwe identificatie en dezelfde stabiele directory-ID retourneert, gaat de gebruiker verder met het bestaande FoxIDs account. Dit werkt ook wanneer alle identificaties zijn gewijzigd. |
| De gebruiker meldt zich aan met een oude identificatie die de connector niet meer retourneert. | De aanmelding wordt geweigerd met de normale aanmeldfout, ook als de gebruiker het wachtwoord nog kent. Er is een actuele identificatie van een ingeschakeld type nodig. |
| De connector retourneert een e-mailadres, telefoonnummer of gebruikersnaam niet meer. | Deze identificatie wordt tijdens synchronisatie uit het FoxIDs account verwijderd. De connector moet minstens één actuele identificatie retourneren. |
Een gebruiker wiens e-mailadres verandert van old@example.org naar new@example.org kan zich bijvoorbeeld aanmelden met new@example.org voordat FoxIDs dat adres kent. De connector moet new@example.org en de ongewijzigde directory-ID retourneren. Hetzelfde account en de geregistreerde authenticator-apps blijven behouden. Aanmelden met een ongewijzigde gebruikersnaam kan ook, als die aanmeldoptie is ingeschakeld.
De connector moet alle actuele identificaties retourneren die FoxIDs moet behouden. Ontbrekende of lege waarden gelden als verwijderde identificaties; eerdere waarden blijven niet als aanmeldalias bestaan. Alleen identificatietypen die op de aanmeldmethode zijn ingeschakeld, kunnen voor aanmelding worden gebruikt.
Accountconflicten
Elke directorygebruiker moet een stabiele, unieke directory-ID hebben en identificaties die niet bij een ander FoxIDs account horen. FoxIDs zoekt eerst de ingevoerde identificatie in de directory en vindt of maakt het lokale account vervolgens via de geretourneerde directory-ID. Als het opslaan van de identificaties conflicteert met een ander account, stopt de flow. Een beheerder moet de directory- of FoxIDs accountconfiguratie corrigeren; accounts worden niet automatisch samengevoegd of opnieuw toegewezen.
Een bestaande interne gebruiker zonder directorykoppeling kan zich niet via Directory Connector aanmelden. Inschakelen koppelt een bestaand account niet automatisch aan een directorygebruiker alleen omdat e-mailadres, telefoonnummer of gebruikersnaam overeenkomt.
Lokale wachtwoordkopie
De externe directory is gezaghebbend zolang Directory Connector is ingeschakeld. FoxIDs valt niet terug op de lokale wachtwoordhash als de Directory Connector API tijdelijk niet beschikbaar is.
Standaard slaat FoxIDs een lokale kopie van het wachtwoord op bij de interne gebruiker na een succesvolle wachtwoordvalidatie via de connector of na een bewerking in de wachtwoordlevenscyclus. Dit kan worden uitgeschakeld in de omgevingsinstellingen.
De lokale wachtwoordkopie wordt niet gebruikt zolang Directory Connector is ingeschakeld. Deze bestaat om later een overstap naar interne gebruikers en wachtwoordvalidatie in FoxIDs mogelijk te maken zonder alle gebruikers te dwingen hun wachtwoord te resetten.
Wachtwoordlevenscyclus
Het aanmaken van gebruikers en bewerkingen in de wachtwoordlevenscyclus worden gedelegeerd aan de Directory Connector API:
- Wachtwoordauthenticatie roept het
authentication-endpoint aan. - Gebruikersaanmaak tijdens aanmelden roept het endpoint
create-useraan. - Het wijzigen van het gebruikerswachtwoord roept het
change-password-endpoint aan. - De stromen voor wachtwoord instellen en wachtwoord resetten roepen het
set-password-endpoint aan.
Wachtwoordendpoints ontvangen de stabiele directoryUserId van de geladen gebruiker. De directory controleert de actuele accountstatus en aanmeldgegevens tijdens de bewerking. Authenticatie, wachtwoordwijziging en reset retourneren succes of een fout. Gebruikersaanmaak retourneert de directory-ID van het aangemaakte account voor een afzonderlijke synchronisatie door FoxIDs.
Wachtwoordbewerkingen gebruiken de directory-ID van de geladen FoxIDs gebruiker. De connector controleert de accountstatus en de vereiste aanmeldgegevens of resetautorisatie, voert de actie uit en retourneert succes of een fout. Gebruikersidentificaties, attributen en claims worden alleen bij synchronisatie geretourneerd.
Na een succesvolle wachtwoordwijziging of reset legt FoxIDs het huidige wijzigingstijdstip vast en verwijdert de verplichting om een wachtwoord te wijzigen of in te stellen. Indien geconfigureerd wordt ook een lokale wachtwoordkopie opgeslagen. De actieve sequentie gaat vervolgens door met de normale account-, herstel- en MFA-afhandeling in FoxIDs.
Als een actie mislukt of FoxIDs de bekende wachtwoordwijzigingen niet kan opslaan, stopt de flow. Een door de directory geaccepteerde wachtwoordwijziging wordt niet teruggedraaid en FoxIDs herhaalt de actie niet automatisch na een time-out of mislukt antwoord. De volgende synchronisatie werkt het lokale account bij.
Als Enable password policy is ingeschakeld, verifieert FoxIDs het huidige directorywachtwoord voordat de controles van het nieuwe wachtwoord worden toegepast. Dit kan een extra authenticatieaanroep vóór change-password vereisen.
FoxIDs werkt zijn interne wachtwoordgeschiedenis niet bij wanneer Directory Connector wordt gebruikt, omdat FoxIDs niet noodzakelijk alle wachtwoordwijzigingen in de externe directory kent.
Wachtwoord instellen en herstellen
Bij de eerste aanmelding kan een directorygebruiker een wachtwoord instellen met een bevestigingscode via e-mail of SMS, omdat het wachtwoord is vergeten of omdat een nieuw wachtwoord verplicht is.
Voer voor Forgot your password? een actuele directory-identificatie in van een type dat op de aanmeldmethode is ingeschakeld. FoxIDs synchroniseert en maakt het account aan voordat de bevestigingscode wordt verzonden. Herstel via e-mail of SMS moet zijn ingeschakeld en de gebruiker moet toegang hebben tot het actuele herstelcontact uit de directory.
Nadat de gebruiker de code heeft geverifieerd en een nieuw wachtwoord heeft ingediend, roept FoxIDs set-password aan met de stabiele directory-ID. Retourneer setPasswordEmail of setPasswordSms en de bijbehorende contactidentificatie om het instellen van een wachtwoord via deze flow te verplichten. FoxIDs gebruikt de normale flow voor het instellen van wachtwoorden.
Bevestigingscodes zijn gebonden aan het account waarvoor ze zijn uitgegeven. Accounts beheerd via een directoryconnector gebruiken dezelfde codeverificatie als andere interne gebruikers. FoxIDs behoudt de normale foutafhandeling bij herstel zonder connectordiagnostiek te tonen.
Wachtwoordbeleid en foutmeldingen
De externe directory handhaaft het wachtwoordbeleid. FoxIDs gebruikt het wachtwoordbeleid van de omgeving wanneer het foutmeldingen over wachtwoordbeleid weergeeft die door de connector zijn geretourneerd.
Configureer het wachtwoordbeleid van de omgeving zodat dit overeenkomt met het wachtwoordbeleid van de externe directory. Als ze niet overeenkomen, kunnen gebruikers wachtwoordhints zien die niet overeenkomen met de werkelijke vereisten van de externe directory.
Als de externe directory bijvoorbeeld een wachtwoord afwijst omdat het te kort is, gebruikt FoxIDs de minimale wachtwoordlengte van de omgeving bij het weergeven van de foutmelding.
API implementeren
U implementeert een Directory Connector API en configureert FoxIDs met de basis-URL en het secret.
De API heeft een basis-URL en vijf endpoints:
synchronise-userzoekt een gebruiker en retourneert de huidige accountstatus, identificaties en claims.authenticationvalideert het huidige wachtwoord van een gebruiker.create-usermaakt een gebruiker in de externe directory aan en retourneert de permanente directory-ID.change-passwordvalideert het huidige wachtwoord en wijzigt het naar een nieuw wachtwoord.set-passwordstelt een nieuw wachtwoord in zonder het huidige wachtwoord te valideren.
Als de basis-URL https://somewhere.org/directory is, zijn de endpoints:
https://somewhere.org/directory/synchronise-userhttps://somewhere.org/directory/authenticationhttps://somewhere.org/directory/create-userhttps://somewhere.org/directory/change-passwordhttps://somewhere.org/directory/set-password
FoxIDs Cloud roept uw API aan vanaf IP
57.128.60.142. IP-adressen kunnen wijzigen of worden uitgebreid.
Beveiliging
Aanvragen worden beveiligd met HTTP Basic authentication:
- Gebruikersnaam:
directory_connector - Wachtwoord: het geconfigureerde API-secret
De call is een HTTP POST met een JSON-body.
FoxIDs verstuurt de geselecteerde taal in de requestheader Accept-Language, bijvoorbeeld Accept-Language: da-DK. Bij aanmelden volgt dit de taal uit ui_locales of de browser, met Engels als terugvaltaal in FoxIDs. De API kan deze header gebruiken om gebruikersmeldingen te lokaliseren en moet zelf een terugvaltaal kiezen als de gevraagde taal niet wordt ondersteund. De header wordt naar alle vijf endpoints gestuurd.
Synchronisatieverzoek
Het endpoint synchronise-user ontvangt een gebruikersidentificatie of bekende directory-ID. De eerste zoekopdracht bij aanmelden of herstel gebruikt de ingevoerde identificatie. FoxIDs gebruikt de opgeslagen directoryUserId voor controles van bestaande sessies en refresh-tokenverzoeken, en de geretourneerde directory-ID na create-user.
Een eerste zoekopdracht met e-mail:
{
"email": "user1@somewhere.org"
}
Een volgende accountcontrole:
{
"directoryUserId": "a1b2c3d4"
}
Gebruik directoryUserId als leidende zoeksleutel wanneer deze aanwezig is. Zoek anders op precies één van email, phone of username. Retourneer HTTP 200 met de volledige gebruikersgegevens, ook voor uitgeschakelde accounts. Retourneer foutcode user_deleted als de bekende ID ontbreekt en user_not_exists als een zoekopdracht uitsluitend op identificatie geen account vindt. Een opgegeven identificatie bewijst nooit eigendom van een account.
FoxIDs kiest de verzoekidentificatie op basis van de ingeschakelde aanmeldidentificaties. Is alleen gebruikersnaam ingeschakeld, dan wordt invoer in e-mailformaat als username verstuurd. Omliggende witruimte wordt verwijderd. De invoer moet overeenkomen met een actuele antwoordidentificatie van een ingeschakeld type; het veronderstelde verzoekveld beperkt niet welk antwoordveld kan overeenkomen.
Zie Foutantwoord voor fouten.
Antwoord bij succes
Het endpoint synchronise-user retourneert HTTP 200 met volledige actuele gebruikersgegevens. Bevat het verzoek een directory-ID, dan moet het antwoord dezelfde ID bevatten. FoxIDs controleert dit voordat gegevens worden opgeslagen. HTTP 204 of onvolledige gebruikersgegevens worden geweigerd.
{
"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 gebruikt de respons om de interne gebruiker in de omgeving aan te maken of bij te werken.
Velden:
directoryUserIdis verplicht. Deze moet stabiel en uniek zijn in de externe directory en wordt opgeslagen op de interne FoxIDs-gebruiker.email,phoneenusernamezijn elk afzonderlijk optioneel, maar minstens één moet aanwezig zijn. FoxIDs slaat de geretourneerde waarden op als identifiers van de interne gebruiker. Geretourneerde gebruikersidentifierwaarden moeten één gebruiker uniek identificeren in de externe directory die door de connector wordt gebruikt.phonemoet de landcode bevatten in internationaal formaat, bijvoorbeeld+4511223344.confirmAccountbepaalt of FoxIDs een bevestigingsstroom moet uitvoeren om de interne gebruiker te bevestigen.disableAccountbepaalt de directe uitschakelstatus van het account. Uitschakelen trekt de FoxIDs sessies en refresh-token grants van de gebruiker in.changePasswordvereist een wachtwoordwijziging na succesvolle verificatie van de aanmeldgegevens.setPasswordEmailensetPasswordSmsvereisen het instellen van een wachtwoord via de betreffende bevestigingscodeflow. De contactidentificatie moet aanwezig zijn en de herstelmethode moet zijn ingeschakeld.disableSetPasswordEmailendisableSetPasswordSmsschakelen de betreffende herstelmethoden uit.passwordLastChangedis een optioneel, niet-negatief Unix-tijdstip in seconden. Bij synchronisatie werkt deze waarde de wachtwoordleeftijd in FoxIDs bij. Zonder deze waarde blijft een bestaand tijdstip behouden. Een succesvolle wachtwoordwijziging of reset slaat de huidige tijd in FoxIDs op; latere synchronisatie kan het leidende tijdstip van de directory leveren.emailVerifiedbepaalt of de e-mail van de interne gebruiker als geverifieerd wordt gemarkeerd.phoneVerifiedbepaalt of het telefoonnummer van de interne gebruiker als geverifieerd wordt gemarkeerd.disableTwoFactorAppschakelt twee-factor-authenticatie met een authenticator-app uit voor de interne gebruiker.disableTwoFactorSmsschakelt sms-twee-factor-authenticatie uit voor de interne gebruiker.disableTwoFactorEmailschakelt e-mail-twee-factor-authenticatie uit voor de interne gebruiker.requireMultiFactorbepaalt of de interne gebruiker multi-factor-authenticatie moet gebruiken.claimsis optioneel. FoxIDs slaat de geretourneerde claims op bij de interne gebruiker.
Claims ondersteunen een optionele valueType: String, Boolean, Number, JsonObject of JsonArray. Het veld value blijft tekst; laat valueType weg voor String. FoxIDs behoudt het geselecteerde type en logt een waarschuwing voordat een ongeldige waarde terugvalt op tekst. Zie typen claimwaarden voor voorbeelden en getalgrenzen. Dezelfde weergave wordt gebruikt voor claims die worden verzonden in aanvragen om gebruikers te maken en worden geretourneerd in synchronisatieantwoorden.
FoxIDs negeert claims waarvan type of value ontbreekt, null is, leeg is of alleen witruimte bevat. Als tracelogging van berichten is ingeschakeld, bevat de responstrace de ontvangen claims voordat ze worden gefilterd. Lange traceberichten worden afgekapt.
Beschermde claims, zoals sid en auth_time, worden ook uit synchronisatieantwoorden verwijderd.
Authentication-aanvraag
Het endpoint authentication ontvangt de vereiste stabiele directory-ID en het huidige wachtwoord.
{
"directoryUserId": "a1b2c3d4",
"password": "testpass1"
}
Controleer de actuele directoryaccountstatus en het wachtwoord voordat succes wordt teruggegeven. Verifieer het wachtwoord voordat accountspecifieke wachtwoordbeleidinformatie wordt verstrekt.
Zie Foutantwoord voor fouten.
Antwoord bij succes
Retourneer bij succes HTTP 204 zonder antwoordinhoud.
Verzoek om een gebruiker aan te maken
Het endpoint create-user ontvangt precies één gebruikersidentifier, een verplicht wachtwoord, geselecteerde create-user-eigenschappen en claims die tijdens de FoxIDs create-user-flow zijn verzameld.
{
"email": "user1@somewhere.org",
"password": "testpass1",
"confirmAccount": true,
"requireMultiFactor": false,
"claims": [
{ "type": "given_name", "value": "User" },
{ "type": "family_name", "value": "One" }
]
}
Velden:
- Precies één van
email,phoneofusernamewordt verzonden. passwordis verplicht. Gebruiker aanmaken zonder wachtwoord wordt niet ondersteund met Directory Connector, omdat de Directory Connector API gebruikers met een wachtwoord authenticeert.confirmAccountenrequireMultiFactorzijn de gevraagde instellingen voor het aanmaken van de gebruiker in FoxIDs.claimsbevat de claims die geen identifiers zijn en die tijdens het aanmaken van de gebruiker in FoxIDs worden verzameld.
Zie Foutantwoord voor fouten.
Antwoord bij succes
Retourneer bij succes HTTP 200 met de permanente directory-ID van het aangemaakte account:
{
"directoryUserId": "a1b2c3d4"
}
FoxIDs roept vervolgens synchronise-user aan met deze ID om het volledige account op te halen en de interne FoxIDs gebruiker aan te maken.
Change-password-aanvraag
Het endpoint change-password ontvangt de vereiste directory-ID, het huidige en het nieuwe wachtwoord. Verifieer het huidige wachtwoord voordat accountspecifieke beleidsinformatie wordt verstrekt.
{
"directoryUserId": "a1b2c3d4",
"currentPassword": "oldpass1",
"newPassword": "newpass1"
}
Zie Foutantwoord voor fouten.
Antwoord bij succes
Retourneer bij succes HTTP 204 zonder antwoordinhoud. De wachtwoordwijziging moet aan de wachtwoordvereiste in de directory voldoen.
Set-password-aanvraag
Het endpoint set-password ontvangt de vereiste directory-ID en het nieuwe wachtwoord. FoxIDs roept dit aan na autorisatie van reset of instelling, inclusief codeverificatie in herstelflows. De connector moet de actuele accountstatus opnieuw controleren voordat het wachtwoord wordt gewijzigd.
{
"directoryUserId": "a1b2c3d4",
"password": "newpass1"
}
Zie Foutantwoord voor fouten.
Antwoord bij succes
Retourneer bij succes HTTP 204 zonder antwoordinhoud. Het resetten of instellen moet aan de wachtwoordvereiste in de directory voldoen.
Foutrespons
Alle endpoints gebruiken hetzelfde JSON-foutformaat. Retourneer een ondersteunde endpointfoutcode in error en diagnostische details in errorMessage. Bijvoorbeeld een geweigerd wachtwoord vanuit authentication:
{
"error": "invalid_password",
"errorMessage": "Invalid password."
}
Gebruik deze HTTP-statuscodes:
- 401 met foutcode
invalid_api_id_secretwanneer HTTP Basic-authenticatie wordt geweigerd. - 400, 401 of 403 voor overige ondersteunde foutcodes in de onderstaande endpointtabel.
- 500 bij een technische connectorfout.
Het veld errorMessage bevat diagnostische tekst voor de logboeken van FoxIDs en wordt niet aan de eindgebruiker getoond. Vermeld de reden voor de fout, maar neem nooit wachtwoorden, API-geheimen of privésleutels op.
Alleen het endpoint authentication mag de foutcode login_rejected retourneren na verificatie van de gebruikersidentificatie en het wachtwoord. Het kan een optionele uiErrorMessage bevatten, die FoxIDs als gewone tekst in het aanmeldformulier toont. De API levert dit bericht in de taal geselecteerd via Accept-Language:
{
"error": "login_rejected",
"errorMessage": "Credentials verified; login rejected by directory policy.",
"uiErrorMessage": "You cannot log in here. Contact support."
}
Als uiErrorMessage ontbreekt, null of leeg is of alleen witruimte bevat, toont FoxIDs dezelfde gelokaliseerde algemene aanmeldmelding als voor invalid_password en operation_rejected. Voor andere ondersteunde foutcodes negeert FoxIDs uiErrorMessage en kiest de gebruikersmelding uit eigen gelokaliseerde teksten. Diagnostische errorMessage-tekst wordt nooit als terugval voor een gebruikersmelding gebruikt. Zie Authenticatiefouten en gebruikersprivacy voor verificatievereisten.
Fouten van authentication, change-password en set-password retourneren geen gebruikersgegevens, wijzigen geen intern account en trekken geen bestaande sessies of refresh tokens in. Synchronisatie past directoryaccountwijzigingen toe. Geweigerde authenticatie- en wachtwoordwijzigingspogingen tellen nog steeds mee voor de bestaande limiet voor mislukte aanmeldingen.
Ondersteunde foutcodes per endpoint:
| Foutcode | synchronise-user |
authentication |
create-user |
change-password |
set-password |
Betekenis |
|---|---|---|---|---|---|---|
invalid_api_id_secret |
Ja | Ja | Ja | Ja | Ja | De API-gebruikersnaam of het geheim voor HTTP Basic authentication is ongeldig. |
user_exists |
Nee | Nee | Ja | Nee | Nee | Er bestaat al een gebruiker met de opgegeven identifier in de externe directory. |
user_not_exists |
Zonder directory-ID | Nee | Nee | Nee | Nee | Geen directorygebruiker kwam overeen met de zoekopdracht uitsluitend op identificatie. |
invalid_password |
Nee | Ja | Nee | Nee | Nee | De directory heeft het wachtwoord in een authenticatieverzoek afgewezen. |
login_rejected |
Nee | Ja | Nee | Nee | Nee | De aanmelding is afgewezen nadat de gebruikersidentifier en het wachtwoord zijn geverifieerd. Een optioneel uiErrorMessage wordt op het aanmeldformulier getoond. |
invalid_current_password |
Nee | Nee | Nee | Ja | Nee | De directory heeft het huidige wachtwoord in een verzoek om het wachtwoord te wijzigen afgewezen. |
create_user_not_supported |
Nee | Nee | Ja | Nee | Nee | De connector ondersteunt het aanmaken van gebruikers in de externe directory niet. |
operation_rejected |
Nee | Ja | Nee | Ja | Ja | De bewerking kan niet worden voltooid, bijvoorbeeld omdat het account niet beschikbaar is. FoxIDs logt errorMessage, negeert uiErrorMessage en toont een algemene gelokaliseerde fout zonder de accountstatus te wijzigen. |
user_deleted |
Met directory-ID | Nee | Nee | Nee | Nee | Een bekende directory-ID bestaat niet meer. FoxIDs trekt toegang in en verwijdert de gebruiker tijdens synchronisatie. |
password_not_accepted |
Nee | Ja | Ja | Ja | Ja | Het wachtwoord dat wordt gevalideerd, gebruikt om een gebruiker aan te maken, gewijzigd of ingesteld, is afgewezen door een wachtwoordregel in de directory waarvoor geen specifiekere code bestaat. |
password_min_length |
Nee | Ja | Ja | Ja | Ja | Het wachtwoord dat wordt gevalideerd, gebruikt om een gebruiker aan te maken, gewijzigd of ingesteld, is korter dan de minimale wachtwoordlengte van de directory. |
password_max_length |
Nee | Ja | Ja | Ja | Ja | Het wachtwoord dat wordt gevalideerd, gebruikt om een gebruiker aan te maken, gewijzigd of ingesteld, is langer dan de maximale wachtwoordlengte van de directory. |
password_banned_characters |
Nee | Ja | Ja | Ja | Ja | Het wachtwoord dat wordt gevalideerd, gebruikt om een gebruiker aan te maken, gewijzigd of ingesteld, bevat een of meer tekens of woorden die de directory afwijst. |
password_complexity |
Nee | Ja | Ja | Ja | Ja | Oudere fout voor tekencomplexiteit die FoxIDs interpreteert als password_character_variation. Gebruik voor nieuwe integraties een van de twee specifieke tekenfoutcodes. |
password_character_repeat |
Nee | Ja | Ja | Ja | Ja | Het wachtwoord dat wordt gevalideerd, gebruikt om een gebruiker aan te maken, gewijzigd of ingesteld, bevat te veel herhaling van tekens. |
password_character_variation |
Nee | Ja | Ja | Ja | Ja | Het wachtwoord dat wordt gevalideerd, gebruikt om een gebruiker aan te maken, gewijzigd of ingesteld, bevat onvoldoende variatie in tekens. |
password_email_text_complexity |
Nee | Ja | Ja | Ja | Ja | Het wachtwoord dat wordt gevalideerd, gebruikt om een gebruiker aan te maken, gewijzigd of ingesteld, bevat het e-mailadres van de gebruiker of een deel daarvan. |
password_phone_text_complexity |
Nee | Ja | Ja | Ja | Ja | Het wachtwoord dat wordt gevalideerd, gebruikt om een gebruiker aan te maken, gewijzigd of ingesteld, bevat het telefoonnummer van de gebruiker of een deel daarvan. |
password_username_text_complexity |
Nee | Ja | Ja | Ja | Ja | Het wachtwoord dat wordt gevalideerd, gebruikt om een gebruiker aan te maken, gewijzigd of ingesteld, bevat de gebruikersnaam van de gebruiker of een deel daarvan. |
password_url_text_complexity |
Nee | Ja | Ja | Ja | Ja | Het wachtwoord dat wordt gevalideerd, gebruikt om een gebruiker aan te maken, gewijzigd of ingesteld, bevat tekst die verband houdt met de URL van FoxIDs. |
password_risk |
Nee | Ja | Ja | Ja | Ja | Het wachtwoord dat wordt gevalideerd, gebruikt om een gebruiker aan te maken, gewijzigd of ingesteld, staat bekend als riskant, gecompromitteerd of anderszins onveilig. |
password_history |
Nee | Nee | Nee | Ja | Ja | Het nieuwe wachtwoord is geweigerd omdat het eerder is gebruikt. |
password_expired |
Nee | Ja | Nee | Nee | Nee | Het opgegeven wachtwoord is geverifieerd maar verlopen; de gebruiker moet het wijzigen voordat authenticatie kan doorgaan. |
new_password_equals_current |
Nee | Nee | Nee | Ja | Nee | Het nieuwe wachtwoord is hetzelfde als het huidige wachtwoord. set-password kan deze fout niet retourneren omdat het endpoint het huidige wachtwoord niet ontvangt. |
Als FoxIDs vóór een wachtwoordwijziging het eigen beleid moet controleren, roept het eerst authentication aan om het huidige wachtwoord te verifiëren. Retourneert de connector daarbij password_expired, dan kan de wijziging doorgaan. Het endpoint change-password moet zelf een geverifieerd verlopen huidig wachtwoord accepteren en alleen fouten retourneren die de wijzigingsbewerking ondersteunt.
Bij fouten in het wachtwoordbeleid gebruikt FoxIDs het wachtwoordbeleid van de omgeving om de gebruikersgerichte foutmelding weer te geven. Zie Wachtwoordbeleid en foutmeldingen.
Retourneer uitsluitend foutcodes die volgens bovenstaande tabel worden ondersteund voor het endpoint en de opgegeven directoryUserId. Een niet-ondersteunde code, ongeldig antwoord of onverwachte HTTP-status is een integratiefout en leidt naar de algemene foutpagina. Zie Browserfouten oplossen om diagnostische details te vinden met de identificaties op de foutpagina.
Authenticatiefouten en privacy van gebruikers
Een niet-geauthenticeerde aanroeper mag niet uit een aanmeldfout kunnen afleiden of een gebruikersnaam of e-mailadres bestaat. Bij wachtwoordauthenticatie handelt FoxIDs de ondersteunde fouten als volgt af:
| Connectorfout | Resultaat voor de gebruiker |
|---|---|
invalid_password, operation_rejected of een account dat tijdens synchronisatie niet beschikbaar blijkt |
Hetzelfde algemene aanmeldbericht, bijvoorbeeld Verkeerde e-mail of wachtwoord., vertaald naar de actieve taal en aangepast aan de ingeschakelde aanmeldidentifiers. |
login_rejected |
Het opgegeven uiErrorMessage, of hetzelfde algemene aanmeldbericht als het ontbreekt of leeg is, op dezelfde plaats op het aanmeldformulier. |
password_not_accepted |
De pagina voor het wijzigen van het wachtwoord met algemene uitleg over het wachtwoordbeleid. |
password_expired of een andere specifieke fout in het wachtwoordbeleid |
De pagina voor het wijzigen van het wachtwoord met de bijbehorende gelokaliseerde uitleg over het wachtwoordbeleid. |
De connector moet het opgegeven huidige wachtwoord verifiëren voordat deze een fout in het wachtwoordbeleid retourneert vanuit authentication. Anders kan een andere pagina of melding een aanvaller in staat stellen gebruikers te ontdekken en hun identifiers te bevestigen door gebruikersnamen of e-mailadressen te raden. Verifieer bij change-password het huidige wachtwoord voordat u accountspecifieke uitleg over het nieuwe wachtwoord retourneert. Algemene formaatcontroles mogen niet onthullen of een account bestaat.
Als een gebruiker om welke reden dan ook niet via deze flow mag aanmelden, valideer dan eerst de opgegeven gebruikersidentificatie en het wachtwoord. Weiger op basis van de beperking pas nadat beide zijn geverifieerd, zodat de beperking niet onthult of een geraden identificatie bij een echte gebruiker hoort. Retourneer login_rejected vanuit authentication, zet de diagnostische reden in errorMessage en geef eventueel veilige gebruikersinformatie in uiErrorMessage. Kunnen de gegevens niet worden geverifieerd, retourneer dan de normale authenticatiefout zonder de beperking bekend te maken.
FoxIDs vertrouwt erop dat de connector de aanmeldgegevens verifieert vóór login_rejected; een succesvolle accountzoekopdracht of kennis van directoryUserId is onvoldoende. Toon instructies of knoppen voor alternatieve aanmeldmethoden vóór verificatie onafhankelijk van het bestaan van een account bij de ingevoerde identificatie.
Alleen synchronise-user rapporteert accountstatus: retourneer volledige gegevens met disableAccount: true voor een uitgeschakeld account, of foutcode user_deleted als een bekende directory-ID niet meer bestaat. Wachtwoordendpoints retourneren operation_rejected als het account niet beschikbaar is. Anders dan login_rejected vereist deze fout geen geverifieerd wachtwoord, omdat deze nooit accountspecifieke informatie aan de browser verstrekt.
Handel fouten voor bekende en onbekende identifiers op dezelfde manier af, inclusief waarneembare responstijden en bescherming tegen herhaalde pogingen. Een algemeen bericht alleen voorkomt niet dat gebruikers worden ontdekt als een andere omleiding, status of responstijd het resultaat onthult. Volg bij het implementeren van de connector de richtlijnen van OWASP voor authenticatiefouten.
API-voorbeeld
Het voorbeeld DirectoryConnectorApiSample laat zien hoe u de Directory Connector API implementeert in ASP.NET Core.
Implementaties en testclients moeten de bovenstaande contracten volgen: HTTP 200 met volledige gebruikersgegevens voor synchronise-user, HTTP 200 met de aangemaakte directory-ID voor create-user en HTTP 204 zonder inhoud voor succesvolle wachtwoordbewerkingen.
Active Directory-component
FoxIDs bevat een op IIS te implementeren Directory Connector voor Active Directory. De component implementeert de Directory Connector API voor één AD/LDAP-domein en kan accounts synchroniseren, wachtwoorden valideren, wijzigen en instellen, en geconfigureerde AD-attributen en geneste AD-groepslidmaatschappen als claims retourneren.
Configureren
Configureer Directory Connector in de omgevingsinstellingen in FoxIDs Control Client.
- Selecteer het tabblad Instellingen.
- Selecteer het tabblad Omgeving.
- Zoek de sectie Directory Connector.
- Schakel Directory Connector in.
- Voeg de basis-API-URL zonder de endpointmap toe in API URL.
- Voeg het API secret toe.
- Bepaal of er een lokale wachtwoordkopie moet worden opgeslagen.
- Configureer het wachtwoordbeleid van de omgeving zodat dit overeenkomt met het wachtwoordbeleid van de externe directory.
- Klik op Update.
