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

På autentificeringsmetoder med listen Forward claims skal almindelige claims oprettet af first-level transforms tilføjes til listen for at være tilgængelige i efterfølgende trin, eller listen skal indeholde * (standard). Login autentificeringsmetoder fører disse claims videre uden denne liste.

De reserverede præfikser _local:, _internal:, _session: og _impersonate: bestemmer, hvordan claims bruges under autentificering. Se Lokale, interne og sessionsclaims for deres forskellige levetider.

For at udstede et almindeligt claim fra en applikationsregistrering skal du tilføje claimet eller * til Issue claims. For OpenID Connect kan du alternativt tilføje claimet til et scopes Voluntary claims og anmode om scopet fra applikationen. Reserverede claims udstedes ikke, heller ikke med *.

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.

Generelle lokale claims fra loginrequesten:

  • _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)
  • _local:params:{name} - en tilladt requestparameter fra applikationen, med parameternavnet i små bogstaver og én claim pr. værdi (kun hvis medsendt)

Når en autentificeringsmetode bruges som et element i Advanced MFA, modtager metodens egne claim transforms følgende lokale claims for den bruger, som allerede er autentificeret af Login autentificeringsmetoden:

Claim Værdi
_local:mfa:user_id Brugerens stabile tekniske FoxIDs bruger-ID.
_local:mfa:user_identifier Den identifikator, der blev brugt ved Login autentificeringen. Hvis ingen identifikator blev angivet, bruger FoxIDs brugerens e-mail, telefonnummer eller brugernavn.
_local:mfa:username Brugerens registrerede brugernavn.
_local:mfa:email Brugerens registrerede e-mail eller værdien af brugerens email claim, hvis den registrerede e-mail er tom.
_local:mfa:phone Brugerens registrerede telefonnummer eller værdien af brugerens phone_number claim, hvis det registrerede telefonnummer er tomt.

Kun claims med en ikke-tom værdi tilføjes. Disse transforms arbejder på de claims, som den eksterne identitetsudbyder returnerer, og kan tilføje den AMR-værdi, som MFA-elementet kræver. Login MFA-flowet bruger det transformerede svar til at validere denne AMR-værdi. Andre claims fra autentificeringsmetoden flettes ikke ind i Login autentificeringsmetodens claims og sendes ikke til dens generelle claim transforms.

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.
  • Impersonation - forbereder et valgt lokalt target som den effektive bruger efter autentificeringsmetodens 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 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.

Alle fire brugeropgaver ovenfor behandler en bruger som utilgængelig, når kontoen er deaktiveret direkte eller via et aktivt medlemskab af en adgangsstruktur. Brugeren udelukkes, før FoxIDs afgør, om søgningen fandt præcist én bruger, så query-opgaver ikke tilføjer claims, og save-opgaver ikke foretager ændringer.

Når en af de to query-opgaver for brugere kører på en autentificeringsmetode, og der endnu ikke er knyttet en lokal konto til det aktuelle autentificeringssvar, bliver den første entydigt matchede bruger i claim transformationernes udførelsesrækkefølge svarets lokale konto. En Query internal user-opgave med Target leverer kun lokale claims og bevarer kontotilknytningen. Hvis autentificeringen fortsætter gennem Extended UI-trin, bevarer FoxIDs den valgte kontos adgangssnapshot i serversekvensen og bruger det, når svaret afsluttes. FoxIDs anvender derefter tilknytningen på aktive sessioner og refresh token grants. En intern bruger eller en forbundet ekstern bruger, der autentificeres direkte af autentificeringsmetoden, har forrang, og en eksisterende tilknytning erstattes aldrig af en senere query.

Hvis en claim transformation starter en anden autentificeringsmetode interaktivt, kører den viderestillede autentificering som et nyt login flow. En lokal kontotilknytning, der er valgt af en tidligere query, føres ikke med gennem viderestillingen.

Query-opgaver for brugere på en applikationsregistrering kan tilføje claims, men opretter eller ændrer ikke loginnets lokale kontotilknytning.

Query-opgaverne for brugere gør den valgte brugers stabile ID tilgængeligt som et lokalt claim:

Claim task Lokalt claim Værdi
Query internal user _local:internal_user_id Den valgte interne brugers stabile tekniske FoxIDs-bruger-ID.
Query external user _local:external_user_id Den valgte eksterne brugers stabile tekniske FoxIDs-ID for eksterne brugere.

