Claim transforms och claim tasks

Varje FoxIDs autentiseringsmetod och applikationsregistrering hanterar claims och stödjer claim transforms och claim tasks. Det innebär att flera uppsättningar av claim transforms och claim tasks kan köras för varje användarautentisering. Först körs claim transforms och claim tasks på autentiseringsmetoden, och sedan på applikationsregistreringen.

Ytterligare delmängder av claim transforms och claim tasks kan utföras om en användare eller en extern användare skapas.

Claim transform flow diagram

I autentiseringsmetoder med listan Forward claims lägger du till vanliga claims som skapas av first-level transforms i listan för att göra dem tillgängliga i efterföljande steg, eller inkluderar * (standard). Login autentiseringsmetoder för dessa claims vidare utan listan.

De reserverade prefixen _local:, _internal:, _session: och _impersonate: styr hur claims används under autentisering. Se Lokala, interna och sessionsclaims för deras olika livslängder.

För att utfärda ett vanligt claim från en applikationsregistrering lägger du till claimet eller * i Issue claims. För OpenID Connect kan du alternativt lägga till claimet i ett scopes Voluntary claims och begära scopet från applikationen. Reserverade claims utfärdas inte, inte heller med *.

Se claim transform exempel.

Aktivera Log claim trace i log settings för att se claims före och efter transformation i logs.

Claim transforms kan konfigureras i en login autentiseringsmetod.

FoxIDs authentication method claim transform

Och claim tasks.

FoxIDs authentication method claim task

På samma sätt kan claim transforms och claim tasks konfigureras som first level och second level i en OpenID Connect autentiseringsmetod.

FoxIDs application registration claim transform

Claims representeras som standard som JWT claims. Om autentiseringsmetoden är SAML 2.0, representeras first level claims som SAML 2.0 claims. Om applikationsregistreringen är SAML 2.0, representeras claims som SAML 2.0 claims.

En claim transform och claim task utför en av upp till sju olika åtgärder beroende på typen.

Claim transform och claim task åtgärder:

Add claim - lägg till en ny claim
Add claim, if not match - utför add åtgärden om villkoret inte matchar
Replace claim - lägg till en ny claim och ta bort befintliga claims om en eller flera finns
Replace claim, if not match - utför replace åtgärden om villkoret inte matchar
Remove claim - ta bort claims om en eller flera finns
If match - utför åtgärden om villkoret matchar
If not match - utför åtgärden om villkoret inte matchar

Claim transforms och claim tasks körs i ordning, och åtgärderna körs därför i ordning. Det innebär att det är möjligt att skapa en lokal variabel genom att lägga till en claim och senare i sekvensen fatta beslut baserat på claimen. En claim är lokal i claim transforms och claim tasks uppsättningen om den börjar med _local:.

När claim transforms och claim tasks körs i ett login flöde lägger FoxIDs automatiskt till lokala claims från login requesten innan transformationerna körs. Dessa _local: claims är avsedda för beslut inom transform task sekvensen och tas bort från output.

Allmänna lokala claims från inloggningsbegäran:

_local:login_action - login request action, lagrad som camelCase
_local:user_id - login request user ID (endast om angivet)
_local:max_age - login request max age (endast om satt och större än 0)
_local:login_hint - login request hint (endast om angivet)
_local:acr - login request ACR värden som en space delimited lista (endast om angivet)
_local:params:{name} - en tillåten requestparameter från applikationen, med parameternamnet i små bokstäver och en claim per värde (endast om den skickas med)

När en autentiseringsmetod används som ett steg i Advanced MFA får metodens egna claim transforms följande lokala claims för användaren som redan har autentiserats av Login-autentiseringsmetoden:

Claim	Värde
`_local:mfa:user_id`	Användarens stabila tekniska FoxIDs-användar-ID.
`_local:mfa:user_identifier`	Identifieraren som användes vid Login-autentiseringen. Om ingen identifierare angavs använder FoxIDs användarens e-postadress, telefonnummer eller användarnamn.
`_local:mfa:username`	Användarens registrerade användarnamn.
`_local:mfa:email`	Användarens registrerade e-postadress, eller värdet i användarens `email`-claim om den registrerade e-postadressen är tom.
`_local:mfa:phone`	Användarens registrerade telefonnummer, eller värdet i användarens `phone_number`-claim om det registrerade telefonnumret är tomt.

Endast claims med ett icke-tomt värde läggs till. Dessa transforms arbetar med claims som returneras av den externa identitetsleverantören och kan lägga till det AMR-värde som MFA-steget kräver. Login MFA-flödet använder det transformerade svaret för att validera detta AMR-värde. Övriga claims från autentiseringsmetoden sammanfogas inte med Login-autentiseringsmetodens claims och skickas inte till dess allmänna claim transforms.

Med åtgärden Add claim, if not match är det möjligt att lägga till en claim (lokal variabel) om en annan claim eller ett claim värde inte finns.

Claim transform typer som stödjer alla åtgärder:

