External Login - API

Met external login kun je gebruikers authenticeren in een bestaande gebruikersdatabase via een API-call. Jij implementeert de API; FoxIDs roept deze aan met een gebruikersnaam en wachtwoord, en de API valideert de combinatie en retourneert succes of fout. Gebruik een External login authenticatiemethode wanneer je een bestaande user store wilt gebruiken als authenticatiebron in FoxIDs. Na een succesvolle login kun je external users aanmaken en optioneel een dialoog tonen om bijvoorbeeld naam of e-mail vast te leggen.

In de loop van de tijd kun je gebruikers naar FoxIDs migreren en de externe API en user store uitfaseren.

Voor een overzicht van gebruikersconcepten (internal users, external users en external user stores) zie users overview.

External login ondersteunt twee user identifier (username) types:

• Email - de e-mail van de gebruiker
• Text - een vrije tekst gebruikersnaam

Als je het teksttype kiest, wordt het formaat niet gevalideerd in FoxIDs (gemengde formaten zijn toegestaan, inclusief e-mails). Home realm discovery (HRD) op basis van domein is alleen beschikbaar met het email-type.

Default external login UI met een tekstgebaseerde gebruikersnaam:

De UI kan worden aangepast.

API implementeren

Je moet een eenvoudige API implementeren die FoxIDs aanroept voor elke authenticatieaanvraag (zie sample).

De API heeft een base URL; functionaliteit is gegroepeerd in mappen. Momenteel wordt alleen de authentication map (gebruikersnaam/wachtwoord valideren) ondersteund. Mappen voor password change en user creation kunnen later worden toegevoegd.

Als de base URL https://somewhere.org/mystore is, is de authentication endpoint: https://somewhere.org/mystore/authentication

FoxIDs Cloud roept je API aan vanaf IP 57.128.60.142. IP(s) kunnen wijzigen of worden uitgebreid.

Request

Beveiligd met HTTP Basic auth: gebruikersnaam external_login, wachtwoord = geconfigureerde secret.

De call is HTTP POST met een JSON body.

Je kunt extra parameters configureren; ze worden opgenomen in de JSON payload.

Email type request:

{
  "usernameType": 100,
  "username": "user1@somewhere.org",
  "password": "testpass1"
}

Text username type request:

{
  "usernameType": 200,
  "username": "user1",
  "password": "testpass1"
}

Username type codes:

• email = 100
• text = 200

Response

Success Bij succes moet de API HTTP code 200 retourneren en optioneel een lijst met claims voor de geauthenticeerde gebruiker.

Bijvoorbeeld de sub van de gebruiker (unieke ID / gebruikersnaam), naam, e-mail en eventueel een rol:

{
  "claims": [
    { "type": "sub", "value": "somewhere/user2" },
    { "type": "given_name", "value": "Joe" },
    { "type": "family_name", "value": "Smith" },
    { "type": "email", "value": "user2@somewhere.org" },
    { "type": "role", "value": "some_access" }
  ]
}

Error De API moet HTTP code 401 (Unauthorized) retourneren en een error (vereist) als Basic auth wordt afgewezen. Voeg optioneel een foutbeschrijving toe in ErrorMessage.

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

De API moet HTTP code 400, 401 of 403 retourneren en een error (vereist) als de combinatie van gebruikersnaam en wachtwoord wordt afgewezen. Voeg optioneel een foutbeschrijving toe in ErrorMessage.

{
  "error": "invalid_username_password",
  "ErrorMessage": "Invalid username or password."
}

Als er andere fouten optreden, moet de API HTTP code 500 of een andere geschikte foutcode retourneren. Het wordt aanbevolen om een technische foutmelding ErrorMessage toe te voegen voor diagnose (alleen gelogd; nooit aan de eindgebruiker getoond).

API Sample

De sample ExternalLoginApiSample laat zien hoe je de API implementeert in ASP.NET Core.

Postman collection external-login-api.postman_collection.json om je API aan te roepen en te testen met Postman.

Configure

Configureer een externe API login authenticatiemethode in FoxIDs Control Client.

1. Navigeer naar het tabblad Authentication
2. Klik New authentication
3. Selecteer Show advanced
4. Selecteer External API Login
5. Voeg Name toe
6. Selecteer Username type (bijv. Text)
7. Voeg de base API URL zonder de authentication map toe in API URL
8. Voeg de API secret toe
9. Klik Create

Optioneel klik Show advanced rechtsboven in de configuratiesectie om de login UI te aan te passen.