Vælg det lokale claim eksplicit i opgavens outgoing claims, eller vælg *, for at gøre det tilgængeligt for efterfølgende transformationer i samme sekvens. Lokale claims fjernes fra det endelige output, medmindre deres værdi mappes til et ikke-lokalt claim.

Efter opslag af en intern bruger via e-mail eller brugernavn kan en Match claim and return error-opgave for eksempel kontrollere _local:internal_user_id og stoppe flowet, hvis der ikke blev fundet præcist én intern bruger. En Match claim-transformation kan i stedet kun tilføje et andet claim, når opslaget lykkes. Det stabile bruger-ID forbliver lokalt i transformationssekvensen, men giver stadig et pålideligt grundlag for efterfølgende beslutninger.

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.

Indlæs en intern bruger i lokale claims

Angiv det valgfrie Target på Query internal user for at indlæse en anden brugers claims til kontroller eller transformationer, mens loginets lokale kontotilknytning bevares. Angiv et navn som target; FoxIDs tilføjer _local: og placerer 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 fulde oprindelige claimtype bevares under targetnavnet. Det adskiller lokale hjælpeclaims for konti og Access Structure fra almindelige claims. Opslaget medtager claims fra aktive Access Structure medlemskaber efter strukturens Forward claims indstilling samt lokale hjælpeclaims til kontrol af medlemskaber.

Vælg claims efter deres oprindelige navne i Claims from internal user, eller brug *. Det fulde lokale claim-navn, inklusive præfiks og target-navn, skal overholde grænsen på 100 tegn. Lad Target være tomt for at tilføje eller erstatte de valgte claims direkte i den aktuelle claim-samling.

Flere opslag og Claims API-kald kan udfylde samme target. Add claim tilføjer de returnerede værdier. Replace claim erstatter værdier for de returnerede claim-typer under dette target og bevarer de øvrige claims, der allerede findes der.

Brug target-claims i efterfølgende transforms i samme sæt. Kontrollér for eksempel _local:target:role, eller map _local:target:sub til _internal:selected_user_id for at bevare værdien til senere transformsæt. Lokale target-claims fjernes, når sættet afsluttes.

Lokale, interne og sessionsclaims

Brug disse præfikser til at vælge levetiden for en værdi, som claim transforms og claim tasks benytter. Et transformationssæt er én ordnet liste af transforms og tasks: eksempelvis autentificeringsmetodens first-level liste, en Extended UI liste, metodens second-level liste eller applikationsregistreringens liste. Overgangen til et andet sæt har betydning, selv når begge sæt tilhører samme autentificeringsmetode.

Præfiks Anvendelse Hvor værdien er tilgængelig Tilgængelig ved et senere applikationslogin?
_local: En midlertidig værdi eller beslutning i ét sæt Efterfølgende transforms og tasks i samme sæt. Fjernes, når sættet afsluttes. Nej. FoxIDs kan levere ny lokal request- eller task-kontekst i et nyt sæt.
_internal: En værdi, som senere sæt i det aktuelle autentificeringsflow skal bruge Autentificeringsmetodens transforms, fortsættelser som Extended UI og applikationens transforms. Fjernes, før protokolsvaret forlader FoxIDs. Nej. Opret eller kopier værdien igen i det nye flow.
_session: En lille værdi, som bevares for samme autentificerede bruger Indlæses før first-level transforms; tilgængelig gennem mellemliggende og second-level transforms. Gemmes efter vellykkede second-level transforms og fjernes før applikationens transforms. Ja, gennem samme autentificeringsmetode, så længe brugerens session er gyldig.
_impersonate: En målidentitet forberedt til impersonering Autentificeringsmetodens transforms og Extended UI, indtil impersoneringen afsluttes efter second-level transforms. Forbered målbrugeren igen i hvert loginflow.

Eksempelvis kan _local:customer_found styre næste task i samme liste; _internal:customer_category kan læses af en applikationstransform senere i flowet; _session:profileId kan bevare en valgt profil til næste applikationslogin.

Transforms til oprettelse af en tilknyttet ekstern bruger arbejder med de claims, som er valgt til dette trin, sammen med de aktuelle _session: claims. Vælg et _internal: claim som input, hvis oprettelsens transforms skal bruge værdien. Sessionsclaims forbliver i autentificeringsflowet og gemmes ikke på den eksterne brugerkonto.

Transforms som Constant, Map, Match claim og Match claim and value kan oprette eller bruge disse claims gennem deres normale handlinger. Præfikset styrer claimets levetid. Brug _session: på autentificeringsmetoden: sessionsclaims oprettet af applikationens transforms gemmes ikke i autentificeringsmetodens session.