Match claim - kontrollerar om vald claim typ finns. För add- och replace-åtgärder skrivs outgoing claim med det nya värdet när claimen finns. if not match-åtgärder körs när claimen saknas. En remove-åtgärd tar bort vald outgoing claim när claimen finns.
Match claim and value - kontrollerar om vald claim typ finns med konfigurerat värde. För add- och replace-åtgärder skrivs outgoing claim med det nya värdet när både claim typ och värde matchar. if not match-åtgärder körs när claimen finns men värdet inte matchar. En remove-åtgärd tar bort vald outgoing claim när både claim typ och värde matchar.
Regex match - kontrollerar om vald claim typ finns och om claim värdet matchar det konfigurerade reguljära uttrycket. För add- och replace-åtgärder skrivs outgoing claim med det nya värdet när det reguljära uttrycket matchar. if not match-åtgärder körs när claimen finns men värdet inte matchar det reguljära uttrycket. En remove-åtgärd tar bort vald outgoing claim när det reguljära uttrycket matchar.

Claim transform typer som stödjer Add claim, Replace claim och Add claim, if new claim does not exist åtgärder:

Map - kopierar valt claim värde till outgoing claim. Med Add claim, if new claim does not exist skrivs värdet bara om outgoing claim inte redan finns.
Regex map - extraherar den namngivna regex gruppen map från valt claim värde och skriver det extraherade värdet till outgoing claim. Med Add claim, if new claim does not exist skrivs värdet bara om outgoing claim inte redan finns.

Claim transform typer som stödjer Add claim och Replace claim åtgärder:

Constant - skriver alltid det konfigurerade konstanta värdet till outgoing claim.
Concatenate - bygger outgoing claim från värden i valda claims. Formatsträngen använder platshållare som {0}, {1} och {2} för de valda claim värdena i ordning.
External claims API - skickar valda claims till ett externt API. Claims som returneras av APIet läggs till eller ersätter outgoing claims.
Impersonation - förbereder ett valt lokalt target som den effektiva användaren efter autentiseringsmetodens transformationer. Se Impersonering.
DK XML privilege to JSON - konverterar en DK privilege XML claim till JSON claims, en claim för varje PrivilegeGroup XML element.

Claim task typer som stödjer Add claim och Replace claim åtgärder:

Query internal user - använder lookup claim värdet för att hitta exakt en intern användare och lägger därefter till eller ersätter valda claims från den användaren i det aktuella claim setet.
Query external user - använder lookup claim värdet för att hitta exakt en extern användare och lägger därefter till eller ersätter valda claims från den användaren i det aktuella claim setet.
Save claim on internal user - använder lookup claim värdet för att hitta exakt en intern användare och lägger därefter till eller ersätter vald claim på den användaren med värden från vald update value claim i det aktuella claim setet.
Save claim on external user - använder lookup claim värdet för att hitta exakt en extern användare och lägger därefter till eller ersätter vald claim på den användaren med värden från vald update value claim i det aktuella claim setet.

Alla fyra användaruppgifterna ovan betraktar en användare som otillgänglig när kontot är inaktiverat direkt eller genom ett aktivt medlemskap i en åtkomststruktur. Användaren utesluts innan FoxIDs avgör om sökningen hittade exakt en användare, så query-uppgifter lägger inte till några claims och save-uppgifter gör inga ändringar.

När någon av de två query-uppgifterna för användare körs på en autentiseringsmetod och inget lokalt konto redan är kopplat till det aktuella autentiseringssvaret, blir den första entydigt matchade användaren i claim-transformeringarnas körordning svarets lokala konto. En Query internal user-uppgift med Target tillhandahåller endast lokala claims och lämnar kontokopplingen oförändrad. Om autentiseringen fortsätter genom Extended UI-steg behåller FoxIDs det valda kontots åtkomstsnapshot i serversekvensen och använder den när svaret slutförs. FoxIDs tillämpar därefter kopplingen på aktiva sessioner och refresh token grants. En intern användare eller ansluten extern användare som autentiseras direkt av autentiseringsmetoden har företräde, och en befintlig koppling ersätts aldrig av en senare query.

Om en claim-transformering startar en annan autentiseringsmetod interaktivt körs den omdirigerade autentiseringen som ett nytt login flow. En lokal kontokoppling som valts av en tidigare query följer inte med genom omdirigeringen.

Query-uppgifter för användare på en applikationsregistrering kan lägga till claims men skapar eller ändrar inte inloggningens lokala kontokoppling.

Query-uppgifterna för användare gör den valda användarens stabila ID tillgängligt som ett lokalt claim:

Claim task	Lokalt claim	Värde
`Query internal user`	`_local:internal_user_id`	Den valda interna användarens stabila tekniska FoxIDs-användar-ID.
`Query external user`	`_local:external_user_id`	Den valda externa användarens stabila tekniska FoxIDs-ID för externa användare.

Välj det lokala claimet uttryckligen i uppgiftens outgoing claims, eller välj *, för att göra det tillgängligt för efterföljande transformeringar i samma sekvens. Lokala claims tas bort från slutresultatet om deras värde inte mappas till ett icke-lokalt claim.

