Claim transforms og claim tasks

Hver FoxIDs autentiseringsmetode og applikasjonsregistrering håndterer claims og støtter claim transforms og claim tasks. Det betyr at flere sett med claim transforms og claim tasks kan utføres for hver brukerautentisering. Først utføres claim transforms og claim tasks på autentiseringsmetoden, og deretter på applikasjonsregistreringen.

Ytterligere delmengder av claim transforms og claim tasks kan utføres hvis en bruker eller en ekstern bruker opprettes.

Hvis du oppretter et nytt claim med en first level claim transform eller claim task, er claimet lokalt for autentiseringsmetoden, unntatt for en Login autentiseringsmetode. I en autentiseringsmetode blir claimet videresendt hvis claim typen er lagt til i Forward claims listen, eller hvis * (standard) er inkludert i listen.

Hvis du oppretter et nytt claim med en claim transform eller claim task, er claimet lokalt for applikasjonsregistreringen. I en applikasjonsregistrering må du legge claimet eller * til Issue claims listen. Alternativt, for OpenID Connect, legg claimet til et scopes Voluntary claims liste og be om scopet fra applikasjonen din.

Se claim transform eksempler.

Aktiver Log claim trace i log settings for å se claims før og etter transformasjon i logs.

Claim transforms kan konfigureres i en login autentiseringsmetode.

Og claim tasks.

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

Claims representeres som standard som JWT claims. Hvis autentiseringsmetoden er SAML 2.0, representeres first level claims som SAML 2.0 claims. Hvis applikasjonsregistreringen er SAML 2.0, representeres claims som SAML 2.0 claims.

En claim transform og claim task vil gjøre en av opptil sju forskjellige handlinger avhengig av type.

Claim transform og claim task handlinger:

• Add claim - legg til et nytt claim
• Add claim, if not match - utfør add handlingen hvis betingelsen ikke matcher
• Replace claim - legg til et nytt claim og fjern eksisterende claims hvis én eller flere finnes
• Replace claim, if not match - utfør replace handlingen hvis betingelsen ikke matcher
• Remove claim - fjern claims hvis én eller flere finnes
• If match - utfør handlingen hvis betingelsen matcher
• If not match - utfør handlingen hvis betingelsen ikke matcher

Claim transforms og claim tasks utføres i rekkefølge, og handlingene utføres derfor i rekkefølge. Det betyr at det er mulig å opprette en lokal variabel ved å legge til et claim og senere i sekvensen ta beslutninger basert på claimet. Et claim er lokalt i claim transforms og claim tasks settet hvis det starter med _local:.

Når claim transforms og claim tasks kjører i en login flyt, legger FoxIDs automatisk til lokale claims fra login requesten før transformasjonene utføres. Disse _local: claims er ment for beslutninger inne i transform task sekvensen og fjernes fra output.

Lokale claims lagt til i AddLocalClaims:

• _local:login_action - login request action, lagret som camelCase
• _local:user_id - login request user ID (bare hvis angitt)
• _local:max_age - login request max age (bare hvis satt og større enn 0)
• _local:login_hint - login request hint (bare hvis angitt)
• _local:acr - login request ACR verdier som en space delimited liste (bare hvis angitt)

Med Add claim, if not match handlingen er det mulig å legge til et claim (lokal variabel) hvis et annet claim eller en claim verdi ikke finnes.

Claim transform typer som støtter alle handlinger:

• Match claim - kontrollerer om valgt claim type finnes. Ved add- og replace-handlinger skrives outgoing claim med den nye verdien når claimen finnes. if not match-handlinger kjøres når claimen mangler. En remove-handling fjerner valgt outgoing claim når claimen finnes.
• Match claim and value - kontrollerer om valgt claim type finnes med konfigurert verdi. Ved add- og replace-handlinger skrives outgoing claim med den nye verdien når både claim type og verdi matcher. if not match-handlinger kjøres når claimen finnes, men verdien ikke matcher. En remove-handling fjerner valgt outgoing claim når både claim type og verdi matcher.
• Regex match - kontrollerer om valgt claim type finnes og claim verdien matcher det konfigurerte regulære uttrykket. Ved add- og replace-handlinger skrives outgoing claim med den nye verdien når det regulære uttrykket matcher. if not match-handlinger kjøres når claimen finnes, men verdien ikke matcher det regulære uttrykket. En remove-handling fjerner valgt outgoing claim når det regulære uttrykket matcher.

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

