Claim transforms og claim tasks

Hver FoxIDs autentificeringsmetode og applikationsregistrering håndterer claims og understøtter claim transforms og claim tasks. Det betyder at flere sæt af claim transforms og claim tasks kan udføres for hver brugerautentificering. Først udføres claim transforms og claim tasks på autentificeringsmetoden, og derefter på applikationsregistreringen.

Yderligere delmængder af claim transforms og claim tasks kan udføres hvis en bruger eller en ekstern bruger oprettes.

Claim transform flow diagram

Hvis du opretter en ny claim med en first level claim transform eller claim task, er claimen lokal for autentificeringsmetoden, undtagen for en Login autentificeringsmetode. I en autentificeringsmetode sendes claimen videre hvis claim typen er tilføjet til listen Forward claims, eller hvis * (standard) er inkluderet i listen.

Hvis du opretter en ny claim med en claim transform eller claim task, er claimen lokal for applikationsregistreringen. I en applikationsregistrering skal du tilføje claimen eller * til listen Issue claims. Alternativt, for OpenID Connect, tilføj claimen til et scopes Voluntary claims liste og anmod om scopet fra din applikation.

Se venligst claim transform eksempler.

Aktiver Log claim trace i log settings for at se claims før og efter transformation i logs.

Claim transforms kan konfigureres i en login autentificeringsmetode.

FoxIDs authentication method claim transform

Og claim tasks.

FoxIDs authentication method claim task

På samme måde kan claim transforms og claim tasks konfigureres som first level og second level i en OpenID Connect autentificeringsmetode.

FoxIDs application registration claim transform

Claims repræsenteres som standard som JWT claims. Hvis autentificeringsmetoden er SAML 2.0, repræsenteres first level claims som SAML 2.0 claims. Hvis applikationsregistreringen er SAML 2.0, repræsenteres claims som SAML 2.0 claims.

En claim transform og claim task vil udføre en af op til syv forskellige handlinger afhængigt af typen.

Claim transform og claim task handlinger:

  • Add claim - tilføj en ny claim
  • Add claim, if not match - udfør add handlingen hvis betingelsen ikke matcher
  • Replace claim - tilføj en ny claim og fjern eksisterende claims hvis en eller flere findes
  • Replace claim, if not match - udfør replace handlingen hvis betingelsen ikke matcher
  • Remove claim - fjern claims hvis en eller flere findes
  • If match - udfør handlingen hvis betingelsen matcher
  • If not match - udfør handlingen hvis betingelsen ikke matcher

Claim transforms og claim tasks udføres i rækkefølge, og handlingerne udføres derfor i rækkefølge. Det betyder at det er muligt at oprette en lokal variabel ved at tilføje en claim og senere i sekvensen træffe beslutninger baseret på claimen. En claim er lokal i claim transforms og claim tasks sættet hvis den starter med _local:.

Når claim transforms og claim tasks kører i et login flow, tilføjer FoxIDs automatisk lokale claims fra login requesten før transformationerne udføres. Disse _local: claims er beregnet til beslutninger i transform task sekvensen og fjernes fra outputtet.

Lokale claims tilføjet i AddLocalClaims:

  • _local:login_action - login request action, gemt som camelCase
  • _local:user_id - login request user ID (kun hvis angivet)
  • _local:max_age - login request max age (kun hvis sat og større end 0)
  • _local:login_hint - login request hint (kun hvis angivet)
  • _local:acr - login request ACR værdier som en space delimited liste (kun hvis angivet)

Med Add claim, if not match handlingen er det muligt at tilføje en claim (lokal variabel) hvis en anden claim eller en claim værdi ikke findes.