Efter att en intern användare har slagits upp via e-post eller användarnamn kan en Match claim and return error-uppgift till exempel kontrollera _local:internal_user_id och stoppa flödet om ingen unik intern användare hittades. En Match claim-transformering kan i stället lägga till ett annat claim endast när uppslagningen lyckas. Det stabila användar-ID:t förblir lokalt i transformeringssekvensen men ger ändå ett tillförlitligt underlag för efterföljande beslut.

För Query internal user och Save claim on internal user läses lookup claimen från det aktuella claim setet. Värdet Lookup claim on internal user avgör hur den interna användaren matchas:

sub matchar den interna användarens user ID.
email, phone_number och preferred_username söker först i den interna användarens identifiers med case-insensitive matching där stora och små bokstäver är relevanta. Om ingen användare hittas via identifier fortsätter uppslaget i användarens sparade claims.
Sökningen fortsätter därefter i den interna användarens sparade claims efter samma claim typ och ett värde som matchar utan hänsyn till stora och små bokstäver. Det gäller alla lookup claim typer om ingen användare först hittades.

Om sökningen hittar exakt en intern användare lägger Query internal user till eller ersätter valda claims från den användaren i det aktuella claim setet. Save claim on internal user lägger till eller ersätter vald claim på användaren med värden från vald update value claim. Om ingen användare hittas, eller om fler än en användare hittas via claims, läggs eller sparas inga interna användarclaims.

För Query external user och Save claim on external user läses lookup claimen från det aktuella claim setet och matchas mot den valda externa användarkällan. Använd link_claim som lookup claim på den externa användaren för att matcha på den externa användarens link claim värde.

Claim task typer som stödjer If match och If not match åtgärder:

Match claim and return error - returnerar ett fel om claim typen matchar eller inte matchar.
Match claim and value and return error - returnerar ett fel om claim typen och claim värdet matchar eller inte matchar.
Regex match and return error - returnerar ett fel om claim typen och claim värdet matchar eller inte matchar det reguljära uttrycket.
Match claim and log event - skriver det valda claim värdet till loggen om claim typen matchar.
Match claim and start authentication - startar ett nytt login flöde genom att initiera en autentiseringsmetod om claim typen matchar eller inte matchar.
Match claim and value and start authentication - startar ett nytt login flöde genom att initiera en autentiseringsmetod om claim typen och claim värdet matchar eller inte matchar.
Regex match and start authentication - startar ett nytt login flöde genom att initiera en autentiseringsmetod om claim typen och claim värdet matchar eller inte matchar det reguljära uttrycket.

För return error tasks konfigureras protokollfelet som returneras till klienten eller requester. OpenID Connect och OAuth 2.0 konfigurationer returnerar en error och en valfri error description. SAML 2.0 konfigurationer returnerar en SAML status code och message.

Start authentication claim tasks kan användas för step-up när användaren är inloggad med en faktor och en annan faktor krävs, eller om ytterligare information (claims) krävs.

Läs in en intern användare i lokala claims

Ange det valfria Target för Query internal user för att läsa in en annan användares claims för kontroller eller transformeringar samtidigt som inloggningens lokala kontokoppling bevaras. Ange ett namn som target; FoxIDs lägger till _local: och placerar namnet före varje vald claim-typ:

Vald 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 fullständiga ursprungliga claimtypen bevaras under targetnamnet. Det skiljer lokala hjälpclaims för konton och Access Structure från vanliga claims. Sökningen inkluderar claims från aktiva Access Structure medlemskap enligt strukturens inställning Forward claims, samt lokala hjälpclaims för medlemskapskontroller.

Välj claims efter deras ursprungliga namn i Claims from internal user, eller använd *. Det fullständiga lokala claim-namnet, inklusive prefix och target-namn, måste rymmas inom gränsen på 100 tecken. Lämna Target tomt för att lägga till eller ersätta de valda claims direkt i den aktuella claim-samlingen.

Flera sökningar och Claims API-anrop kan fylla samma target. Add claim lägger till de returnerade värdena. Replace claim ersätter värdena för de returnerade claim-typerna under detta target och behåller övriga claims som redan finns där.

Använd target-claims i efterföljande transformeringar i samma uppsättning. Kontrollera till exempel _local:target:role, eller mappa _local:target:sub till _internal:selected_user_id för att behålla värdet för senare uppsättningar. Lokala target-claims tas bort när uppsättningen avslutas.

Lokala, interna och sessionsclaims

Använd dessa prefix för att välja livslängden för ett värde som används av claim transforms och claim tasks. En transformationsuppsättning är en ordnad lista med transforms och tasks: exempelvis autentiseringsmetodens first-level lista, en Extended UI lista, dess second-level lista eller applikationsregistreringens lista. Övergången till en annan uppsättning har betydelse även när båda tillhör samma autentiseringsmetod.

