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.

Claim transform flow diagram

I autentiseringsmetoder med listen Forward claims legger du til vanlige claims opprettet av first-level transforms i listen for å gjøre dem tilgjengelige i etterfølgende trinn, eller inkluderer * (standard). Login autentiseringsmetoder viderefører disse claims uten listen.

De reserverte prefiksene _local:, _internal:, _session: og _impersonate: bestemmer hvordan claims brukes under autentisering. Se Lokale, interne og sesjonsclaims for de ulike levetidene.

For å utstede et vanlig claim fra en applikasjonsregistrering legger du til claimet eller * i Issue claims. For OpenID Connect kan du alternativt legge til claimet i et scopes Voluntary claims og be om scopet fra applikasjonen. Reserverte claims utstedes ikke, heller ikke med *.

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.

FoxIDs authentication method claim transform

Og claim tasks.

FoxIDs authentication method claim task

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

FoxIDs application registration claim transform

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.

Generelle lokale claims fra innloggingsforespørselen:

  • _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)
  • _local:params:{name} - en tillatt requestparameter fra applikasjonen, med parameternavnet i små bokstaver og én claim per verdi (bare hvis den er sendt med)

Når en autentiseringsmetode brukes som et element i Advanced MFA, mottar metodens egne claim transforms følgende lokale claims for brukeren som allerede er autentisert av Login-autentiseringsmetoden:

Claim Verdi
_local:mfa:user_id Brukerens stabile tekniske FoxIDs-bruker-ID.
_local:mfa:user_identifier Identifikatoren som ble brukt ved Login-autentiseringen. Hvis ingen identifikator ble oppgitt, bruker FoxIDs brukerens e-postadresse, telefonnummer eller brukernavn.
_local:mfa:username Brukerens registrerte brukernavn.
_local:mfa:email Brukerens registrerte e-postadresse, eller verdien av brukerens email-claim hvis den registrerte e-postadressen er tom.
_local:mfa:phone Brukerens registrerte telefonnummer, eller verdien av brukerens phone_number-claim hvis det registrerte telefonnummeret er tomt.

Bare claims med en ikke-tom verdi legges til. Disse transformasjonene arbeider med claims som returneres av den eksterne identitetsleverandøren, og kan legge til AMR-verdien som MFA-elementet krever. Login MFA-flyten bruker det transformerte svaret til å validere denne AMR-verdien. Andre claims fra autentiseringsmetoden slås ikke sammen med Login-autentiseringsmetodens claims og sendes ikke til dens generelle claim transforms.

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.
  • Impersonation - forbereder et valgt lokalt target som den effektive brukeren etter autentiseringsmetodens transforms. Se Impersonering.
  • 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.

Alle de fire brukeroppgavene ovenfor behandler en bruker som utilgjengelig når kontoen er deaktivert direkte eller gjennom et aktivt medlemskap i en tilgangsstruktur. Brukeren utelates før FoxIDs avgjør om søket fant nøyaktig én bruker, slik at query-oppgaver ikke legger til claims og save-oppgaver ikke gjør noen endringer.

Når en av de to query-oppgavene for brukere kjøres på en autentiseringsmetode og ingen lokal konto allerede er knyttet til det gjeldende autentiseringssvaret, blir den første entydig matchede brukeren i claim-transformasjonenes kjørerekkefølge svarets lokale konto. En Query internal user-oppgave med Target leverer bare lokale claims og lar kontotilknytningen være uendret. Hvis autentiseringen fortsetter gjennom Extended UI-trinn, beholder FoxIDs tilgangssnapshotet for den valgte kontoen i serversekvensen og bruker det når svaret fullføres. FoxIDs bruker deretter tilknytningen på aktive sesjoner og refresh token grants. En intern bruker eller tilkoblet ekstern bruker som autentiseres direkte av autentiseringsmetoden, har forrang, og en eksisterende tilknytning erstattes aldri av en senere query.

Hvis en claim-transformasjon starter en annen autentiseringsmetode interaktivt, kjøres den videresendte autentiseringen som et nytt login flow. En lokal kontotilknytning som ble valgt av en tidligere query, føres ikke gjennom videresendingen.