Claim transform typer der understøtter alle handlinger:

  • Match claim - kontrollerer om den valgte claim type findes. Ved add- og replace-handlinger skrives den outgoing claim med den nye værdi, når claimen findes. if not match-handlinger kører, når claimen mangler. En remove-handling fjerner den valgte outgoing claim, når claimen findes.
  • Match claim and value - kontrollerer om den valgte claim type findes med den konfigurerede værdi. Ved add- og replace-handlinger skrives den outgoing claim med den nye værdi, når både claim type og værdi matcher. if not match-handlinger kører, når claimen findes, men værdien ikke matcher. En remove-handling fjerner den valgte outgoing claim, når både claim type og værdi matcher.
  • Regex match - kontrollerer om den valgte claim type findes, og om claim værdien matcher det konfigurerede regulære udtryk. Ved add- og replace-handlinger skrives den outgoing claim med den nye værdi, når det regulære udtryk matcher. if not match-handlinger kører, når claimen findes, men værdien ikke matcher det regulære udtryk. En remove-handling fjerner den valgte outgoing claim, når det regulære udtryk matcher.

Claim transform typer der understøtter Add claim, Replace claim og Add claim, if new claim does not exist handlinger:

  • Map - kopierer den valgte claim værdi til den outgoing claim. Med Add claim, if new claim does not exist skrives værdien kun, hvis den outgoing claim ikke allerede findes.
  • Regex map - udtrækker den navngivne regex gruppe map fra den valgte claim værdi og skriver den udtrukne værdi til den outgoing claim. Med Add claim, if new claim does not exist skrives værdien kun, hvis den outgoing claim ikke allerede findes.

Claim transform typer der understøtter Add claim og Replace claim handlinger:

  • Constant - skriver altid den konfigurerede konstante værdi til den outgoing claim.
  • Concatenate - bygger den outgoing claim ud fra værdier i de valgte claims. Formatstrengen bruger pladsholdere som {0}, {1} og {2} for de valgte claim værdier i rækkefølge.
  • External claims API - sender valgte claims til et eksternt API. Claims returneret af API'et tilføjes til eller erstatter outgoing claims.
  • DK XML privilege to JSON - konverterer en DK privilege XML claim til JSON claims, én claim for hvert PrivilegeGroup XML element.

Claim task typer der understøtter Add claim og Replace claim handlinger:

  • Query internal user - bruger lookup claim værdien til at finde én intern bruger og tilføjer eller erstatter derefter valgte claims fra den interne bruger i det aktuelle claim set.
  • Query external user - bruger lookup claim værdien til at finde én ekstern bruger og tilføjer eller erstatter derefter valgte claims fra den eksterne bruger i det aktuelle claim set.
  • Save claim on internal user - bruger lookup claim værdien til at finde én intern bruger og tilføjer eller erstatter derefter den valgte claim på den interne bruger med værdier fra den valgte update value claim i det aktuelle claim set.
  • Save claim on external user - bruger lookup claim værdien til at finde én ekstern bruger og tilføjer eller erstatter derefter den valgte claim på den eksterne bruger med værdier fra den valgte update value claim i det aktuelle claim set.

Ved Query internal user og Save claim on internal user læses lookup claimen fra det aktuelle claim set. Værdien i Lookup claim on internal user bestemmer, hvordan den interne bruger matches:

  • sub matcher den interne brugers user ID.
  • email, phone_number og preferred_username søger først i den interne brugers identifiers med case-insensitive matching, hvor store og små bogstaver er relevante. Hvis der ikke findes en bruger via identifier, fortsætter opslaget i brugerens gemte claims.
  • Søgningen fortsætter derefter i den interne brugers gemte claims efter samme claim type og en case-insensitive matchende værdi. Det gælder alle lookup claim typer, hvis der ikke først blev fundet en bruger.

Hvis søgningen finder præcist én intern bruger, tilføjer eller erstatter Query internal user valgte claims fra den bruger i det aktuelle claim set. Save claim on internal user tilføjer eller erstatter den valgte claim på brugeren med værdier fra den valgte update value claim. Hvis der ikke findes en bruger, eller hvis der findes mere end én bruger via claims, tilføjes eller gemmes der ingen interne brugerclaims.