Prefix	Användning	Var värdet är tillgängligt	Tillgängligt vid senare applikationsinloggning?
`_local:`	Ett tillfälligt värde eller beslut inom en uppsättning	Efterföljande transforms och tasks i samma uppsättning. Tas bort när uppsättningen avslutas.	Nej. FoxIDs kan tillföra ny lokal request- eller task-kontext i en ny uppsättning.
`_internal:`	Ett värde som senare uppsättningar behöver i det aktuella autentiseringsflödet	Autentiseringsmetodens transforms, fortsättningar som Extended UI och applikationens transforms. Tas bort innan protokollsvaret lämnar FoxIDs.	Nej. Skapa eller kopiera värdet igen i det nya flödet.
`_session:`	Ett litet värde som bevaras för samma autentiserade användare	Återställs före first-level transforms; tillgängligt genom mellanliggande och second-level transforms. Sparas efter lyckade second-level transforms och tas bort före applikationens transforms.	Ja, via samma autentiseringsmetod så länge användarens session är giltig.
`_impersonate:`	En målidentitet förberedd för impersonering	Autentiseringsmetodens transformationer och Extended UI tills impersoneringen slutförs efter andra nivåns transformationer.	Förbered målanvändaren på nytt vid varje inloggningsflöde.

Exempelvis kan _local:customer_found styra nästa task i samma lista; _internal:customer_category kan läsas av en applikationstransform senare i flödet; _session:profileId kan bevara en vald profil till nästa applikationsinloggning.

Transforms som skapar en länkad extern användare arbetar med de claims som valts för steget tillsammans med aktuella _session: claims. Välj ett _internal: claim som indata om dessa transforms behöver värdet. Sessionsclaims förblir en del av autentiseringsflödet och lagras inte på det externa användarkontot.

Transforms som Constant, Map, Match claim och Match claim and value kan skapa eller använda dessa claims genom sina vanliga åtgärder. Prefixet styr claimets livslängd. Använd _session: på autentiseringsmetoden: sessionsclaims som skapas av applikationens transforms sparas inte i autentiseringsmetodens session.

Kopiera ett värde till en annan livslängd

En Map transform kopierar ett värde till valt utgående claim. Källa och mål är separata claims med livslängder enligt respektive prefix. När namnen skiljer sig ersätter Replace claim befintliga värden i målclaimet och behåller källclaimet. Senare ändringar i det ena uppdaterar inte automatiskt det andra.

När exempelvis en Query internal user task returnerar _local:internal_user_id lägger du till en Map transform i samma uppsättning från _local:internal_user_id till _internal:selected_user_id. Senare uppsättningar kan då läsa _internal:selected_user_id efter att det lokala claimet tagits bort. En transform på autentiseringsmetoden kan på samma sätt kopiera ett _internal: värde till ett _session: claim för att bevara det till senare inloggningar.

För ett sessionsvärde vidare till applikationens transforms

Anta att _session:profileId innehåller customer-456 och att applikationens transforms behöver värdet. Konfigurera denna transform i autentiseringsmetodens second-level lista efter de transforms som ändrar vald profil:

Inställning	Värde
Transformtyp	`Map`
Åtgärd	`Replace claim`
Indataclaim	`_session:profileId`
Utdataclaim	`_internal:profileId`

Det fortsatta flödet är:

Båda claims innehåller customer-456 under autentiseringsmetodens återstående transforms.
När second-level transforms avslutas sparar FoxIDs _session:profileId för senare inloggningar och tar bort det från den aktuella claimsamlingen.
_internal:profileId fortsätter till applikationens transforms. Det kan användas för beslut där utan att utfärdas till applikationen.
Om applikationen behöver värdet i sitt token eller sin assertion lägger du till en Map transform på applikationen från _internal:profileId till ett vanligt claim som profile_id och konfigurerar detta för utfärdande.

Vid nästa applikationsinloggning återställer FoxIDs _session:profileId för samma autentiserade användare. Autentiseringsmetodens transform skapar ett nytt _internal:profileId för flödet. Samma tillvägagångssätt gäller när FoxIDs översätter mellan JWT och SAML claims.

Vidarebefordran, protokollmappning och externa API:er

Interna claims och sessionsclaims behöver ingen post i Forward claims; de allmänna längdgränserna gäller fortfarande. Reserverade claimnamn ändras inte av JWT/SAML protokollmappning, inklusive automatisk mappning. Använd en Map claim transform för att kopiera ett värde mellan prefix; protokollmappningar kan inte skapa reserverade claimtyper.

Ingen av de tre reserverade namnrymderna utfärdas i tokens eller assertions, inte heller när Issue claims innehåller *. De utesluts också från förfrågningar och svar till external claims API. Mappa ett valt värde till ett vanligt claim innan det skickas till ett API och mappa vid behov ett vanligt svarsclaim till ett reserverat claim efteråt.

