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 - utfør handlingen hvis claim typen matcher
• Match claim and value - utfør handlingen hvis claim typen og claim verdien matcher
• Regex match - utfør handlingen hvis claim typen matcher og claim verdien matcher regex

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

• Map - utfør handlingen hvis claim typen matcher, og map claim verdien til et nytt claim
• Regex map - utfør handlingen hvis claim typen matcher og claim verdien matcher regex gruppen, og map gruppe verdien til et nytt claim

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

• Constant - utfør handlingen alltid (legg til/erstatt et claim med en konstant verdi)
• Concatenate - utfør handlingen hvis en eller flere claim typer matcher, og concatener claim verdiene til et nytt claim
• External claims API - kall et eksternt API med de valgte claims for å legge til erstatte claims med eksterne claims
• DK XML privilege to JSON - konverter DK privilege til JSON.

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

• Query internal user - match claimet og finn nøyaktig én intern bruker basert på claim verdien. Requesten feiler hvis mer enn én bruker finnes. Legg til erstatt deretter brukerens claims.
• Query external user - match claimet og finn nøyaktig én ekstern bruker basert på claim verdien. Requesten feiler hvis mer enn én bruker finnes. Legg til erstatt deretter brukerens claims.

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

• Match claim and return error - returner en feil hvis claim typen matcher eller ikke matcher.
• Match claim and value and return error - returner en feil hvis claim typen og claim verdien matcher eller ikke matcher.
• Regex match and return error - returner en feil hvis claim typen og claim verdien matcher eller ikke matcher regex.
• Match claim and start authentication - start en ny login flyt ved å initiere en autentiseringsmetode hvis claim typen matcher eller ikke matcher.
• Match claim and value and start authentication - start en ny login flyt ved å initiere en autentiseringsmetode hvis claim typen og claim verdien matcher eller ikke matcher.
• Regex match and start authentication - start en ny login flyt ved å initiere en autentiseringsmetode hvis claim typen matcher og claim verdien matcher eller ikke matcher regex.

Start authentication claim tasks kan brukes for step up når brukeren er logget inn med én faktor og en annen faktor er påkrevd, 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 ^(nemlogin\|)(?<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).