Query-oppgaver for brukere på en applikasjonsregistrering kan legge til claims, men oppretter eller endrer ikke innloggingens lokale kontotilknytning.

Query-oppgavene for brukere gjør den valgte brukerens stabile ID tilgjengelig som et lokalt claim:

Claim task Lokalt claim Verdi
Query internal user _local:internal_user_id Den valgte interne brukerens stabile tekniske FoxIDs-bruker-ID.
Query external user _local:external_user_id Den valgte eksterne brukerens stabile tekniske FoxIDs-ID for eksterne brukere.

Velg det lokale claimet eksplisitt i oppgavens outgoing claims, eller velg *, for å gjøre det tilgjengelig for etterfølgende transformasjoner i samme sekvens. Lokale claims fjernes fra det endelige resultatet med mindre verdien deres mappes til et ikke-lokalt claim.

Etter å ha slått opp en intern bruker via e-post eller brukernavn kan en Match claim and return error-oppgave for eksempel kontrollere _local:internal_user_id og stoppe flyten hvis ingen entydig intern bruker ble funnet. En Match claim-transformasjon kan i stedet legge til et annet claim bare når oppslaget lykkes. Den stabile bruker-ID-en forblir lokal i transformasjonssekvensen, men gir fortsatt et pålitelig grunnlag for etterfølgende beslutninger.

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.

Les inn en intern bruker i lokale claims

Angi det valgfrie Target på Query internal user for å lese inn en annen brukers claims til kontroller eller transformasjoner, samtidig som innloggingens lokale kontotilknytning beholdes. Angi et navn som target; FoxIDs legger til _local: og plasserer navnet foran hver valgt claim-type:

Valgt claim Lokalt resultat med Target target
sub _local:target:sub
email _local:target:email
role _local:target:role
_local:internal_user_id _local:target:_local:internal_user_id
_local:access_node _local:target:_local:access_node
_local:access_claim _local:target:_local:access_claim
_local:access_path_claim _local:target:_local:access_path_claim

Den fullstendige opprinnelige claimtypen beholdes under targetnavnet. Dette skiller lokale hjelpeclaims for kontoer og Access Structure fra vanlige claims. Oppslaget inkluderer claims fra aktive Access Structure medlemskap etter strukturens Forward claims innstilling, samt lokale hjelpeclaims for medlemskapskontroller.

Velg claims etter de opprinnelige navnene i Claims from internal user, eller bruk *. Det fullstendige lokale claim-navnet, inkludert prefiks og target-navn, må være innenfor grensen på 100 tegn. La Target være tomt for å legge til eller erstatte de valgte claims direkte i den gjeldende claim-samlingen.

Flere oppslag og Claims API-kall kan fylle samme target. Add claim legger til de returnerte verdiene. Replace claim erstatter verdiene for de returnerte claim-typene under dette target og beholder de øvrige claims som allerede finnes der.

Bruk target-claims i etterfølgende transformasjoner i samme sett. Kontroller for eksempel _local:target:role, eller map _local:target:sub til _internal:selected_user_id for å beholde verdien til senere transformasjonssett. Lokale target-claims fjernes når settet avsluttes.

Lokale, interne og sesjonsclaims

Bruk disse prefiksene til å velge levetiden for en verdi brukt av claim transforms og claim tasks. Et transformasjonssett er én ordnet liste med transforms og tasks: for eksempel autentiseringsmetodens first-level liste, en Extended UI liste, metodens second-level liste eller applikasjonsregistreringens liste. Overgangen til et annet sett har betydning selv når begge tilhører samme autentiseringsmetode.