Prefixen är skiftlägeskänsliga och reserverade av FoxIDs. Reserverade claims från ett protokoll eller ett integrations-API tas bort före transformationerna. Reserverade claims lagrade på en befintlig användare ignoreras, och claim tasks kan inte spara dem på interna eller externa användare. Om en task startar en annan autentiseringsmetod överförs inte den aktuella claimsamlingen till det nya inloggningsflödet.

Sessionsclaims

Använd _session: claims för att bevara små mängder tillstånd för samma autentiserade användare mellan webbläsarinloggningar till olika applikationer. Sessioner måste vara aktiverade på autentiseringsmetoden; de är aktiverade som standard. FoxIDs stöder sessionsclaims för Login, External Login, OpenID Connect, SAML 2.0, WS-Federation och Environment Link autentiseringsmetoder.

FoxIDs gör sparade sessionsclaims tillgängliga före autentiseringsmetodens first-level transforms. De är tillgängliga genom mellanliggande transforms, Extended UI och second-level transforms. När dessa avslutas framgångsrikt sparar FoxIDs resulterande sessionsclaims. Att ta bort ett sessionsclaim i en transform tar även bort dess sparade värde. För att använda ett sparat sessionsvärde i applikationens transforms ska du kopiera det till ett internt claim innan autentiseringsmetoden avslutas.

Sessionsclaims tillhör den ursprungligen autentiserade användaren oberoende av ändringar i sub genom claim transforms. De återställs endast för ett matchande autentiserat subject och en giltig, aktiv session på samma autentiseringsmetod. En metod som accepterar flera issuers måste få subjects som är unika över dessa issuers. En start-authentication task för inte sessionsclaims till en annan autentiseringsmetod, och flöden som enbart hanterar tokens läser eller sparar inte webbläsarens sessionsclaims.

Login och External Login kan återanvända sin webbläsarsession. Externa protokollbaserade autentiseringsmetoder autentiserar fortfarande hos den externa identitetsleverantören vid varje applikationsinloggning; FoxIDs återställer sessionsclaims efter att ha verifierat den returnerade identiteten. Sessionsclaims följer autentiseringsmetodens sessionslivslängd och är inte tillgängliga efter utloggning eller återkallande av sessionen.

När en ny inloggning verifierar samma användare medan den tidigare sessionen fortfarande är giltig, bevarar FoxIDs sessionens sparade värden under claim transforms och Extended UI tills second-level transforms slutförs utan fel och ersätter dem. En slutförd ny inloggning startar om autentiseringsmetodens absoluta sessionslivslängd; återanvändning av en Login eller External Login session följer dess konfigurerade glidande och absoluta livslängd.

Login och External Login bevarar de ursprungliga claims i webbläsarsessionen innan claim transforms körs. När second-level transforms har slutförts utan fel uppdaterar FoxIDs sessionsclaims för den autentiserade användaren, även efter Extended UI. Uppdateringen bevarar sessionens vanliga claims och utgångstid. Varje autentiseringsmetod har en aktuell användare och en samling sessionsclaims i webbläsaren. En ny inloggning följer autentiseringsmetodens normala sessionsbeteende; webbläsaren använder den sessionscookie som den senast tar emot.

Sessionsclaims har följande lagringsgränser:

Gräns	Värde
Claimnamn	100 tecken inklusive `_session:`, med ett giltigt JWT claimnamn och ett namn efter prefixet som inte är tomt eller bara blanktecken
Enskilt värde	1 000 tecken
Antal claims	10 namn/värde-par; varje värde i ett claim med flera värden räknas separat
Sammanlagd värdelängd	2 000 tecken

Claims med ogiltiga namn eller tomma värden eller värden som bara innehåller blanktecken utelämnas. Längre värden trunkeras. Claims behandlas i ordning; lagringen stoppas när nästa giltiga claim skulle överskrida antalsgränsen eller den sammanlagda värdelängden. Den allmänna claimvalideringen under autentiseringsflödet gäller fortfarande.

En transformation i autentiseringsmetoden kan exempelvis spara en referens till en godkänd målanvändare för impersonering i _session:impersonation_target_id. Senare applikationsinloggningar via metoden kan använda referensen för att läsa in målanvändaren och kontrollera behörigheterna igen. Se det fullständiga exemplet under Impersonering.

External claims - API

Du kan anropa ditt eget API från FoxIDs med en claim transformation. APIet anropas med claims och claims som returneras från APIet kan läggas till med en add eller replace åtgärd. APIet anropas endast om minst en vald claim finns. Du kan använda * för att välja och skicka alla claims till ditt API.

Reserverade _local:, _internal:, _session: och _impersonate: claims utesluts från API-förfrågningar och -svar. För att utbyta ett valt reserverat värde mappar du det till ett vanligt claim före anropet, eller mappar ett vanligt svarsclaim till ett reserverat claim efteråt.

Skyddade claims, som sid och auth_time, tas bort från API-svar. Övriga claims i svaret behandlas enligt den konfigurerade åtgärden.

Use case scenarier:

Anropa ditt API från en autentiseringsmetod varje gång en användare autentiseras antingen i FoxIDs eller hos en extern identity provider. Du kan då hitta användaren i din databas och returnera en user ID och kanske en customer ID eller något annat relevant. Du kan också skapa användaren i din databas.
Anropa ditt API från en applikationsregistrering med user ID (sub) och fråga efter användarens roller i din databas. Ditt API skulle då antingen returnera en tom lista eller en lista med role claims eller kanske en mer komplex rättighetsstruktur.

Läs in claims från API-svar som lokala claims

Ange det valfria Target för External claims API för att använda svarets claims i efterföljande kontroller eller transformeringar. När Target är target blir en claim med namnet sub i API-svaret _local:target:sub, och role blir _local:target:role. API:et returnerar vanliga claim-namn; FoxIDs lägger till det lokala prefixet efter att svaret har filtrerats och validerats. Det fullständiga lokala claim-namnet måste rymmas inom gränsen på 100 tecken. Lämna Target tomt för att lägga till eller ersätta svarets claims direkt i den aktuella claim-samlingen.

Flera API-anrop och interna användarsökningar kan fylla samma target. Add claim lägger till de returnerade värdena. Replace claim ersätter de returnerade claim-typerna under detta target och behåller de övriga. Ett tomt svar lämnar befintliga target-claims oförändrade.

Lokala target-claims är tillgängliga inom den aktuella uppsättningen transformeringar. Mappa ett värde som _local:target:sub till _internal:selected_user_id för att använda det i senare uppsättningar.

Implementera API

Du behöver implementera ett enkelt API som FoxIDs anropar när claim transformationen utförs. Se sample code.

APIet har en base URL och funktionaliteten är uppdelad i mappar. För närvarande stöds endast mappen claims (funktionalitet) för att begära en lista med claims.

Om base URL för APIet är https://somewhere.org/myclaimsstore är URLen för mappen claims https://somewhere.org/myclaimsstore/claims.

FoxIDs Cloud anropar ditt API från IP adressen 57.128.60.142. Den utgående IP adressen kan ändras och fler kan läggas till över tid.

Request

Säkrat med HTTP Basic auth: användarnamn external_claims, lösenord = konfigurerad secret.

APIet anropas med HTTP POST och en JSON body.

Detta är en request JSON body med två input claims:

{
  "claims": [
    { "type": "sub", "value": "1b1ac05e-5937-4939-a49c-0e84a89662df" },
    { "type": "email", "value": "some@test.org" }
  ]
}

Response - Success

Vid success ska APIet returnera HTTP code 200 och en lista med claims (listan kan vara tom).

FoxIDs ignorerar claims där type eller value saknas, är null, är tomt eller bara innehåller blanktecken. När trace-loggning av meddelanden är aktiverad visar svarets trace mottagna claims innan de filtreras. Långa trace-meddelanden kortas ned.

Till exempel användarens sub (user ID / username), customer ID och 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åste returnera HTTP code 401 (Unauthorized) och en error (required) om Basic auth avvisas. Lägg eventuellt till en felbeskrivning i ErrorMessage.

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

Om andra fel uppstår ska APIet returnera HTTP code 500 eller en annan lämplig felkod. Det rekommenderas att lägga till ett tekniskt felmeddelande ErrorMessage för diagnostik (det loggas bara och visas aldrig för slutanvändaren).

Felmeddelanden som returneras från APIet i ErrorMessage visas INTE för användaren; de loggas bara.

API Sample

Sample ExternalClaimsApiSample visar hur APIet implementeras i ASP.NET Core.

Du kan använda denna Postman collection för att anropa och testa ditt API med Postman.

Configure

Konfigurera FoxIDs att anropa ditt API från en claim transformation i FoxIDs Control Client.

Navigera till Claim Transform sektionen
Klicka Add claim transform
Klicka External claims API
Välj Add claim eller Replace claim
Lägg till de valda claims t.ex. sub i Select claims
Lägg till base API URL utan mappen claims i API URL
Lägg till API secret
Ange vid behov Target för att läsa in svarets claims som lokala claims
Klicka Update

Claim transform exempel

Dela upp `name` claim i två claims `given_name` och `family_name`

Transformeringen delar värdet i name claim vid första mellanslaget och lägger till given_name och family_name claims om de inte redan finns. Om det finns mer än ett mellanslag i name claim värdet kommer inga nya given_name och family_name claims att läggas till eftersom de redan finns.

Använd två Regex map claim transformationer.

Transform name to given_name and family_name

Hitta family_name claim värdet med regex ^\S+\s(?<map>\S+)$
Hitta given_name claim värdet med regex ^(?<map>\S+)\s\S+$

Ta bort det standard tillagda autentiseringsmetod namnet från `sub`

Autentiseringsmetod namnet läggs som standard till sub claim värdet som ett prefix delat med en pipe t.ex. some-auth-method|my-external-user-id.

Du kan använda en replace claim på sub claimet för att ta bort den standard tillagda prefix värdet.

Transformeringen delar värdet i sub claimet och ersätter claimet med ett nytt sub som bara innehåller den ursprungliga IDn.

