Twee-factor en multi-factor authenticatie (2FA/MFA)

FoxIDs ondersteunt zowel een eenvoudige twee-factor modus als een geavanceerde multi-factor modus in de login-authenticatiemethode.

  • Twee-factor modus: Advanced multi-factor is uitgeschakeld (standaard).
  • Multi-factor modus: Advanced multi-factor is ingeschakeld.

Gebruik de twee-factor modus wanneer één extra factor voldoende is. Gebruik de multi-factor modus wanneer u een geordende MFA-keten nodig hebt of authenticatiemethoden als MFA-stappen wilt gebruiken.

Concepten

Twee-factor authenticatie (2FA) en multi-factor authenticatie (MFA) voegen beide een of meer verificatiestappen toe na de primaire aanmelding.

  • 2FA: een primaire aanmelding plus één extra factor.
  • MFA: een primaire aanmelding plus één of meer geordende extra factoren.

Ondersteunde factoren

FoxIDs ondersteunt ingebouwde factoren en authenticatiemethoden als MFA-items.

Factor Type AMR-waarde
SMS-code Ingebouwd sms
E-mailcode Ingebouwd email
Authenticator app-code Ingebouwd otp
Recovery code Ingebouwd (authenticator app) otp
Authenticatiemethode (OIDC, SAML 2.0, TrackLink) Configureerbaar item Geconfigureerde AMR of methode-/profielnaam als het veld leeg is

U kunt elke compatibele authenticator app gebruiken, bijvoorbeeld Google Authenticator, Microsoft Authenticator, Authy en andere TOTP-apps.

Wanneer MFA vereist is

MFA wordt geactiveerd wanneer een van de volgende situaties geldt:

  • De gebruiker heeft Require multi-factor (2FA/MFA) ingeschakeld.
  • De login-authenticatiemethode heeft Require multi-factor (2FA/MFA) ingeschakeld.
  • De aanroepende applicatie vraagt MFA aan met ACR urn:foxids:mfa.

MFA-vereisten gelden in beide modi. Als Advanced multi-factor is uitgeschakeld, wordt aan de vereiste voldaan door de eenvoudige twee-factor flow.

Als specifieke ACR-waarden samen met urn:foxids:mfa worden aangevraagd, zijn alleen de overeenkomende ACR-waarden vereist.

Twee-factor modus (Advanced multi-factor is uitgeschakeld)

In deze modus worden ingebouwde twee-factor opties direct geconfigureerd:

  • Authenticator app
  • SMS
  • E-mail

Zo configureert u de twee-factor modus:

  1. Open het tabblad Authentication.
  2. Klik op de login-authenticatiemethode Login om deze te bewerken.
  3. Klik op Show advanced.
  4. Ga naar de sectie Multi-factor.
  5. Laat Advanced multi-factor uitgeschakeld en configureer de opties voor Authenticator app, SMS en E-mail.

De naam van de authenticator app die aan gebruikers wordt getoond kan worden geconfigureerd. Standaard wordt de tenantnaam gebruikt.

Configure simple two-factor options in login authentication method

SMS- en e-mailfactoren vereisen contactinformatie van de gebruiker. Dit kan worden aangeleverd als gebruikersidentificatoren of als claims (phone_number en email).

Selectie van het twee-factor type

In de twee-factor modus geeft FoxIDs de voorkeur aan een reeds geregistreerde authenticator app. Als geen authenticator app is geregistreerd, heeft SMS voorrang op e-mail wanneer beide beschikbaar zijn.

SMS twee-factor ingeschakeld en gebruiker heeft telefoonnummer E-mail twee-factor ingeschakeld en gebruiker heeft e-mail Gebruiker heeft een authenticator app geregistreerd Mogelijke twee-factor typen Geselecteerd twee-factor type
false false false Instellen van authenticator app Instellen van authenticator app
false false true Authenticator app Authenticator app
true false false SMS met optionele configuratie van authenticator app na SMS-verificatie SMS
true false true SMS en authenticator app Authenticator app
false true false E-mail met optionele configuratie van authenticator app na e-mailverificatie E-mail
false true true E-mail en authenticator app Authenticator app
true true false SMS en e-mail met optionele configuratie van authenticator app na SMS- of e-mailverificatie SMS
true true true SMS, e-mail en authenticator app Authenticator app

Een API informeren wanneer een authenticator app wordt geregistreerd

De login-authenticatiemethode kan je backend onmiddellijk informeren nadat een gebruiker een nieuwe authenticator app heeft geregistreerd. De melding is optioneel en geldt alleen voor nieuwe registraties, niet voor latere aanmeldingen met de authenticator app.

De melding configureren:

  1. Open het tabblad Authentication.
  2. Klik op de authenticatiemethode Login om deze te bewerken.
  3. Klik op Show advanced.
  4. Ga naar de sectie Multi-factor.
  5. Schakel in de twee-factor modus Notify an API when an authenticator app is registered in onder de ingebouwde factoropties. Schakel dit in de geavanceerde multi-factor modus in binnen het MFA-item Authenticator app.
  6. Configureer de basis-URL en het API-secret.

