External Login - API

Med external login kan du autentificere brugere i en eksisterende brugerdatabase via et API-kald. Du implementerer API'et; FoxIDs kalder det med brugernavn og adgangskode, og API'et validerer kombinationen og returnerer succes eller fejl. Brug en External login autentificeringsmetode, når du vil bruge en eksisterende brugerstore som autentificeringskilde i FoxIDs. Efter succesfuldt login kan du oprette external users og valgfrit vise en dialog til at indsamle f.eks. navn eller e-mail.

Over tid kan du migrere brugere til FoxIDs og udfase den eksterne API og brugerstore.

For et overblik over brugerbegreber (internal users, external users og external user stores) se users overview.

External login understøtter to user identifier (username) typer:

• Email - brugerens e-mail
• Text - en fri tekst brugernavn

Hvis du vælger text-typen, valideres formatet ikke i FoxIDs (blandede formater er tilladt, inklusive e-mails). Home realm discovery (HRD) baseret på domæne er kun tilgængelig med email-typen.

Default external login UI med et tekstbaseret brugernavn:

UI'et kan tilpasses.

Implementer API

Du skal implementere et simpelt API som FoxIDs kalder for hver autentificeringsrequest (se sample).

API'et har en base URL; funktionaliteten er grupperet i mapper. I øjeblikket understøttes kun authentication mappen (valider brugernavn/adgangskode). Mapper til password change og user creation kan tilføjes senere.

Hvis base URL er https://somewhere.org/mystore, er authentication endpointet: https://somewhere.org/mystore/authentication

FoxIDs Cloud kalder dit API fra IP 57.128.60.142. IP(s) kan ændres eller udvides.

Request

Sikret med HTTP Basic auth: brugernavn external_login, adgangskode = konfigureret secret.

Kaldet er HTTP POST med en JSON body.

Du kan konfigurere yderligere parametre; de inkluderes 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 Ved succes skal API'et returnere HTTP code 200 og valgfrit en liste af claims for den autentificerede bruger.

For eksempel brugerens sub (unik ID / brugernavn), navn, e-mail og evt. en rolle:

{
  "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 skal returnere HTTP code 401 (Unauthorized) og en error (påkrævet) hvis Basic auth afvises. Tilføj valgfrit en fejlbeskrivelse i ErrorMessage.

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

API'et skal returnere HTTP code 400, 401 eller 403 og en error (påkrævet) hvis kombinationen af brugernavn og adgangskode afvises. Tilføj valgfrit en fejlbeskrivelse i ErrorMessage.

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

Hvis andre fejl opstår, skal API'et returnere HTTP code 500 eller en anden passende fejlcode. Det anbefales at tilføje en teknisk fejlmeddelelse ErrorMessage til diagnosticering (den logges kun; vises aldrig til slutbrugeren).

API Sample

Sample ExternalLoginApiSample viser hvordan man implementerer API'et i ASP.NET Core.

Postman collection external-login-api.postman_collection.json til at kalde og teste dit API med Postman.

Configure

Konfigurer en ekstern API login autentificeringsmetode i FoxIDs Control Client.

1. Naviger til fanen Authentication
2. Klik New authentication
3. Vælg Show advanced
4. Vælg External API Login
5. Tilføj Name
6. Vælg Username type (f.eks. Text)
7. Tilføj base API URL uden authentication mappen i API URL
8. Tilføj API secret
9. Klik Create

Valgfrit klik Show advanced i øverste højre hjørne af konfigurationssektionen for at tilpasse login UI'et.