• Map - kopierer valgt claim verdi til outgoing claim. Med Add claim, if new claim does not exist skrives verdien bare hvis outgoing claim ikke allerede finnes.
• Regex map - trekker ut den navngitte regex gruppen map fra valgt claim verdi og skriver den uttrukne verdien til outgoing claim. Med Add claim, if new claim does not exist skrives verdien bare hvis outgoing claim ikke allerede finnes.

Claim transform typer som støtter Add claim og Replace claim handlinger:

• Constant - skriver alltid den konfigurerte konstante verdien til outgoing claim.
• Concatenate - bygger outgoing claim fra verdier i valgte claims. Formatstrengen bruker plassholdere som {0}, {1} og {2} for de valgte claim verdiene i rekkefølge.
• External claims API - sender valgte claims til et eksternt API. Claims returnert av API-et legges 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 som støtter Add claim og Replace claim handlinger:

• Query internal user - bruker lookup claim verdien til å finne én intern bruker og legger deretter til eller erstatter valgte claims fra den interne brukeren i det aktuelle claim setet.
• Query external user - bruker lookup claim verdien til å finne én ekstern bruker og legger deretter til eller erstatter valgte claims fra den eksterne brukeren i det aktuelle claim setet.
• Save claim on internal user - bruker lookup claim verdien til å finne én intern bruker og legger deretter til eller erstatter valgt claim på den interne brukeren med verdier fra valgt update value claim i det aktuelle claim setet.
• Save claim on external user - bruker lookup claim verdien til å finne én ekstern bruker og legger deretter til eller erstatter valgt claim på den eksterne brukeren med verdier fra valgt update value claim i det aktuelle claim setet.

Ved Query internal user og Save claim on internal user leses lookup claimen fra det aktuelle claim setet. Verdien i Lookup claim on internal user bestemmer hvordan den interne brukeren matches:

• sub matcher den interne brukerens user ID.
• email, phone_number og preferred_username søker først i den interne brukerens identifiers med case-insensitive matching der store og små bokstaver er relevante. Hvis ingen bruker finnes via identifier, fortsetter oppslaget i brukerens lagrede claims.
• Søket fortsetter deretter i den interne brukerens lagrede claims etter samme claim type og en case-insensitive matchende verdi. Dette gjelder alle lookup claim typer hvis ingen bruker først ble funnet.

Hvis søket finner nøyaktig én intern bruker, legger Query internal user til eller erstatter valgte claims fra den brukeren i det aktuelle claim setet. Save claim on internal user legger til eller erstatter valgt claim på brukeren med verdier fra valgt update value claim. Hvis ingen bruker finnes, eller hvis mer enn én bruker finnes via claims, legges eller lagres ingen interne brukerclaims.

Ved Query external user og Save claim on external user leses lookup claimen fra det aktuelle claim setet og matches mot valgt ekstern brukerkilde. Bruk link_claim som lookup claim på ekstern bruker for å matche på den eksterne brukerens link claim verdi.

Claim task typer som støtter If match og If not match handlinger:

• Match claim and return error - returnerer en feil hvis claim typen matcher eller ikke matcher.
• Match claim and value and return error - returnerer en feil hvis claim typen og claim verdien matcher eller ikke matcher.
• Regex match and return error - returnerer en feil hvis claim typen og claim verdien matcher eller ikke matcher det regulære uttrykket.
• Match claim and log event - skriver den valgte claim verdien til loggen hvis claim typen matcher.
• Match claim and start authentication - starter en ny loginflyt ved å initiere en autentiseringsmetode hvis claim typen matcher eller ikke matcher.
• Match claim and value and start authentication - starter en ny loginflyt ved å initiere en autentiseringsmetode hvis claim typen og claim verdien matcher eller ikke matcher.
• Regex match and start authentication - starter en ny loginflyt ved å initiere en autentiseringsmetode hvis claim typen og claim verdien matcher eller ikke matcher det regulære uttrykket.

For return error tasks konfigureres protokollfeilen som returneres til client eller requester. OpenID Connect- og OAuth 2.0-konfigurasjoner returnerer en error og eventuelt en error description. SAML 2.0-konfigurasjoner returnerer en SAML status code og message.

Start authentication claim tasks kan brukes til step-up når brukeren er logget inn med én faktor og en annen faktor kreves, eller hvis ytterligere informasjon (claims) er nødvendig.

External claims - API

Du kan kalle ditt eget API fra FoxIDs med en claim transformasjon. APIet kalles med claims og claims returnert fra APIet kan legges til med en add eller replace handling. APIet kalles bare hvis minst én valgt claim eksisterer. Du kan bruke * for å velge og sende alle claims til APIet ditt.