FoxIDs slaat de registratie van de authenticator app lokaal op voordat de API wordt aangeroepen en schrijft de trace Authenticator app registration saved locally; external notification pending. De API wordt vervolgens synchroon aangeroepen. De aanmelding gaat alleen verder als de API HTTP-status 200 OK retourneert. Als de aanroep mislukt of een andere status retourneert, verwijdert FoxIDs de nieuwe registratie en toont het de foutpagina. Bestaande registraties worden niet gewijzigd.

De geslaagde registratie wordt naar het auditlog geschreven nadat de API 200 OK heeft geretourneerd. Als de melding is uitgeschakeld, wordt de audit onmiddellijk geschreven nadat de lokale registratie is opgeslagen.

Request naar de meldings-API

Als de geconfigureerde basis-URL https://backend.example/authenticator is, stuurt FoxIDs een HTTP POST-request naar:

https://backend.example/authenticator/notification

FoxIDs Cloud roept je API aan vanaf IP 57.128.60.142.

IP-adres(sen) kunnen veranderen of worden uitgebreid.

De request gebruikt HTTP Basic authentication:

  • Gebruikersnaam: authenticator_app
  • Wachtwoord: het geconfigureerde API-secret

De JSON-request bevat:

{
  "type": "registered",
  "registration_id": "7a772286-76a2-4f17-a0f8-4e927bb1772d",
  "user_id": "e061ed17-7b44-48a8-b224-ecdb800ed5cc",
  "email": "user@example.com",
  "phone": "+4512345678",
  "username": "user@example.com"
}

type identificeert de melding. Het ondersteunde type registered betekent dat een nieuwe authenticator app is geregistreerd. registration_id is de permanente unieke ID van de nieuwe registratie. Je API kan deze als idempotentiesleutel gebruiken. user_id is de stabiele technische FoxIDs-gebruikers-ID. email, phone en username worden opgenomen wanneer ze een waarde hebben. Het secret en de herstelcode van de authenticator app worden nooit verzonden.

De API moet de melding accepteren en 200 OK retourneren zodra het vereiste synchrone werk is voltooid. Verdere wachtrijverwerking of distributie naar andere deployments is de verantwoordelijkheid van de backend.

Authenticator-appregistraties beheren

Beheerders kunnen de authenticator-appregistraties van een gebruiker weergeven en afzonderlijk verwijderen onder Internal Users → gebruiker bewerken → Advanced → Two-factor. Registraties worden geïdentificeerd door hun permanente registratie-ID en, voor nieuwe registraties, hun registratietijd. Tijdens de registratie wordt de gebruiker niet om een weergavenaam gevraagd.

Zie Control API - gebruikers en authenticator-apps om registraties via Control API te lijsten, lezen, maken, bijwerken, verwijderen of synchroniseren. Deze handleiding documenteert de endpoints, request-resource, beveiligingsoverwegingen, foutresponses en notification-gedrag op één plaats.

Multi-factor modus (Advanced multi-factor is ingeschakeld)

Wanneer Advanced multi-factor is ingeschakeld, wordt MFA geconfigureerd als een geordende lijst van maximaal 5 MFA-items.

Er kan slechts één Authenticator app MFA-item worden geconfigureerd. Een gebruiker kan voor dat item maximaal vijf registraties van authenticator apps hebben. Alle registraties zijn alternatieven om hetzelfde MFA-item te voltooien: FoxIDs controleert de ingediende code aan de hand van de geregistreerde authenticator apps en accepteert de eerste overeenkomst. De registratieprompt tijdens het aanmelden maakt alleen een registratie aan wanneer de gebruiker er nog geen heeft; er wordt geen extra registratie toegevoegd wanneer er al een bestaat. De naam van de authenticator app en de optionele API voor registratiemeldingen worden geconfigureerd binnen het Authenticator app MFA-item.

Zo configureert u de multi-factor modus:

  1. Open het tabblad Authentication.
  2. Klik op de login-authenticatiemethode Login om deze te bewerken.
  3. Klik op Show advanced.
  4. Ga naar de sectie Multi-factor.
  5. Schakel Advanced multi-factor in en configureer de geordende MFA-items.

Ondersteunde MFA-itemtypen:

Configuratieregels:

  • Ingebouwde itemtypen kunnen elk slechts één keer worden geconfigureerd.
  • Items van het type authenticatiemethode kunnen meerdere keren worden geconfigureerd, bijvoorbeeld met verschillende profielen.
  • Items worden in lijstvolgorde uitgevoerd.
  • U kunt items toevoegen, verwijderen en opnieuw ordenen.

Configure advanced multi-factor item list with add/remove/reorder

AMR- en ACR-gedrag van MFA-items