Prefiks Bruksområde Hvor verdien er tilgjengelig Tilgjengelig ved senere applikasjonsinnlogging?
_local: En midlertidig verdi eller beslutning i ett sett Etterfølgende transforms og tasks i samme sett. Fjernes når settet avsluttes. Nei. FoxIDs kan tilføre ny lokal request- eller task-kontekst i et nytt sett.
_internal: En verdi som senere sett trenger i den aktuelle autentiseringsflyten Autentiseringsmetodens transforms, fortsettelser som Extended UI og applikasjonens transforms. Fjernes før protokollsvaret forlater FoxIDs. Nei. Opprett eller kopier verdien på nytt i den nye flyten.
_session: En liten verdi som beholdes for samme autentiserte bruker Lastes inn før first-level transforms; tilgjengelig gjennom mellomliggende og second-level transforms. Lagres etter vellykkede second-level transforms og fjernes før applikasjonens transforms. Ja, gjennom samme autentiseringsmetode så lenge brukerens sesjon er gyldig.
_impersonate: En målidentitet forberedt for impersonering Autentiseringsmetodens transforms og Extended UI frem til impersoneringen fullføres etter second-level transforms. Forbered målbrukeren på nytt i hver innloggingsflyt.

For eksempel kan _local:customer_found styre neste task i samme liste; _internal:customer_category kan leses av en applikasjonstransform senere i flyten; _session:profileId kan beholde en valgt profil til neste applikasjonsinnlogging.

Transforms som oppretter en tilknyttet ekstern bruker, arbeider med claims valgt for dette trinnet sammen med de aktuelle _session: claims. Velg et _internal: claim som inndata hvis opprettelsens transforms trenger verdien. Sesjonsclaims forblir i autentiseringsflyten og lagres ikke på den eksterne brukerkontoen.

Transforms som Constant, Map, Match claim og Match claim and value kan opprette eller bruke disse claims gjennom sine vanlige handlinger. Prefikset styrer claimets levetid. Bruk _session: på autentiseringsmetoden: sesjonsclaims opprettet av applikasjonens transforms lagres ikke i autentiseringsmetodens sesjon.

Kopier en verdi til en annen levetid

En Map transform kopierer en verdi til valgt utgående claim. Kilde og mål er separate claims med levetid etter sine egne prefikser. Når navnene er forskjellige, erstatter Replace claim eksisterende verdier i målclaimet og beholder kildeclaimet. Senere endringer av det ene oppdaterer ikke automatisk det andre.

Når en Query internal user task for eksempel returnerer _local:internal_user_id, legger du til en Map transform i samme sett fra _local:internal_user_id til _internal:selected_user_id. Senere sett kan da lese _internal:selected_user_id etter at det lokale claimet er fjernet. En transform på autentiseringsmetoden kan tilsvarende kopiere en _internal: verdi til et _session: claim for å beholde verdien til senere innlogginger.

Før en sesjonsverdi videre til applikasjonens transforms

Anta at _session:profileId inneholder customer-456, og at applikasjonens transforms trenger verdien. Konfigurer denne transformen i autentiseringsmetodens second-level liste etter transforms som endrer valgt profil:

Innstilling Verdi
Transformtype Map
Handling Replace claim
Inngående claim _session:profileId
Utgående claim _internal:profileId

Den videre flyten er:

  1. Begge claims inneholder customer-456 gjennom resten av autentiseringsmetodens transforms.
  2. Når second-level transforms avsluttes, lagrer FoxIDs _session:profileId for senere innlogginger og fjerner det fra den aktuelle claimsamlingen.
  3. _internal:profileId fortsetter til applikasjonens transforms. Det kan brukes til beslutninger der uten å utstedes til applikasjonen.
  4. Hvis applikasjonen trenger verdien i sitt token eller sin assertion, legger du til en Map transform på applikasjonen fra _internal:profileId til et vanlig claim som profile_id og konfigurerer dette for utstedelse.

Ved neste applikasjonsinnlogging laster FoxIDs inn _session:profileId for samme autentiserte bruker. Autentiseringsmetodens transform oppretter et nytt _internal:profileId for denne flyten. Samme fremgangsmåte gjelder når FoxIDs oversetter mellom JWT og SAML claims.

Videresending, protokollmapping og eksterne API-er