Använd en Regex map claim transformation och välj Replace claim åtgärden.

Remove default added post authentication method name

Hitta ID utan det standard tillagda post authentication method namnet med regex ^([^|]+)\|(?<map>.+)$

Du kan göra samma sak i en SAML 2.0 autentiseringsmetod genom att använda http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier claimet (som innehåller SAML 2.0 Authn Response NameID värdet) istället för sub claimet.

Jämför `email` med `_local:mfa:email` och lägg till `amr`

Exemplet körs i en autentiseringsmetod som används som MFA-steg. Det jämför metodens returnerade email-claim med Login-användarens _local:mfa:email. Om de två e-postvärdena är lika och matchar ett reguljärt uttryck läggs claimet amr till med autentiseringsmetodens namn som värde (metodens namn konfigureras som amr-värde).

Login MFA-flödet använder det tillagda claimet amr för att validera att MFA-steget slutfördes. Det returnerade claimet email och övriga claims från autentiseringsmetoden sammanfogas inte med Login-autentiseringsmetodens claims.

Använd en Concatenate claim transformation följt av en Regex match claim transformation.

Jämför email och lägg till amr

Concatenate: Ny claim _local:compare_emails, åtgärd Replace claim, concatenate claims email och _local:mfa:email, concatenate format string {0}|{1}.
Regex match: Ny claim amr, åtgärd Replace claim, select claim _local:compare_emails, regex value match ^([^|]+)\|\1$, nytt värde satt till autentiseringsmetodens namn (till exempel 9fk5z3vg).

Impersonering

Använd transformationen Impersonation i en autentiseringsmetod för att utfärda claims för en annan användare och samtidigt behålla den ursprungligen autentiserade användaren som aktör. Sessioner måste vara aktiverade på autentiseringsmetoden; de är aktiverade som standard.

Läs in målanvändaren med Query internal user, ett externt claims API eller båda, med Target satt till exempelvis target. Kontrollera den autentiserade användarens behörighet och nödvändiga claims för målanvändaren innan du väljer denne med en Impersonation transformation. Target är obligatoriskt och har standardvärdet target i Control Client. En requestparameter från applikationen väljer en målanvändare; den ger inte behörighet att impersonera.

Spara en referens till målanvändaren i ett sessionsclaim för att upprepa sökningen vid senare applikationsinloggningar. Referensen kan vara ett internt användar-ID eller ett externt profil-ID och behöver inte motsvara målanvändarens utfärdade sub. Exemplet med en intern användare nedan använder impersonation_target_id för både requestparametern och sessionsclaimet; dessa exempelnamn anpassas till ditt flöde.

Den valda målanvändaren måste innehålla exakt ett distinkt, icke-blankt sub. Annars fortsätter transformationen utan att välja denna målanvändare. En sökning efter en inaktiverad intern användare returnerar inga claims. Använd en villkorlig feluppgift om din policy kräver att inloggningen avvisas när en målanvändare inte kan väljas.

Transformationen förbereder _impersonate: claims för slutförande efter framgångsrika transformationer på andra nivån. Exempelvis blir _local:target:sub till _impersonate:sub och _local:target:_local:internal_user_id till _impersonate:_local:internal_user_id. Dessa claims kan också förberedas med vanliga transformationer. De är tillgängliga mellan autentiseringsmetodens transformationsuppsättningar och genom Extended UI.

Vid slutförandet ersätter FoxIDs användarens vanliga identitetsclaims med målanvändarens vanliga claims, behåller den verifierade autentiseringskontexten och lägger till ett act claim vars sub identifierar den ursprungligen autentiserade användaren. Aktörens subject är användarens FoxIDs sub innan impersoneringen ersätter dennes claims. Applikationstransformationerna får denna effektiva identitet. Reserverade hjälpclaims utfärdas inte till applikationer.

Interna målkonton

När _impersonate:_local:internal_user_id finns kontrollerar FoxIDs att den interna användaren finns och är aktiverad, inklusive tillämplig Access Structure policy, och kopplar målkontot till sessionen och grants tillsammans med det ursprungliga kontot. Om den interna målanvändaren är ogiltig, saknas eller är inaktiverad utförs ingen impersonering.

Om något av de kopplade kontona inaktiveras eller tas bort återkallas den aktiva sessionen och refresh token grants. Återkallande av Access Structure åtkomst och kontroller av tidsbegränsade medlemskap gäller även målanvändaren. För en målanvändare som endast tillhandahålls av ett API utan intern kontokoppling avgör det konfigurerade API:et och transformationerna om målanvändaren är tillgänglig vid varje inloggning.

Exempel: impersonera en intern användare

Exemplet låter en medarbetare med claimvärdet role med värdet allow_impersonation välja en intern användare och fortsätta impersonera denne vid senare applikationsinloggningar. En inloggning utan vald målanvändare fortsätter som den ursprungliga användaren.

Figuren följer de åtta transforms som konfigureras nedan. Målreferensen behålls mellan inloggningar; målanvändarens claims och medarbetarens behörighet kontrolleras på nytt vid varje inloggning.