Ved Query external user og Save claim on external user læses lookup claimen fra det aktuelle claim set og matches mod den valgte eksterne brugerkilde. Brug link_claim som lookup claim på den eksterne bruger for at matche på den eksterne brugers link claim værdi.

Claim task typer der understøtter If match og If not match handlinger:

  • Match claim and return error - returnerer en fejl, hvis claim typen matcher eller ikke matcher.
  • Match claim and value and return error - returnerer en fejl, hvis claim typen og claim værdien matcher eller ikke matcher.
  • Regex match and return error - returnerer en fejl, hvis claim typen og claim værdien matcher eller ikke matcher det regulære udtryk.
  • Match claim and log event - skriver den valgte claim værdi til loggen, hvis claim typen matcher.
  • Match claim and start authentication - starter et nyt login flow ved at initiere en autentificeringsmetode, hvis claim typen matcher eller ikke matcher.
  • Match claim and value and start authentication - starter et nyt login flow ved at initiere en autentificeringsmetode, hvis claim typen og claim værdien matcher eller ikke matcher.
  • Regex match and start authentication - starter et nyt login flow ved at initiere en autentificeringsmetode, hvis claim typen og claim værdien matcher eller ikke matcher det regulære udtryk.

For return error tasks konfigureres protokolfejlen, der returneres til client eller requester. OpenID Connect- og OAuth 2.0-konfigurationer returnerer en error og eventuelt en error description. SAML 2.0-konfigurationer returnerer en SAML status code og message.

Start authentication claim tasks kan bruges til step-up, når brugeren er logget ind med én faktor og en anden faktor kræves, eller hvis yderligere information (claims) er nødvendig.

External claims - API

Du kan kalde dit eget API fra FoxIDs med en claim transformation. API'et kaldes med claims og claims returneret fra API'et kan tilføjes med en add eller replace handling. API'et kaldes kun hvis mindst en valgt claim eksisterer. Du kan bruge * til at vælge og sende alle claims til dit API.

Use case scenarier:

  • Kald dit API fra en autentificeringsmetode hver gang en bruger autentificeres enten i FoxIDs eller hos en ekstern identity provider. Du kan derefter finde brugeren i din database og returnere et user ID og måske et customer ID eller hvad der er relevant. Du kan også oprette brugeren i din database.
  • Kald dit API fra en applikationsregistrering med bruger ID'et (sub) og forespørg brugerens roller i din database. Dit API returnerer enten en tom liste eller en liste af role claims eller måske en mere kompleks rettighedsstruktur.

Implementer API

Du skal implementere et simpelt API som FoxIDs kalder når claim transformationen udføres. Se venligst sample code.

API'et har en base URL, og funktionaliteten er opdelt i mapper. I øjeblikket understøttes kun claims mappen (funktionalitet) for at anmode om en liste af claims.

Hvis base URL for API'et er https://somewhere.org/myclaimsstore vil URL'en for claims mappen være https://somewhere.org/myclaimsstore/claims.

FoxIDs Cloud kalder dit API fra IP adressen 57.128.60.142. Den udgående IP adresse kan ændres og flere kan tilføjes over tid.

Request

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

API'et kaldes med HTTP POST og en JSON body.

Dette er en request JSON body med to input claims:

{
  "claims": [
    { "type": "sub", "value": "1b1ac05e-5937-4939-a49c-0e84a89662df" },
    { "type": "email", "value": "some@test.org" }
  ]
}

Response - Success

Ved success skal API'et returnere HTTP code 200 og en liste af claims (listen kan være tom).

For eksempel brugerens sub (user ID / username), customer ID og roller:

{
    "claims": [
        { "type": "sub", "value": "somewhere/external-some@test.org" },
        { "type": "customer_id", "value": "1234abcd" },
        { "type": "role", "value": "admin_access" },
        { "type": "role", "value": "read_access" },
        { "type": "role", "value": "write_access" }
    ]
}