Interne claims og sesjonsclaims trenger ingen oppføring i Forward claims; de generelle lengdegrensene gjelder fortsatt. Reserverte claimnavn endres ikke av JWT/SAML protokollmapping, inkludert automatisk mapping. Bruk en Map claim transform til å kopiere en verdi mellom prefikser; protokollmapping kan ikke opprette reserverte claimtyper.

Ingen av de tre reserverte navnerommene utstedes i tokens eller assertions, heller ikke når Issue claims inneholder *. De utelates også fra forespørsler og svar til external claims API. Map en valgt verdi til et vanlig claim før den sendes til et API, og map ved behov et vanlig svarclaim til et reservert claim etterpå.

Prefiksene skiller mellom store og små bokstaver og er reservert av FoxIDs. Reserverte claims fra en protokoll eller et integrasjons-API fjernes før transformasjonene. Reserverte claims lagret på en eksisterende bruker ignoreres, og claim tasks kan ikke lagre dem på interne eller eksterne brukere. Hvis en task starter en annen autentiseringsmetode, overføres ikke den aktuelle claimsamlingen til den nye innloggingsflyten.

Sesjonsclaims

Bruk _session: claims til å beholde små mengder tilstand for samme autentiserte bruker på tvers av nettleserinnlogginger til forskjellige applikasjoner. Sesjoner må være aktivert på autentiseringsmetoden; de er aktivert som standard. FoxIDs støtter sesjonsclaims for Login, External Login, OpenID Connect, SAML 2.0, WS-Federation og Environment Link autentiseringsmetoder.

FoxIDs gjør lagrede sesjonsclaims tilgjengelige før autentiseringsmetodens first-level transforms. De er tilgjengelige gjennom mellomliggende transforms, Extended UI og second-level transforms. Når disse fullføres vellykket, lagrer FoxIDs de resulterende sesjonsclaims. Å fjerne et sesjonsclaim i en transform fjerner også den lagrede verdien. For å bruke en lagret sesjonsverdi i applikasjonens transforms må du kopiere den til et internt claim før autentiseringsmetoden fullføres.

Sesjonsclaims tilhører den opprinnelig autentiserte brukeren, uavhengig av endringer i sub gjennom claim transforms. De lastes bare inn ved samsvarende autentisert subject og en gyldig, aktiv sesjon på samme autentiseringsmetode. En metode som godtar flere issuers, må motta subjects som er unike på tvers av disse issuers. En start-authentication task fører ikke sesjonsclaims videre til en annen autentiseringsmetode, og flyter som bare håndterer tokens, leser eller lagrer ikke nettleserens sesjonsclaims.

Login og External Login kan gjenbruke nettlesersesjonen. Eksterne protokollbaserte autentiseringsmetoder autentiserer fortsatt hos den eksterne identitetsleverandøren ved hver applikasjonsinnlogging; FoxIDs laster inn sesjonsclaims etter kontroll av den returnerte identiteten. Sesjonsclaims følger autentiseringsmetodens sesjonslevetid og er utilgjengelige etter utlogging eller tilbakekalling av sesjonen.

Når en ny innlogging verifiserer samme bruker mens den tidligere sesjonen fortsatt er gyldig, beholder FoxIDs sesjonens lagrede verdier under claim transforms og Extended UI til second-level transforms fullføres uten feil og erstatter dem. En fullført ny innlogging starter autentiseringsmetodens absolutte sesjonslevetid på nytt; gjenbruk av en Login eller External Login sesjon følger dens konfigurerte glidende og absolutte levetid.

Login og External Login beholder de opprinnelige claims i nettlesersesjonen før claim transforms kjøres. Når second-level transforms er fullført uten feil, oppdaterer FoxIDs sesjonsclaims for den autentiserte brukeren, også etter Extended UI. Denne oppdateringen bevarer sesjonens vanlige claims og utløpstidspunkt. Hver autentiseringsmetode har én gjeldende bruker og én samling sesjonsclaims i nettleseren. En ny innlogging følger autentiseringsmetodens vanlige sesjonsatferd; nettleseren bruker den sist mottatte sesjonscookien.

Sesjonsclaims har disse lagringsgrensene:

Grense Verdi
Claimnavn 100 tegn inkludert _session:, med et gyldig JWT claimnavn og et navn etter prefikset som ikke er tomt eller bare blanktegn
Enkeltverdi 1 000 tegn
Antall claims 10 navn/verdi-par; hver verdi i et claim med flere verdier telles separat
Samlet verdilengde 2 000 tegn

Claims med ugyldige navn, tomme verdier eller verdier som bare inneholder blanktegn, utelates. Lengre verdier trunkeres. Claims behandles i rekkefølge; lagringen stopper når neste gyldige claim ville overskride antallsgrensen eller samlet verdilengde. Den generelle claimvalideringen under autentiseringsflyten gjelder fortsatt.

En transform på autentiseringsmetoden kan for eksempel beholde en referanse til en godkjent målbruker for impersonering i _session:impersonation_target_id. Senere applikasjonsinnlogginger gjennom metoden kan bruke referansen til å laste målbrukeren og kontrollere tillatelsene på nytt. Se Impersonering for hele eksemplet.

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.

Reserverte _local:, _internal:, _session: og _impersonate: claims utelates fra API-forespørsler og -svar. For å utveksle en valgt reservert verdi mapper du den til et vanlig claim før kallet, eller mapper et vanlig svarclaim til et reservert claim etterpå.

Beskyttede claims, som sid og auth_time, fjernes fra API-svar. De gjenværende claims i svaret behandles i henhold til den konfigurerte handlingen.

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.

Les inn claims fra API-svar som lokale claims

Angi det valgfrie Target på External claims API for å bruke svarets claims i etterfølgende kontroller eller transformasjoner. Når Target er target, blir et claim med navnet sub i API-svaret til _local:target:sub, og role blir til _local:target:role. API-et returnerer vanlige claim-navn; FoxIDs legger til det lokale prefikset etter filtrering og validering av svaret. Det fullstendige lokale claim-navnet må være innenfor grensen på 100 tegn. La Target være tomt for å legge til eller erstatte svarets claims direkte i den gjeldende claim-samlingen.

Flere API-kall og interne brukeroppslag kan fylle samme target. Add claim legger til de returnerte verdiene. Replace claim erstatter de returnerte claim-typene under dette target og beholder de øvrige. Et tomt svar lar eksisterende target-claims være uendret.

Lokale target-claims er tilgjengelige i det gjeldende transformasjonssettet. Map en verdi som _local:target:sub til _internal:selected_user_id for å bruke den i senere sett.

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

FoxIDs ignorerer claims der type eller value mangler, er null, er tom eller bare inneholder blanktegn. Når trace-logging av meldinger er aktivert, viser svarets trace de mottatte claims før de filtreres. Lange trace-meldinger avkortes.

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 Configure an external claims API claims transformation
  8. Angi eventuelt Target for å lese inn svarets claims som lokale claims
  9. 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.

Transform name to given_name and family_name

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

Remove default added post authentication method name

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 kjøres i en autentiseringsmetode som brukes som MFA-element. Det sammenligner metodens returnerte email-claim med Login-brukerens _local:mfa:email. Hvis de to e-postverdiene er like og samsvarer med et regulært uttrykk, legges amr-claimet til med autentiseringsmetodens navn som verdi (metodens navn konfigureres som amr-verdi).

Login MFA-flyten bruker det tillagte amr-claimet til å validere at MFA-elementet ble fullført. Det returnerte email-claimet og andre claims fra autentiseringsmetoden slås ikke sammen med Login-autentiseringsmetodens claims.

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

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

Impersonering

Bruk en Impersonation transform på en autentiseringsmetode til å utstede claims for en annen bruker, samtidig som den opprinnelig autentiserte brukeren beholdes som aktør. Sesjoner må være aktivert på autentiseringsmetoden; de er aktivert som standard.

Last målbrukeren med Query internal user, et eksternt claims API eller begge deler, med Target satt til et navn som target. Kontroller den autentiserte brukerens tillatelser og nødvendige claims for målbrukeren før du velger denne med en Impersonation transform. Target er påkrevd og har standardverdien target i Control Client. En forespørselsparameter fra applikasjonen velger en målbruker; den gir ikke tillatelse til impersonering.