Impersonering av en intern användare: välj mål, kontrollera behörighet, läs in användaren och spara målreferensen för senare inloggningar

Konfigurera impersonation_target_id i Allowed request parameters på varje applikationsregistrering som skickar parametern. Applikationen skickar ett internt användar-ID som parametervärde, vilket FoxIDs gör tillgängligt som _local:params:impersonation_target_id. Se Applikationens requestparametrar. Säkerställ att medarbetarens claims innehåller role=allow_impersonation.

Lägg till följande åtta poster i ordning i Login autentiseringsmetodens Second-level claim transforms.

Map: återställ den sparade målreferensen. Använd Replace claim, sätt Select claim till _session:impersonation_target_id och New claim till _local:impersonation_target_id.
Map: använd en målanvändare från applikationen. Använd Replace claim, sätt Select claim till _local:params:impersonation_target_id och New claim till _local:impersonation_target_id. En angiven parameter ersätter det sparade valet. Om parametern saknas behålls värdet från steg 1.
Match claim and value: kontrollera medarbetarens roll. Använd Replace claim, sätt Select claim till role, Match value till allow_impersonation, New claim till _local:impersonation_check_passed och New value till true.
Match claim: tillåt inloggning utan målanvändare. Använd Replace claim, if not match, sätt Select claim till _local:impersonation_target_id, New claim till _local:impersonation_check_passed och New value till true.

Det lokala kontrollclaimet betyder att inloggningen får fortsätta: antingen har medarbetaren den nödvändiga rollen eller så är ingen målanvändare vald. Rollkontrollen körs innan målanvändaren ersätter den ursprungliga användarens claims.

Andra nivåns claim transforms 1–4: välj målanvändaren och kontrollera den ursprungliga användarens roll

Match claim and return error: avvisa ett obehörigt val. Använd If not match och välj _local:impersonation_check_passed. Sätt Error till access_denied och Error message till You are not allowed to impersonate another user.
Query internal user: läs in målanvändaren. Använd Replace claim, sätt Lookup claim till _local:impersonation_target_id, Lookup claim on internal user till sub, Claims from internal user till * och Target till target. Sökningen matchar det interna användar-ID:t och läser in användarens claims, inklusive vidarebefordrade Access Structure claims och lokala hjälpclaims, under _local:target:. Exempelvis tillhandahålls _local:target:sub och _local:target:_local:internal_user_id.
Impersonation: välj den inlästa målanvändaren. Använd Replace claim och sätt Target till target.
Map: spara målanvändaren för senare inloggningar. Använd Replace claim, sätt Select claim till _local:target:_local:internal_user_id och New claim till _session:impersonation_target_id. Detta sparar den inlästa användarens stabila ID som referens för nästa inloggning.

Andra nivåns claim transforms 5–8: avvisa obehöriga val, läs in och impersonera den interna användaren och spara målreferensen

Om din policy begränsar vilka användare som får impersoneras lägger du till målkontroller mellan steg 6 och 7. Kontrollera exempelvis _local:target:role eller Access Structure hjälpclaimet _local:target:_local:access_node.

Om sökningen inte returnerar någon målanvändare slutförs dessa åtta steg utan impersonering och behåller en tidigare sparad målreferens. Lägg till en villkorlig feluppgift efter sökningen om en otillgänglig målanvändare ska avvisa inloggningen, eller ta uttryckligen bort sessionsclaimet om det sparade valet ska rensas.

Fortsätta och ändra impersonering

Varje applikationsinloggning kör autentiseringsmetodens transformationer igen. I exemplet ovan läser transformationerna målreferensen från _session:impersonation_target_id när _local:params:impersonation_target_id saknas, läser in målanvändarens aktuella claims och upprepar behörighetskontrollerna innan impersonering väljs. Den sparade referensen förblir bunden till den ursprungligen autentiserade användaren och samma autentiseringsmetod.

Välj en annan målanvändare genom att skicka en ny referens via requestparametern och ersätta sessionsclaimet när den nya målanvändaren klarar kontrollerna. Avsluta impersonering genom att rensa den sparade referensen och slutföra transformationerna utan en giltig målanvändare.

Ett framgångsrikt slutförande med samma målanvändare behåller sid. Att välja en annan målanvändare, starta impersonering eller slutföra utan en giltig målanvändare skapar ett nytt sid och återkallar den tidigare aktiva sessionen och refresh token grants.

UserInfo och inlösen av grants avvisar en återkallad aktiv session. Applikationer och API:er som validerar tokens lokalt måste fortfarande tillämpa sina egna regler för sessioner och tokenlivslängd. SAML single logout använder varje applikations registrerade utfärdandevärden.

Aktiva sessioner och refresh token grants visar målanvändarens subject och den ursprungliga aktören i Control Client och Control API. Inloggningens audithändelser inkluderar aktören. Separata audithändelser för impersonering registrerar start, ändring och stopp, inklusive tidigare och aktuella sessions-ID:n.