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.

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.

Og claim tasks.

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

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 - udfør handlingen hvis claim typen matcher
• Match claim and value - udfør handlingen hvis claim typen og claim værdien matcher
• Regex match - udfør handlingen hvis claim typen matcher og claim værdien matcher regex

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

• Map - udfør handlingen hvis claim typen matcher, og map claim værdien til en ny claim
• Regex map - udfør handlingen hvis claim typen matcher og claim værdien matcher regex gruppen, og map gruppe værdien til en ny claim

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

• Constant - udfør handlingen altid (tilføj erstat en claim med en konstant værdi)
• Concatenate - udfør handlingen hvis en eller flere claim typer matcher, og concatenér claim værdierne til en ny claim
• External claims API - kald en external API med de valgte claims for at tilføje eller erstatte claims med eksterne claims
• DK XML privilege to JSON - konverter DK privilege til JSON.

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

• Query internal user - match claimen og find præcist én intern bruger baseret på claim værdien. Anmodningen fejler hvis der findes mere end én bruger. Tilføj eller erstat derefter brugerens claims.
• Query external user - match claimen og find præcist én ekstern bruger baseret på claim værdien. Anmodningen fejler hvis der findes mere end én bruger. Tilføj eller erstat derefter brugerens claims.

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

• Match claim and return error - returnér en fejl hvis claim typen matcher eller ikke matcher.
• Match claim and value and return error - returnér en fejl hvis claim typen og claim værdien matcher eller ikke matcher.
• Regex match and return error - returnér en fejl hvis claim typen og claim værdien matcher eller ikke matcher regex.
• Match claim and start authentication - start et nyt login flow ved at initier en autentificeringsmetode hvis claim typen matcher eller ikke matcher.
• Match claim and value and start authentication - start et nyt login flow ved at initier en autentificeringsmetode hvis claim typen og claim værdien matcher eller ikke matcher.
• Regex match and start authentication - start et nyt login flow ved at initier en autentificeringsmetode hvis claim typen matcher og claim værdien matcher eller ikke matcher regex.

Start authentication claim tasks kan bruges til step up når brugeren er logget ind med en 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
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.

• 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.

Find ID uden det standard tilføjede post authentication method navn med regex ^(nemlogin\|)(?<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.

• 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).