Elk voltooid MFA-item draagt AMR-claimwaarden bij aan de sessie.

  • Ingebouwde AMR-waarden zijn vast:
    • SMS: sms
    • E-mail: email
    • Authenticator app en recovery code: otp
  • MFA-item van het type authenticatiemethode:
    • Er kan een optionele aangepaste AMR worden geconfigureerd.
    • Als de AMR leeg is, wordt de naam van de authenticatiemethode of profielnaam gebruikt.

Aangevraagde ACR-waarden worden met de AMR-waarden van MFA-items vergeleken in dit formaat:

  • urn:foxids:<amr>
  • Voorbeeld: urn:foxids:link

urn:foxids:mfa is de algemene MFA-vereiste en FoxIDs voegt AMR mfa toe wanneer MFA is voltooid.

Selectie en chaining van MFA-items

  • Als specifieke ACR-waarden worden aangevraagd, moet een van de overeenkomende MFA-items worden voltooid.
  • Als alleen algemene MFA wordt aangevraagd, kan elk beschikbaar geconfigureerd MFA-item aan de vereiste voldoen.
  • Als meer dan één geschikt MFA-item bestaat en FoxIDs niet automatisch kan selecteren, wordt een selectie-interface getoond.
  • Als een authenticator app is geconfigureerd en al is geregistreerd, geeft FoxIDs daaraan de voorkeur bij algemene MFA-aanvragen.
  • Als het instellen van een authenticator app wordt gekozen en deze nog niet is geregistreerd, kan de setup-flow doorgaan na een geselecteerde stap voor SMS, e-mail of authenticatiemethode.
  • Als alleen de authenticator app is geconfigureerd, kan de setup direct starten na aanmelding met de eerste factor.

MFA-pagina voor authenticatiemethode met optionele registratie van een authenticator app en de mogelijkheid om een ander MFA-item te kiezen. MFA authentication method selection page

MFA-SMS-pagina met optionele registratie van een authenticator app en de mogelijkheid om een ander MFA-item te kiezen. MFA SMS page

MFA-e-mailpagina waar de authenticator app wordt ingesteld, met de mogelijkheid om een ander MFA-item te kiezen. MFA Email page

MFA-pagina voor authenticator app met de mogelijkheid om een ander MFA-item te kiezen. MFA authenticator app page

Authenticatiemethoden gebruikt als MFA-items

Authenticatiemethoden (OIDC, SAML 2.0, TrackLink) kunnen als MFA-items worden gebruikt met de volgende regels:

  • MFA-specifieke ACR-waarden worden niet doorgestuurd naar het verzoek aan de MFA-authenticatiemethode.
  • Het antwoord van de authenticatiemethode moet de vereiste AMR-waarde bevatten voor het geselecteerde MFA-item.
  • De AMR-waarde wordt normaal gesproken toegevoegd in de claim transform als de teruggegeven identiteit overeenkomt met de verwachte identiteit. Zie het voorbeeld van claim transform.
  • Als de vereiste AMR-waarde ontbreekt, mislukt de aanmelding.
  • Na succesvolle validatie voegt FoxIDs AMR mfa toe aan de resulterende sessie.

MFA aanvragen vanuit applicaties

Applicaties kunnen MFA aanvragen in zowel OpenID Connect als SAML 2.0.

Als specifieke ACR-waarden worden aangevraagd maar niet zijn geconfigureerd op MFA-items in de geselecteerde login-authenticatiemethode, mislukt de authenticatie.

OpenID Connect

Gebruik acr_values:

  • Algemene MFA: acr_values=urn:foxids:mfa
  • Algemene MFA en specifieke methode: acr_values=urn:foxids:mfa urn:foxids:link

SAML 2.0

Gebruik RequestedAuthnContext.AuthnContextClassRef:

  • Algemene MFA: neem urn:foxids:mfa op
  • Algemene MFA en specifieke methode: neem urn:foxids:mfa en specifieke waarden zoals urn:foxids:link op

Sessiegedrag

FoxIDs valideert vereiste AMR-waarden tegen de huidige aanmeldsessie.

  • Nieuwe aanmelding: de sessie wordt gemaakt nadat aan alle vereisten is voldaan.
  • Step-up login: een bestaande sessie wordt bijgewerkt nadat aan alle extra MFA-vereisten is voldaan.
  • Hergebruik van sessie: als de sessie al voldoet aan de vereiste AMR-waarden, hergebruikt FoxIDs de sessie en wordt niet opnieuw om aanmelding gevraagd.

Probleemoplossing

Veelvoorkomende oorzaken van MFA-fouten:

  • Aangevraagde ACR-waarden zijn niet geconfigureerd als MFA-items in de login-authenticatiemethode.
  • Een authenticatiemethode die als MFA wordt gebruikt retourneert niet de vereiste AMR-waarde.
  • Er is momenteel geen geconfigureerd MFA-item beschikbaar voor de gebruiker, bijvoorbeeld omdat telefoon- of e-mailgegevens ontbreken voor SMS of e-mail.