Kopier en værdi til en anden levetid

En Map transform kopierer en værdi til det valgte outputclaim. Kilde og destination er separate claims med hver deres præfiksbestemte levetid. Når navnene er forskellige, erstatter Replace claim eksisterende værdier i destinationsclaimet og bevarer kildeclaimet. Senere ændringer af det ene claim opdaterer ikke automatisk det andet.

Når en Query internal user task eksempelvis returnerer _local:internal_user_id, kan du i samme sæt tilføje en Map transform fra _local:internal_user_id til _internal:selected_user_id. Senere sæt kan læse _internal:selected_user_id, efter det lokale claim er fjernet. En transform på autentificeringsmetoden kan tilsvarende kopiere en _internal: værdi til et _session: claim, hvis værdien skal bevares til senere logins.

Før en sessionsværdi videre til applikationens transforms

Antag, at _session:profileId indeholder customer-456, og at applikationens transforms skal bruge værdien. Konfigurer denne transform i autentificeringsmetodens second-level liste efter de transforms, der ændrer den valgte profil:

Indstilling Værdi
Transformtype Map
Handling Replace claim
Inputclaim _session:profileId
Outputclaim _internal:profileId

Det efterfølgende flow er:

  1. Begge claims indeholder customer-456 gennem de resterende transforms på autentificeringsmetoden.
  2. Når second-level transforms afsluttes, gemmer FoxIDs _session:profileId til senere logins og fjerner det fra den aktuelle claimsamling.
  3. _internal:profileId fortsætter til applikationens transforms. Det kan bruges til beslutninger dér uden at blive udstedt til applikationen.
  4. Hvis applikationen skal modtage værdien i sit token eller sin assertion, tilføjes en Map transform på applikationen fra _internal:profileId til et almindeligt claim som profile_id, der konfigureres til udstedelse.

Ved næste applikationslogin indlæser FoxIDs _session:profileId for samme autentificerede bruger. Autentificeringsmetodens transform opretter et nyt _internal:profileId til dette flow. Samme fremgangsmåde gælder, når FoxIDs oversætter mellem JWT og SAML claims.

Videresendelse, protokolmapping og eksterne API'er

Interne claims og sessionsclaims behøver ingen post i Forward claims; de generelle længdegrænser gælder stadig. Reserverede claimnavne ændres ikke af JWT/SAML protokolmapping, heller ikke automatisk mapping. Brug en Map claim transform til at kopiere en værdi mellem præfikser; protokolmapping kan ikke oprette reserverede claimtyper.

Ingen af de tre reserverede namespaces udstedes i tokens eller assertions, heller ikke når Issue claims indeholder *. De udelades også fra requests og responses til external claims API. Map en valgt værdi til et almindeligt claim, før den sendes til et API, og map efter behov et almindeligt responseclaim til et reserveret claim bagefter.

Præfikserne skelner mellem store og små bogstaver og er reserveret af FoxIDs. Reserverede claims modtaget fra en protokol eller et integrations-API fjernes før transformationerne. Reserverede claims gemt på en eksisterende bruger ignoreres, og claim tasks kan ikke gemme dem på interne eller eksterne brugere. Hvis en task starter en anden autentificeringsmetode, overføres den aktuelle claimsamling ikke til det nye loginflow.

Sessionsclaims

Brug _session: claims til at bevare små mængder tilstand for samme autentificerede bruger på tværs af browserlogins til forskellige applikationer. Sessioner skal være aktiveret på autentificeringsmetoden; de er aktiveret som standard. FoxIDs understøtter sessionsclaims for Login, External Login, OpenID Connect, SAML 2.0, WS-Federation og Environment Link autentificeringsmetoder.

FoxIDs gør gemte sessionsclaims tilgængelige før autentificeringsmetodens first-level transforms. De er tilgængelige gennem mellemliggende transforms, Extended UI og second-level transforms. Når disse transforms afsluttes korrekt, gemmer FoxIDs de resulterende sessionsclaims. Fjernes et sessionsclaim i en transform, fjernes også den gemte værdi. For at bruge en gemt sessionsværdi i applikationens transforms skal du kopiere den til et internt claim, før autentificeringsmetoden afsluttes.

Sessionsclaims tilhører den oprindeligt autentificerede bruger, uanset ændringer af sub i claim transforms. De indlæses kun ved et matchende autentificeret subject og en gyldig, aktiv session på samme autentificeringsmetode. En metode, der accepterer flere issuers, skal modtage subjects, som er unikke på tværs af disse issuers. En start-authentication task fører ikke sessionsclaims videre til en anden autentificeringsmetode, og flows, der kun håndterer tokens, læser eller gemmer ikke browserens sessionsclaims.