Behold en referanse til den valgte målbrukeren i et sesjonsclaim for å gjenta oppslaget ved senere applikasjonsinnlogginger. Referansen kan være en intern bruker-ID eller en ekstern profil-ID og trenger ikke samsvare med målbrukerens utstedte sub. Eksemplet med en intern bruker nedenfor bruker impersonation_target_id for både forespørselsparameteren og sesjonsclaimet; dette er eksempelnavn som tilpasses flyten.

Den valgte målbrukeren må inneholde nøyaktig én entydig sub som ikke er blank. Ellers fortsetter transformen uten å velge denne målbrukeren. Et oppslag på en deaktivert intern bruker gir ingen claims. Bruk en betinget feiloppgave hvis policyen krever at innloggingen avvises når en målbruker ikke kan velges.

Transformen forbereder _impersonate: claims som fullføres etter vellykkede second-level transforms. For eksempel blir _local:target:sub til _impersonate:sub, og _local:target:_local:internal_user_id blir til _impersonate:_local:internal_user_id. Du kan også forberede disse med vanlige transforms. De er tilgjengelige mellom autentiseringsmetodens transformsett og gjennom Extended UI.

Ved fullføring erstatter FoxIDs brukerens vanlige identitetsclaims med målbrukerens vanlige claims, beholder den verifiserte autentiseringskonteksten og legger til et act claim der sub identifiserer den opprinnelig autentiserte brukeren. Aktørens subject er brukerens FoxIDs sub før impersoneringen erstatter claims. Applikasjonens transforms mottar denne effektive identiteten. Reserverte hjelpeclaims utstedes ikke til applikasjoner.

Interne målkontoer

Når _impersonate:_local:internal_user_id finnes, kontrollerer FoxIDs at den interne brukeren finnes og er aktivert, inkludert gjeldende Access Structure policy, og knytter målkontoen til sesjonen og grants sammen med den opprinnelige kontoen. Hvis den interne målbrukeren er ugyldig, ikke finnes eller er deaktivert, utføres ingen impersonering.

Deaktivering eller sletting av en av de tilknyttede kontoene tilbakekaller den aktive sesjonen og refresh token grants. Tilbakekalling av Access Structure tilgang og kontroller av tidsbegrensede medlemskap gjelder også målbrukeren. For en målbruker som bare leveres av et API uten intern kontotilknytning, avgjør det konfigurerte API-et og transforms om målbrukeren er tilgjengelig ved hver innlogging.

Eksempel: impersoner en intern bruker

Eksemplet lar en ansatt med claimverdien allow_impersonation i role velge en intern bruker og fortsette å impersonere denne ved senere applikasjonsinnlogginger. En innlogging uten valgt målbruker fortsetter som den opprinnelige brukeren.

Figuren følger de åtte transformasjonene som konfigureres nedenfor. Målreferansen beholdes mellom innlogginger; målbrukerens claims og medarbeiderens rettigheter kontrolleres på nytt ved hver innlogging.

Impersonering av en intern bruker: velg målbruker, kontroller rettigheter, last inn brukeren og lagre målreferansen for senere innlogginger

Konfigurer impersonation_target_id i Allowed request parameters på hver applikasjonsregistrering som sender parameteren. Applikasjonen sender én intern bruker-ID som parameterverdi, som FoxIDs gjør tilgjengelig som _local:params:impersonation_target_id. Se Forespørselsparametere fra applikasjoner. Sørg for at den ansattes claims inneholder role=allow_impersonation.

Legg følgende åtte oppføringer i rekkefølge til Login autentiseringsmetodens Second-level claim transforms.

  1. Map: gjenopprett den lagrede målreferansen. Bruk Replace claim, sett Select claim til _session:impersonation_target_id og New claim til _local:impersonation_target_id.

  2. Map: bruk en målbruker fra applikasjonen. Bruk Replace claim, sett Select claim til _local:params:impersonation_target_id og New claim til _local:impersonation_target_id. En angitt parameter erstatter det lagrede valget. Hvis parameteren mangler, beholdes verdien fra trinn 1.

  3. Match claim and value: kontroller den ansattes rolle. Bruk Replace claim, sett Select claim til role, Match value til allow_impersonation, New claim til _local:impersonation_check_passed og New value til true.

  4. Match claim: tillat innlogging uten målbruker. Bruk Replace claim, if not match, sett Select claim til _local:impersonation_target_id, New claim til _local:impersonation_check_passed og New value til true.

