External Login - API

Med external login kan du autentisera användare i en befintlig användardatabas via ett API-anrop. Du implementerar API:et; FoxIDs anropar det med användarnamn och lösenord, och API:et validerar kombinationen och returnerar framgång eller fel. Använd en External login autentiseringsmetod när du vill använda en befintlig user store som autentiseringskälla i FoxIDs. Efter lyckad login kan du skapa external users och valfritt visa en dialog för att samla in t.ex. namn eller e-post.

Om du vill att användare ska förbli interna användare i FoxIDs-miljön medan lösenordsautentisering och lösenordets livscykel delegeras till en extern katalog, använd Directory Connector i stället.

Med tiden kan du migrera användare till FoxIDs och fasa ut den externa API:n och user store.

För en översikt över användarkoncept (internal users, external users och external user stores) se users overview.

External login stöder två user identifier (username) typer:

  • Email - användarens e-post
  • Text - ett fritext-användarnamn

Om du väljer text-typen valideras formatet inte i FoxIDs (blandade format är tillåtna inklusive e-post). Home realm discovery (HRD) baserat på domän är endast tillgängligt med email-typen.

Default external login UI med ett textbaserat användarnamn: External login UI

UI:n kan anpassas.

Implementera API

Du måste implementera ett enkelt API som FoxIDs anropar för varje autentiseringsrequest (se sample).

API:et har en base URL; funktionalitet är grupperad i mappar. För närvarande stöds endast authentication-mappen (validera användarnamn/lösenord). Mappar för password change och user creation kan läggas till senare.

Om base URL är https://somewhere.org/mystore, är authentication endpoint: https://somewhere.org/mystore/authentication

FoxIDs Cloud anropar ditt API från IP 57.128.60.142. IP(s) kan ändras eller utökas.

Request

Säkrad med HTTP Basic auth: användarnamn external_login, lösenord = konfigurerat secret.

Anropet är HTTP POST med en JSON body.

Du kan konfigurera ytterligare parametrar; de inkluderas i 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 koder:

  • email = 100
  • text = 200

Response

Success Vid framgång ska API:et returnera HTTP code 200 och valfritt en lista med claims för den autentiserade 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.

Till exempel användarens sub (unik ID / användarnamn), namn, e-post och kanske en roll:

{
  "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 API:et måste returnera HTTP code 401 (Unauthorized) och en error (krävs) om Basic auth avvisas. Lägg valfritt till en felbeskrivning i ErrorMessage.

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

API:et måste returnera HTTP code 400, 401 eller 403 och en error (krävs) om kombinationen av användarnamn och lösenord avvisas. Lägg valfritt till en felbeskrivning i ErrorMessage.

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

Om andra fel uppstår ska API:et returnera HTTP code 500 eller annan lämplig felkod. Det rekommenderas att lägga till ett tekniskt felmeddelande ErrorMessage för diagnostik (loggas bara; visas aldrig för slutanvändaren).

API Sample

Sample ExternalLoginApiSample visar hur du implementerar API:et i ASP.NET Core.

Postman collection external-login-api.postman_collection.json för att anropa och testa ditt API med Postman.

Configure

Konfigurera en extern API login autentiseringsmetod i FoxIDs Control Client.

  1. Navigera till fliken Authentication
  2. Klicka New authentication
  3. Välj Show advanced
  4. Välj External API Login
  5. Lägg till Name
  6. Välj Username type (t.ex. Text)
  7. Lägg till base API URL utan authentication-mappen i API URL
  8. Lägg till API secret Configure an external login authentication method
  9. Klicka Create

Valfritt klicka Show advanced uppe till höger i konfigurationssektionen för att anpassa login UI:n.