Login og External Login kan genbruge deres browsersession. Eksterne protokolbaserede autentificeringsmetoder autentificerer stadig hos den eksterne identitetsudbyder ved hvert applikationslogin; FoxIDs indlæser sessionsclaims efter kontrol af den returnerede identitet. Sessionsclaims følger autentificeringsmetodens sessionslevetid og er utilgængelige efter logout eller tilbagekaldelse af sessionen.

Når et nyt login verificerer samme bruger, mens den tidligere session stadig er gyldig, bevarer FoxIDs sessionens gemte værdier under claim transforms og Extended UI, indtil second-level transforms afsluttes korrekt og erstatter dem. Et gennemført nyt login starter autentificeringsmetodens absolutte sessionslevetid forfra; genbrug af en Login eller External Login session følger dens konfigurerede glidende og absolutte levetid.

Login og External Login bevarer de oprindelige claims i browsersessionen, før claim transforms køres. Når second-level transforms er gennemført korrekt, opdaterer FoxIDs sessionsclaims for den autentificerede bruger, også efter Extended UI. Denne opdatering bevarer sessionens almindelige claims og udløbstidspunkt. Hver autentificeringsmetode har én aktuel bruger og én samling sessionsclaims i browseren. Et nyt login følger autentificeringsmetodens normale sessionsadfærd; browseren benytter den sidst modtagne sessionscookie.

Sessionsclaims har følgende lagringsgrænser:

Grænse Værdi
Claimnavn 100 tegn inklusive _session:, med et gyldigt JWT claimnavn og et navn efter præfikset, som ikke er tomt eller kun blanktegn
Enkeltværdi 1.000 tegn
Antal claims 10 navn/værdi-par; hver værdi i et claim med flere værdier tælles separat
Samlet værdilængde 2.000 tegn

Claims med ugyldige navne eller tomme værdier eller værdier, der kun består af blanktegn, udelades. Længere værdier trunkeres. Claims behandles i rækkefølge; lagringen stopper, når det næste gyldige claim ville overskride antalsgrænsen eller den samlede værdilængde. Den generelle claimvalidering under autentificeringsflowet gælder stadig.

En transform på autentificeringsmetoden kan f.eks. gemme en reference til en godkendt impersoneringsmålbruger i _session:impersonation_target_id. Senere applikationslogin gennem metoden kan bruge referencen til at indlæse målbrugeren og kontrollere rettighederne igen. Se det fulde eksempel under Impersonering.

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.

Reserverede _local:, _internal:, _session: og _impersonate: claims udelades fra API-requests og -responses. For at udveksle en valgt reserveret værdi skal den mappes til et almindeligt claim før kaldet, eller et almindeligt responseclaim skal mappes til et reserveret claim bagefter.

Beskyttede claims, såsom sid og auth_time, fjernes fra API-svar. De resterende claims i svaret behandles i henhold til den konfigurerede handling.

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.

Indlæs claims fra API-svar som lokale claims

Angiv det valgfrie Target på External claims API for at bruge svarets claims i efterfølgende kontroller eller transformationer. Når Target er target, bliver et claim med navnet sub i API-svaret til _local:target:sub, og role bliver til _local:target:role. API'et returnerer almindelige claim-navne; FoxIDs tilføjer det lokale præfiks efter filtrering og validering af svaret. Det fulde lokale claim-navn skal overholde grænsen på 100 tegn. Lad Target være tomt for at tilføje eller erstatte svarets claims direkte i den aktuelle claim-samling.

Flere API-kald og interne brugeropslag kan udfylde samme target. Add claim tilføjer de returnerede værdier. Replace claim erstatter de returnerede claim-typer under dette target og bevarer de øvrige. Et tomt svar lader eksisterende target-claims være uændrede.

Lokale target-claims er tilgængelige inden for det aktuelle transformsæt. Map en værdi som _local:target:sub til _internal:selected_user_id for at bruge den i senere sæt.

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