Response - Error

API'et skal returnere HTTP code 401 (Unauthorized) og en error (required) hvis Basic auth afvises. Tilføj eventuelt en fejlbeskrivelse i ErrorMessage.

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

Hvis andre fejl opstår, skal API'et returnere HTTP code 500 eller en anden passende fejlkode. Det anbefales at tilføje en teknisk fejlbeskrivelse i ErrorMessage for diagnostik (den logges kun og vises aldrig til slutbrugeren).

Fejlbeskeder returneret fra API'et i ErrorMessage vises IKKE til brugeren; de logges kun.

API Sample

Sample ExternalClaimsApiSample viser hvordan API'et implementeres i ASP.NET Core.

Du kan bruge denne Postman collection til at kalde og teste dit API med Postman.

Configure

Konfigurer FoxIDs til at kalde dit API fra en claim transformation i FoxIDs Control Client.

  1. Naviger til sektionen Claim Transform
  2. Klik Add claim transform
  3. Klik External claims API
  4. Vælg Add claim eller Replace claim
  5. Tilføj de valgte claims f.eks. sub i Select claims
  6. Tilføj base API URL uden claims mappen i API URL
  7. Tilføj API secret Configure an external claims API claims transformation
  8. Klik Update

Claim transform eksempler

Split name claim i to claims given_name og family_name

Transformeringen splitter værdien i name claim ved første mellemrum og tilføjer henholdsvis given_name og family_name claims, hvis de ikke allerede findes. Hvis der er mere end ét mellemrum i name claim værdien, tilføjes der ikke nye given_name og family_name claims fordi de allerede findes.

Brug to Regex map claim transformationer.

Transform name to given_name and family_name

  • Find family_name claim værdien med regex ^\S+\s(?<map>\S+)$
  • Find given_name claim værdien med regex ^(?<map>\S+)\s\S+$

Fjern standard tilføjet autentificeringsmetode navn fra sub

Autentificeringsmetode navnet tilføjes som standard til sub claim værdien som et prefix adskilt med en pipe f.eks. some-auth-method|my-external-user-id.

Du kan bruge en replace claim på sub claimen til at fjerne den standard tilføjede prefix værdi.

Transformeringen splitter værdien i sub claimen og erstatter claimen med en ny sub der kun indeholder den oprindelige ID.

Brug en Regex map claim transformation og vælg Replace claim handlingen.

Remove default added post authentication method name

Find ID uden det standard tilføjede post authentication method navn med regex ^([^|]+)\|(?<map>.+)$

Du kan gøre det samme i en SAML 2.0 autentificeringsmetode ved at bruge http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier claimen (som indeholder SAML 2.0 Authn Response NameID værdien) i stedet for sub claimen.

Sammenlign email med _local:mfa:email og tilføj amr

Eksemplet sammenligner den aktuelt autentificerede brugers email med den allerede autentificerede MFA-brugers _local:mfa:email. Hvis de to email værdier matcher via et regex match, tilføjes amr claimen med autentificeringsmetodens navn som værdi (autentificeringsmetodens navn er konfigureret som amr værdi).

Brug en Concatenate claim transformation efterfulgt af en Regex match claim transformation.

Sammenlign email og tilføj amr

  • Concatenate: Ny claim _local:compare_emails, handling Replace claim, concatenate claims email og _local:mfa:email, concatenate format string {0}|{1}.
  • Regex match: Ny claim amr, handling Replace claim, select claim _local:compare_emails, regex value match ^([^|]+)\|\1$, ny værdi sat til autentificeringsmetodens navn (for eksempel 9fk5z3vg).
Dit privatliv

Dit privatliv

Vi bruger cookies til at gøre din oplevelse på vores websites bedre. Klik på 'Acceptér alle cookies' for at acceptere brugen af cookies. For at fravælge ikke-nødvendige cookies, klik på 'Kun nødvendige cookies'.

Besøg vores privatlivspolitik for mere