Use case scenarier:

• Kall APIet ditt fra en autentiseringsmetode hver gang en bruker autentiseres enten i FoxIDs eller hos en ekstern identity provider. Du kan deretter finne brukeren i databasen din og returnere en user ID og kanskje en customer ID eller hva som er relevant. Du kan også opprette brukeren i databasen din.
• Kall APIet ditt fra en applikasjonsregistrering med bruker ID (sub) og hent brukerens roller i databasen din. APIet ditt vil da enten returnere en tom liste eller en liste med role claims eller kanskje en mer kompleks rettighetsstruktur.

Implementer API

Du må implementere et enkelt API som FoxIDs kaller når claim transformasjonen utføres. Vennligst se sample code.

APIet har en base URL, og funksjonaliteten er delt inn i mapper. For øyeblikket støttes bare claims mappen (funksjonalitet) for å be om en liste med claims.

Hvis base URL for APIet er https://somewhere.org/myclaimsstore vil URLen for claims mappen være https://somewhere.org/myclaimsstore/claims.

FoxIDs Cloud kaller APIet ditt fra IP adressen 57.128.60.142. Den utgående IP adressen kan endres og flere kan legges til over tid.

Request

Sikret med HTTP Basic auth: brukernavn external_claims, passord = konfigurert secret.

APIet kalles 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 suksess skal APIet returnere HTTP code 200 og en liste med claims (listen kan være tom).

For eksempel brukerens 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

APIet må returnere HTTP code 401 (Unauthorized) og en error (required) hvis Basic auth avvises. Legg eventuelt til en feilmelding i ErrorMessage.

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

Hvis andre feil oppstår, skal APIet returnere HTTP code 500 eller en annen passende feilkode. Det anbefales å legge til en teknisk feilmelding ErrorMessage for diagnostikk (den logges bare og vises aldri til sluttbrukeren).

Feilmeldinger returnert fra APIet i ErrorMessage vises IKKE til brukeren; de logges bare.

API Sample

Sample ExternalClaimsApiSample viser hvordan APIet implementeres i ASP.NET Core.

Du kan bruke denne Postman collection for å kalle og teste APIet ditt med Postman.

Configure

Konfigurer FoxIDs til å kalle APIet ditt fra en claim transformasjon i FoxIDs Control Client.

1. Naviger til Claim Transform seksjonen
2. Klikk Add claim transform
3. Klikk External claims API
4. Velg Add claim eller Replace claim
5. Legg til de valgte claims f.eks. sub i Select claims
6. Legg til base API URL uten claims mappen i API URL
7. Legg til API secret
8. Klikk Update

Claim transform eksempler

Splitt name claim i to claims given_name og family_name

Transformasjonen vil splitte verdien i name claim ved første mellomrom og legge til given_name og family_name claims, hvis de ikke allerede finnes. Hvis det er mer enn ett mellomrom i name claim verdien, legges ikke nye given_name og family_name claims til fordi de allerede finnes.

Bruk to Regex map claim transformasjoner.

• Finn family_name claim verdien med regex ^\S+\s(?<map>\S+)$
• Finn given_name claim verdien med regex ^(?<map>\S+)\s\S+$

Fjern standard lagt til autentiseringsmetode navn fra sub

Autentiseringsmetode navnet legges som standard til sub claim verdien som et prefix delt med en pipe f.eks. some-auth-method|my-external-user-id.

Du kan bruke en replace claim på sub claimet for å fjerne den standard lagte prefix verdien.

Transformasjonen vil splitte verdien i sub claimet og erstatte claimet med et nytt sub som bare inneholder den opprinnelige IDen.

Bruk en Regex map claim transformasjon og velg Replace claim handlingen.

Finn IDen uten den standard lagte post authentication method navnet med regex ^([^|]+)\|(?<map>.+)$

Du kan gjøre det samme i en SAML 2.0 autentiseringsmetode ved å bruke http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier claimet (som inneholder SAML 2.0 Authn Response NameID verdien) i stedet for sub claimet.

Sammenlign email med _local:mfa:email og legg til amr

Eksemplet sammenligner den aktuelt autentiserte brukerens email med den allerede autentiserte MFA-brukerens _local:mfa:email. Hvis de to email verdiene er like og matches med en regex match, legges amr claimet til med autentiseringsmetodens navn som verdi (autentiseringsmetodens navn er konfigurert som amr verdi).

Bruk en Concatenate claim transformasjon etterfulgt av en Regex match claim transformasjon.

• 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 verdi satt til autentiseringsmetodens navn (for eksempel 9fk5z3vg).