FoxIDs ignorerer claims, hvor type eller value mangler, er null, er tom eller kun indeholder blanktegn. Når trace-logning af meddelelser er aktiveret, viser svarets trace de modtagne claims, før de filtreres. Lange trace-meddelelser afkortes.

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. Angiv eventuelt Target for at indlæse svarets claims som lokale claims
  9. 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 kører i en autentificeringsmetode, der bruges som MFA-element. Det sammenligner metodens returnerede email claim med Login-brugerens _local:mfa:email. Hvis de to e-mailværdier er ens og matcher et regulært udtryk, tilføjes amr claimet med autentificeringsmetodens navn som værdi (metodens navn konfigureres som amr-værdi).

Login MFA-flowet bruger det tilføjede amr claim til at validere, at MFA-elementet blev gennemført. Det returnerede email claim og andre claims fra autentificeringsmetoden flettes ikke ind i Login autentificeringsmetodens claims.

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

Impersonering

Brug en Impersonation transform på en autentificeringsmetode til at udstede claims for en anden bruger, mens den oprindeligt autentificerede bruger bevares som aktør. Sessioner skal være aktiveret på autentificeringsmetoden; de er aktiveret som standard.

Indlæs målbrugeren med Query internal user, et eksternt claims API eller begge dele, og sæt Target til f.eks. target. Kontrollér den autentificerede brugers rettigheder og de nødvendige claims på målbrugeren, før du vælger denne med en Impersonation transform. Target er påkrævet og har standardværdien target i Control Client. En parameter fra applikationen vælger en målbruger; den giver ikke ret til impersonering.

Gem en reference til målbrugeren i en session claim, så opslaget kan gentages ved senere applikationslogin. Referencen kan være et internt bruger-ID eller et eksternt profil-ID og behøver ikke svare til målbrugerens udstedte sub. Eksemplet med en intern bruger nedenfor bruger impersonation_target_id til både requestparameteren og session claimet; navnene er eksempler, som du tilpasser dit flow.

Den valgte målbruger skal indeholde præcis én entydig, ikke-blank sub. Ellers fortsætter transformen uden at vælge denne målbruger. Et opslag af en deaktiveret intern bruger leverer ingen claims. Brug en betinget fejltask, hvis din politik kræver, at login afvises, når en målbruger ikke kan vælges.

Transformen forbereder _impersonate: claims, der færdigbehandles efter vellykkede second-level transforms. F.eks. bliver _local:target:sub til _impersonate:sub, og _local:target:_local:internal_user_id bliver til _impersonate:_local:internal_user_id. Du kan også forberede disse claims med almindelige transforms. De er tilgængelige mellem autentificeringsmetodens transformsæt og gennem Extended UI.

Ved afslutningen erstatter FoxIDs brugerens almindelige identitetsclaims med målbrugerens almindelige claims, bevarer den verificerede autentificeringskontekst og tilføjer et act claim, hvor sub identificerer den oprindeligt autentificerede bruger. Aktørens subject er brugerens FoxIDs sub, før impersoneringen erstatter claims. Applikationens transforms modtager denne effektive identitet. Reserverede hjælpeclaims udstedes ikke til applikationer.

Interne målkonti

Når _impersonate:_local:internal_user_id findes, kontrollerer FoxIDs, at den interne bruger findes og er aktiveret, inklusive gældende Access Structure politik, og knytter målkontoen til sessionen og grants sammen med den oprindelige konto. Hvis den interne målbruger er ugyldig, ikke findes eller er deaktiveret, udføres ingen impersonering.

Deaktivering eller sletning af en af de tilknyttede konti tilbagekalder den aktive session og refresh token grants. Tilbagekaldelse af Access Structure adgang og kontrol af tidsbegrænsede medlemskaber gælder også for målbrugeren. For en målbruger, som kun leveres af et API uden intern kontokobling, afgør det konfigurerede API og transforms, om målbrugeren er tilgængelig ved hvert login.

Eksempel: impersonér en intern bruger

Eksemplet lader en medarbejder med værdien allow_impersonation i claimet role vælge en intern bruger og fortsætte impersoneringen ved senere applikationslogin. Et login uden valgt målbruger fortsætter som den oprindelige bruger.

Figuren følger de otte transforms, der konfigureres nedenfor. Målreferencen bevares mellem login; målbrugerens claims og medarbejderens rettigheder kontrolleres igen ved hvert login.

Impersonering af en intern bruger: vælg målbruger, kontrollér rettigheder, indlæs brugeren og gem målreferencen til senere login

Konfigurér impersonation_target_id i Allowed request parameters på hver applikationsregistrering, der sender parameteren. Applikationen sender ét internt bruger-ID som værdi, som FoxIDs gør tilgængeligt som _local:params:impersonation_target_id. Se Applikationens requestparametre. Sørg for, at medarbejderens claims indeholder role=allow_impersonation.