Det lokale kontrollclaimet betyr at innloggingen kan fortsette: enten har den ansatte den påkrevde rollen, eller ingen målbruker er valgt. Rollekontrollen kjøres før målbrukeren erstatter den opprinnelige brukerens claims.

Second-level claim transforms 1–4: velg målbrukeren og kontroller den opprinnelige brukerens rolle

  1. Match claim and return error: avvis et uautorisert valg. Bruk If not match og velg _local:impersonation_check_passed. Sett Error til access_denied og Error message til You are not allowed to impersonate another user.

  2. Query internal user: last målbrukeren. Bruk Replace claim, sett Lookup claim til _local:impersonation_target_id, Lookup claim on internal user til sub, Claims from internal user til * og Target til target. Oppslaget matcher den interne bruker-ID-en og laster brukerens claims, inkludert videresendte Access Structure claims og lokale hjelpeclaims, under _local:target:. Det gir for eksempel _local:target:sub og _local:target:_local:internal_user_id.

  3. Impersonation: velg den lastede målbrukeren. Bruk Replace claim og sett Target til target.

  4. Map: behold målbrukeren for senere innlogginger. Bruk Replace claim, sett Select claim til _local:target:_local:internal_user_id og New claim til _session:impersonation_target_id. Dette lagrer brukerens stabile ID som referanse for neste innlogging.

Second-level claim transforms 5–8: avvis uautoriserte valg, last og impersoner den interne brukeren, og behold målreferansen

Hvis policyen begrenser hvilke brukere som kan impersoneres, legger du til målkontroller mellom trinn 6 og 7. Kontroller for eksempel _local:target:role eller Access Structure hjelpeclaimet _local:target:_local:access_node.

Hvis oppslaget ikke gir noen målbruker, fullføres disse åtte trinnene uten impersonering, og en tidligere lagret målreferanse beholdes. Legg til en betinget feiloppgave etter oppslaget hvis en utilgjengelig målbruker skal avvise innloggingen, eller fjern sesjonsclaimet eksplisitt hvis valget skal tømmes.

Fortsette og endre impersonering

Hver applikasjonsinnlogging kjører autentiseringsmetodens transforms på nytt. I eksemplet over leser transforms målreferansen fra _session:impersonation_target_id når _local:params:impersonation_target_id mangler, laster målbrukerens gjeldende claims og gjentar tilgangskontrollene før impersonering velges. Referansen forblir bundet til den opprinnelig autentiserte brukeren og samme autentiseringsmetode.

Velg en annen målbruker ved å sende en ny referanse gjennom forespørselsparameteren og erstatte sesjonsclaimet etter at den nye målbrukeren har bestått kontrollene. Avslutt impersoneringen ved å tømme referansen og fullføre transforms uten en gyldig målbruker.

Vellykket fullføring med samme målbruker beholder sid. Valg av en annen målbruker, start av impersonering eller fullføring uten en gyldig målbruker oppretter en ny sid og tilbakekaller den forrige aktive sesjonen og refresh token grants.

UserInfo og innløsning av grants avviser en tilbakekalt aktiv sesjon. Applikasjoner og API-er som validerer tokens lokalt, må fortsatt følge sine egne regler for sesjoner og tokenlevetid. SAML single logout bruker hver applikasjons registrerte utstedelsesverdier.

Aktive sesjoner og refresh token grants viser målbrukerens subject og den opprinnelige aktøren i Control Client og Control API. Innloggingens audithendelser inkluderer aktøren. Egne audithendelser for impersonering registrerer start, endring og stopp, inkludert tidligere og gjeldende sesjons-ID-er.