Tilføj følgende otte poster i rækkefølge til Login autentificeringsmetodens Second-level claim transforms.

  1. Map: gendan den gemte målreference. Brug Replace claim, sæt Select claim til _session:impersonation_target_id og New claim til _local:impersonation_target_id.

  2. Map: anvend en målbruger fra applikationen. Brug Replace claim, sæt Select claim til _local:params:impersonation_target_id og New claim til _local:impersonation_target_id. En angivet parameter erstatter det gemte valg. Hvis parameteren mangler, bevares værdien fra trin 1.

  3. Match claim and value: kontrollér medarbejderens rolle. Brug Replace claim, sæt Select claim til role, Match value til allow_impersonation, New claim til _local:impersonation_check_passed og New value til true.

  4. Match claim: tillad login uden målbruger. Brug Replace claim, if not match, sæt Select claim til _local:impersonation_target_id, New claim til _local:impersonation_check_passed og New value til true.

Det lokale kontrolclaim betyder, at login må fortsætte: enten har medarbejderen den krævede rolle, eller også er ingen målbruger valgt. Rollekontrollen udføres, før målbrugeren erstatter den oprindelige brugers claims.

Second-level claim transforms 1–4: vælg målbrugeren og kontrollér den oprindelige brugers rolle

  1. Match claim and return error: afvis et uautoriseret valg. Brug If not match, og vælg _local:impersonation_check_passed. Sæt Error til access_denied og Error message til You are not allowed to impersonate another user.

  2. Query internal user: indlæs målbrugeren. Brug Replace claim, sæt Lookup claim til _local:impersonation_target_id, Lookup claim on internal user til sub, Claims from internal user til * og Target til target. Opslaget matcher det interne bruger-ID og indlæser brugerens claims, inklusive videresendte Access Structure claims og lokale hjælpeclaims, under _local:target:. Det leverer f.eks. _local:target:sub og _local:target:_local:internal_user_id.

  3. Impersonation: vælg den indlæste målbruger. Brug Replace claim, og sæt Target til target.

  4. Map: gem målbrugeren til senere login. Brug Replace claim, sæt Select claim til _local:target:_local:internal_user_id og New claim til _session:impersonation_target_id. Det gemmer den indlæste brugers stabile ID som reference til næste login.

Second-level claim transforms 5–8: afvis uautoriserede valg, indlæs og impersonér den interne bruger, og gem målreferencen

Hvis din politik begrænser, hvilke brugere der må impersoneres, tilføjes kontroller af målbrugeren mellem trin 6 og 7. Kontrollér f.eks. _local:target:role eller Access Structure hjælpeclaimet _local:target:_local:access_node.

Hvis opslaget ikke leverer en målbruger, afsluttes disse otte trin uden impersonering, og en tidligere gemt målreference bevares. Tilføj en betinget fejltask efter opslaget, hvis en utilgængelig målbruger skal afvise login, eller fjern session claimet eksplicit, hvis det gemte valg skal ryddes.

Fortsæt og ændr impersonering

Hvert applikationslogin kører autentificeringsmetodens transforms igen. I eksemplet ovenfor læser transforms målreferencen fra _session:impersonation_target_id, når _local:params:impersonation_target_id mangler, indlæser målbrugerens aktuelle claims og gentager rettighedskontrollerne, før impersonering vælges. Den gemte reference forbliver bundet til den oprindeligt autentificerede bruger og samme autentificeringsmetode.

Vælg en anden målbruger ved at sende en ny reference i requestparameteren og erstatte session claimet, når den nye målbruger består kontrollerne. Afslut impersonering ved at rydde den gemte reference og afslutte transforms uden en gyldig impersoneringsmålbruger.

En vellykket afslutning med samme målbruger bevarer sid. Valg af en anden målbruger, start af impersonering eller afslutning uden en gyldig målbruger opretter et nyt sid og tilbagekalder den tidligere aktive session og refresh token grants.

UserInfo og indløsning af grants afviser en tilbagekaldt aktiv session. Applikationer og API'er, der validerer tokens lokalt, skal stadig anvende deres egne regler for sessioner og tokenlevetid. SAML single logout bruger de udstedelsesværdier, der er registreret for hver applikation.

Aktive sessioner og refresh token grants viser målbrugerens subject og den oprindelige aktør i Control Client og Control API. Login audit-events omfatter aktøren. Separate audit-events for impersonering registrerer start, ændring og stop, inklusive tidligere og aktuelle sessions-ID'er.