Claim transforms en claim tasks

Elke FoxIDs authenticatiemethode en app registratie verwerkt claims en ondersteunt claim transforms en claim tasks. Dat betekent dat meerdere sets van claim transforms en claim tasks kunnen worden uitgevoerd voor elke gebruikersauthenticatie. Eerst worden claim transforms en claim tasks uitgevoerd op de authenticatiemethode, en daarna op de app registratie.

Extra subsets van claim transforms en claim tasks kunnen worden uitgevoerd als een gebruiker of een externe gebruiker wordt aangemaakt.

Claim transform flow diagram

Voeg bij authenticatiemethoden met een lijst Forward claims gewone claims uit transformaties van het eerste niveau toe aan die lijst om ze beschikbaar te maken voor volgende stappen, of neem * op (standaard). Login authenticatiemethoden geven deze claims zonder die lijst door.

De gereserveerde voorvoegsels _local:, _internal:, _session: en _impersonate: bepalen hoe claims tijdens authenticatie worden gebruikt. Zie Lokale, interne en sessieclaims voor hun verschillende levensduren.

Voeg een gewone claim of * toe aan Issue claims om de claim vanuit een applicatieregistratie uit te geven. Bij OpenID Connect kunt u de claim ook toevoegen aan de Voluntary claims van een scope en die scope vanuit uw applicatie aanvragen. Gereserveerde claims worden niet uitgegeven, ook niet met *.

Bekijk de claim transform voorbeelden.

Schakel Log claim trace in de log settings in om de claims vóór en na de transformatie in de logs te zien.

Claim transforms kunnen worden geconfigureerd in een login authenticatiemethode.

FoxIDs authentication method claim transform

En claim tasks.

FoxIDs authentication method claim task

Op dezelfde manier kunnen claim transforms en claim tasks worden geconfigureerd als first level en second level in een OpenID Connect authenticatiemethode.

FoxIDs application registration claim transform

Claims worden standaard weergegeven als JWT claims. Als de authenticatiemethode SAML 2.0 is, worden de first level claims weergegeven als SAML 2.0 claims. Als de app registratie SAML 2.0 is, worden de claims weergegeven als SAML 2.0 claims.

Een claim transform en claim task voert één van maximaal zeven verschillende acties uit, afhankelijk van het type.

Claim transform en claim task acties:

Add claim - voeg een nieuwe claim toe
Add claim, if not match - voer de add actie uit als de voorwaarde niet overeenkomt
Replace claim - voeg een nieuwe claim toe en verwijder bestaande claims als er één of meer bestaan
Replace claim, if not match - voer de replace actie uit als de voorwaarde niet overeenkomt
Remove claim - verwijder de claims als er één of meer bestaan
If match - voer de actie uit als de voorwaarde overeenkomt
If not match - voer de actie uit als de voorwaarde niet overeenkomt

Claim transforms en claim tasks worden in volgorde uitgevoerd, en de acties worden daarom in volgorde uitgevoerd. Dit betekent dat het mogelijk is om een lokale variabele te maken door een claim toe te voegen en later in de reeks beslissingen te nemen op basis van de claim. Een claim is lokaal in de claim transforms en claim tasks set als deze begint met _local:.

Wanneer claim transforms en claim tasks in een login flow draaien, voegt FoxIDs automatisch lokale claims toe uit de login request voordat de transformaties worden uitgevoerd. Deze _local: claims zijn bedoeld voor beslissingen binnen de transform task reeks en worden uit de output verwijderd.

Algemene lokale claims uit het aanmeldverzoek:

_local:login_action - de login request action, opgeslagen als camelCase
_local:user_id - de login request user ID (alleen als opgegeven)
_local:max_age - de login request max age (alleen als ingesteld en groter dan 0)
_local:login_hint - de login request hint (alleen als opgegeven)
_local:acr - de login request ACR waarden als een space delimited lijst (alleen als opgegeven)
_local:params:{name} - een toegestane aanvraagparameter van de applicatie, met de parameternaam in kleine letters en één claim per waarde (alleen indien meegegeven)

Wanneer een authenticatiemethode als onderdeel van Advanced MFA wordt gebruikt, ontvangen de eigen claimtransformaties van die methode de volgende lokale claims voor de gebruiker die al door de Login-authenticatiemethode is geauthenticeerd:

Claim	Waarde
`_local:mfa:user_id`	De stabiele technische FoxIDs-gebruikers-ID van de gebruiker.
`_local:mfa:user_identifier`	De identificator die voor de Login-authenticatie is gebruikt. Als er geen identificator is opgegeven, gebruikt FoxIDs het e-mailadres, telefoonnummer of de gebruikersnaam van de gebruiker.
`_local:mfa:username`	De geregistreerde gebruikersnaam van de gebruiker.
`_local:mfa:email`	Het geregistreerde e-mailadres van de gebruiker, of de waarde van diens claim `email` als het geregistreerde e-mailadres leeg is.
`_local:mfa:phone`	Het geregistreerde telefoonnummer van de gebruiker, of de waarde van diens claim `phone_number` als het geregistreerde telefoonnummer leeg is.

Alleen claims met een niet-lege waarde worden toegevoegd. Deze transformaties verwerken de claims die door de externe identiteitsprovider worden geretourneerd en kunnen de AMR-waarde toevoegen die het MFA-onderdeel vereist. De Login-MFA-flow gebruikt het getransformeerde antwoord om die AMR-waarde te valideren. Andere claims van de authenticatiemethode worden niet samengevoegd met de claims van de Login-authenticatiemethode en niet doorgegeven aan de algemene claimtransformaties daarvan.

Met de Add claim, if not match actie is het mogelijk om een claim (lokale variabele) toe te voegen als een andere claim of een claim waarde niet bestaat.

Claim transform typen die alle acties ondersteunen:

Match claim - controleert of het geselecteerde claim type bestaat. Bij add- en replace-acties wordt de outgoing claim met de nieuwe waarde geschreven wanneer de claim bestaat. if not match-acties worden uitgevoerd wanneer de claim ontbreekt. Een remove-actie verwijdert de geselecteerde outgoing claim wanneer de claim bestaat.
Match claim and value - controleert of het geselecteerde claim type bestaat met de geconfigureerde waarde. Bij add- en replace-acties wordt de outgoing claim met de nieuwe waarde geschreven wanneer claim type en waarde overeenkomen. if not match-acties worden uitgevoerd wanneer de claim bestaat maar de waarde niet overeenkomt. Een remove-actie verwijdert de geselecteerde outgoing claim wanneer claim type en waarde overeenkomen.
Regex match - controleert of het geselecteerde claim type bestaat en de claim waarde overeenkomt met de geconfigureerde reguliere expressie. Bij add- en replace-acties wordt de outgoing claim met de nieuwe waarde geschreven wanneer de reguliere expressie overeenkomt. if not match-acties worden uitgevoerd wanneer de claim bestaat maar de waarde niet overeenkomt met de reguliere expressie. Een remove-actie verwijdert de geselecteerde outgoing claim wanneer de reguliere expressie overeenkomt.

Claim transform typen die Add claim, Replace claim en Add claim, if new claim does not exist acties ondersteunen:

Map - kopieert de geselecteerde claim waarde naar de outgoing claim. Met Add claim, if new claim does not exist wordt de waarde alleen geschreven als de outgoing claim nog niet bestaat.
Regex map - extraheert de genoemde regex groep map uit de geselecteerde claim waarde en schrijft de geëxtraheerde waarde naar de outgoing claim. Met Add claim, if new claim does not exist wordt de waarde alleen geschreven als de outgoing claim nog niet bestaat.

Claim transform typen die Add claim en Replace claim acties ondersteunen:

Constant - schrijft altijd de geconfigureerde constante waarde naar de outgoing claim.
Concatenate - bouwt de outgoing claim uit waarden in de geselecteerde claims. De format string gebruikt placeholders zoals {0}, {1} en {2} voor de geselecteerde claim waarden in volgorde.
External claims API - stuurt geselecteerde claims naar een externe API. Claims die door de API worden teruggegeven, worden toegevoegd aan of vervangen outgoing claims.
Impersonation - bereidt een geselecteerd lokaal target voor als effectieve gebruiker na de transformaties van de authenticatiemethode. Zie Impersonatie.
DK XML privilege to JSON - converteert een DK privilege XML claim naar JSON claims, één claim voor elk PrivilegeGroup XML element.

Claim task typen die Add claim en Replace claim acties ondersteunen:

Query internal user - gebruikt de lookup claim waarde om exact één interne gebruiker te vinden en voegt daarna geselecteerde claims van die gebruiker toe aan, of vervangt ze in, de huidige claim set.
Query external user - gebruikt de lookup claim waarde om exact één externe gebruiker te vinden en voegt daarna geselecteerde claims van die gebruiker toe aan, of vervangt ze in, de huidige claim set.
Save claim on internal user - gebruikt de lookup claim waarde om exact één interne gebruiker te vinden en voegt daarna de geselecteerde claim op die gebruiker toe, of vervangt die, met waarden uit de geselecteerde update value claim in de huidige claim set.
Save claim on external user - gebruikt de lookup claim waarde om exact één externe gebruiker te vinden en voegt daarna de geselecteerde claim op die gebruiker toe, of vervangt die, met waarden uit de geselecteerde update value claim in de huidige claim set.

Alle vier bovenstaande gebruikerstaken beschouwen een gebruiker als niet beschikbaar wanneer het account rechtstreeks of via een actief lidmaatschap van een toegangsstructuur is uitgeschakeld. De gebruiker wordt uitgesloten voordat FoxIDs bepaalt of de zoekopdracht precies één gebruiker heeft gevonden, zodat query-taken geen claims toevoegen en save-taken geen wijzigingen aanbrengen.

Wanneer een van beide query user-taken wordt uitgevoerd op een authenticatiemethode en er nog geen lokaal account aan het huidige authenticatieresultaat is gekoppeld, wordt de eerste uniek gevonden gebruiker in de uitvoeringsvolgorde van de claim-transformaties het lokale account van het resultaat. Een Query internal user-taak met Target levert alleen lokale claims en laat deze accountkoppeling ongewijzigd. Als de authenticatie doorgaat via Extended UI-stappen, bewaart FoxIDs de toegangssnapshot van het geselecteerde account in de server-side sequentie en gebruikt die wanneer het resultaat wordt voltooid. FoxIDs past de koppeling vervolgens toe op actieve sessies en refresh token-grants. Een interne of gekoppelde externe gebruiker die rechtstreeks door de authenticatiemethode is geauthenticeerd, heeft voorrang en een bestaande koppeling wordt nooit vervangen door een latere query.

Als een claim-transformatie interactief een andere authenticatiemethode start, wordt de doorgestuurde authenticatie als een nieuwe login flow uitgevoerd. Een lokale accountkoppeling die door een eerdere query is geselecteerd, wordt niet via die redirect meegenomen.

Query user-taken op een app-registratie kunnen claims toevoegen, maar maken of wijzigen de lokale accountkoppeling van de login niet.

De query user-taken stellen het stabiele ID van de geselecteerde gebruiker beschikbaar als een lokale claim:

Claim task	Lokale claim	Waarde
`Query internal user`	`_local:internal_user_id`	Het stabiele technische FoxIDs-gebruikers-ID van de geselecteerde interne gebruiker.
`Query external user`	`_local:external_user_id`	Het stabiele technische FoxIDs-ID van de geselecteerde externe gebruiker.

Selecteer de lokale claim expliciet in de outgoing claims van de taak, of selecteer *, om deze beschikbaar te maken voor volgende transformaties in dezelfde sequentie. Lokale claims worden uit de uiteindelijke uitvoer verwijderd, tenzij hun waarde naar een niet-lokale claim wordt gemapt.

Na het opzoeken van een interne gebruiker via e-mail of gebruikersnaam kan een Match claim and return error-taak bijvoorbeeld _local:internal_user_id controleren en de flow stoppen als er geen unieke interne gebruiker is gevonden. Een Match claim-transformatie kan in plaats daarvan alleen een andere claim toevoegen wanneer het opzoeken slaagt. Het stabiele gebruikers-ID blijft lokaal voor de transformatiesequentie en vormt toch een betrouwbare basis voor volgende beslissingen.

Voor Query internal user en Save claim on internal user wordt de lookup claim gelezen uit de huidige claim set. De waarde Lookup claim on internal user bepaalt hoe de interne gebruiker wordt gematcht:

sub matcht de user ID van de interne gebruiker.
email, phone_number en preferred_username zoeken eerst in de identifiers van de interne gebruiker met hoofdletterongevoelige matching waar hoofdletters relevant zijn. Als er geen gebruiker via identifier wordt gevonden, gaat de lookup verder in de opgeslagen claims van de gebruiker.
De zoekopdracht gaat daarna verder in de opgeslagen claims van de interne gebruiker voor hetzelfde claim type en een waarde die hoofdletterongevoelig overeenkomt. Dit geldt voor alle lookup claim typen als er eerst geen gebruiker is gevonden.

Als de zoekopdracht precies één interne gebruiker vindt, voegt Query internal user geselecteerde claims van die gebruiker toe aan, of vervangt ze in, de huidige claim set. Save claim on internal user voegt de geselecteerde claim op die gebruiker toe, of vervangt die, met waarden uit de geselecteerde update value claim. Als er geen gebruiker wordt gevonden, of als er via claims meer dan één gebruiker wordt gevonden, worden er geen interne gebruikerclaims toegevoegd of opgeslagen.

Voor Query external user en Save claim on external user wordt de lookup claim gelezen uit de huidige claim set en gematcht tegen de geselecteerde externe gebruikersbron. Gebruik link_claim als lookup claim op de externe gebruiker om te matchen op de link claim waarde van de externe gebruiker.

Claim task typen die If match en If not match ondersteunen:

Match claim and return error - geeft een fout terug als het claim type overeenkomt of niet overeenkomt.
Match claim and value and return error - geeft een fout terug als het claim type en de claim waarde overeenkomen of niet overeenkomen.
Regex match and return error - geeft een fout terug als het claim type en de claim waarde overeenkomen of niet overeenkomen met de reguliere expressie.
Match claim and log event - schrijft de geselecteerde claim waarde naar het log als het claim type overeenkomt.
Match claim and start authentication - start een nieuwe login flow door een authenticatiemethode te initiëren als het claim type overeenkomt of niet overeenkomt.
Match claim and value and start authentication - start een nieuwe login flow door een authenticatiemethode te initiëren als het claim type en de claim waarde overeenkomen of niet overeenkomen.
Regex match and start authentication - start een nieuwe login flow door een authenticatiemethode te initiëren als het claim type en de claim waarde overeenkomen of niet overeenkomen met de reguliere expressie.

Voor return error tasks configureer je de protocolfout die wordt teruggegeven aan de client of requester. OpenID Connect en OAuth 2.0 configuraties geven een error en optionele error description terug. SAML 2.0 configuraties geven een SAML statuscode en message terug.

De start authentication claim tasks kunnen worden gebruikt voor step-up wanneer de gebruiker is ingelogd met één factor en een andere factor vereist is, of als aanvullende informatie (claims) nodig is.

Een interne gebruiker in lokale claims laden

Stel het optionele Target in bij Query internal user om claims van een andere gebruiker te laden voor controles of transformaties, terwijl de lokale accountkoppeling van de aanmelding behouden blijft. Voer een naam zoals target in; FoxIDs voegt _local: toe en plaatst de naam vóór elk geselecteerd claim-type:

Geselecteerde claim	Lokaal resultaat met 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`

Het volledige oorspronkelijke claimtype blijft behouden onder de targetnaam. Zo blijven lokale hulpclaims voor accounts en Access Structure te onderscheiden van gewone claims. De zoekopdracht omvat claims uit actieve Access Structure lidmaatschappen, met inachtneming van de instelling Forward claims van de structuur, en lokale hulpclaims voor lidmaatschapscontroles.

Selecteer claims op hun oorspronkelijke naam in Claims from internal user, of gebruik *. De volledige lokale claim-naam, inclusief het voorvoegsel en de target-naam, moet binnen de limiet van 100 tekens blijven. Laat Target leeg om de geselecteerde claims rechtstreeks aan de huidige claim-verzameling toe te voegen of daarin te vervangen.

Meerdere zoekopdrachten en Claims API-aanroepen kunnen hetzelfde target vullen. Add claim voegt de geretourneerde waarden toe. Replace claim vervangt de waarden van de geretourneerde claim-typen onder dat target en behoudt de overige claims die daar al aanwezig zijn.

Gebruik de target-claims in volgende transformaties binnen dezelfde set. Controleer bijvoorbeeld _local:target:role, of map _local:target:sub naar _internal:selected_user_id om die waarde voor latere transformatiesets te behouden. Lokale target-claims worden aan het einde van de set verwijderd.

Lokale, interne en sessieclaims

Gebruik deze voorvoegsels om de levensduur te kiezen van een waarde voor claimtransformaties en claimtaken. Een transformatieset is één geordende lijst van transformaties en taken: bijvoorbeeld het eerste niveau van de authenticatiemethode, een Extended UI lijst, het tweede niveau of de lijst van een applicatieregistratie. De overgang naar een andere set is ook relevant als beide sets bij dezelfde authenticatiemethode horen.

Voorvoegsel	Gebruik	Waar de waarde beschikbaar is	Beschikbaar bij een latere applicatieaanmelding?
`_local:`	Tijdelijke waarde of beslissing binnen één set	Volgende transformaties en taken in dezelfde set. Verwijderd wanneer de set eindigt.	Nee. FoxIDs kan nieuwe lokale aanvraag- of taakcontext leveren in een nieuwe set.
`_internal:`	Waarde voor latere sets in de huidige authenticatiestroom	Transformaties van de authenticatiemethode, vervolgstappen zoals Extended UI en applicatietransformaties. Verwijderd voordat het protocolantwoord FoxIDs verlaat.	Nee. Maak of kopieer de waarde opnieuw in de nieuwe stroom.
`_session:`	Kleine waarde die voor dezelfde geauthenticeerde gebruiker bewaard blijft	Hersteld vóór het eerste niveau; beschikbaar tijdens tussenliggende transformaties en het tweede niveau. Opgeslagen na een geslaagd tweede niveau en verwijderd vóór applicatietransformaties.	Ja, via dezelfde authenticatiemethode zolang de sessie van de gebruiker geldig blijft.
`_impersonate:`	Een doelidentiteit voorbereid voor impersonatie	Transformaties van de authenticatiemethode en Extended UI, totdat de impersonatie na transformaties van het tweede niveau is voltooid.	Bereid het target bij iedere aanmeldingsstroom opnieuw voor.

Zo kan _local:customer_found de volgende taak in dezelfde lijst sturen, kan _internal:customer_category later door een applicatietransformatie worden gelezen en kan _session:profileId een geselecteerd profiel bewaren voor de volgende applicatieaanmelding.

Transformaties voor het aanmaken van een gekoppelde externe gebruiker werken met de claims die voor die stap zijn geselecteerd, samen met de huidige _session: claims. Selecteer een _internal: claim als invoer als de aanmaaktransformaties die waarde nodig hebben. Sessieclaims blijven onderdeel van de authenticatiestroom en worden niet opgeslagen op het externe gebruikersaccount.

Transformaties zoals Constant, Map, Match claim en Match claim and value kunnen deze claims via hun gewone acties maken of gebruiken. Het voorvoegsel bepaalt de levensduur. Gebruik _session: op de authenticatiemethode: sessieclaims uit applicatietransformaties worden niet in de sessie van de authenticatiemethode opgeslagen.

Een waarde naar een andere levensduur kopiëren

Een Map transformatie kopieert een waarde naar de geselecteerde uitvoerclaim. Bron en doel zijn afzonderlijke claims met de levensduur van hun eigen voorvoegsel. Bij verschillende namen vervangt Replace claim bestaande waarden van de doelclaim en behoudt de bronclaim. Latere wijzigingen in de ene claim werken de andere niet automatisch bij.

Als een Query internal user taak bijvoorbeeld _local:internal_user_id retourneert, voegt u in dezelfde set een Map transformatie toe van _local:internal_user_id naar _internal:selected_user_id. Latere sets kunnen dan _internal:selected_user_id lezen nadat de lokale claim is verwijderd. Een transformatie van de authenticatiemethode kan op dezelfde manier een _internal: waarde naar een _session: claim kopiëren om die voor latere aanmeldingen te bewaren.

Een sessiewaarde doorgeven aan applicatietransformaties

Stel dat _session:profileId de waarde customer-456 bevat en applicatietransformaties die nodig hebben. Configureer deze transformatie in de lijst van het tweede niveau van de authenticatiemethode, na transformaties die het geselecteerde profiel wijzigen:

Instelling	Waarde
Transformatietype	`Map`
Actie	`Replace claim`
Invoerclaim	`_session:profileId`
Uitvoerclaim	`_internal:profileId`

De verdere stroom is:

Beide claims bevatten customer-456 tijdens de resterende transformaties van de authenticatiemethode.
Na het tweede niveau slaat FoxIDs _session:profileId op voor latere aanmeldingen en verwijdert die uit de huidige claimverzameling.
_internal:profileId gaat door naar de applicatietransformaties. Die kunnen de waarde voor beslissingen gebruiken zonder de claim aan de applicatie uit te geven.
Als de applicatie de waarde in haar token of assertion nodig heeft, voegt u een applicatietransformatie Map toe van _internal:profileId naar een gewone claim zoals profile_id en configureert u die voor uitgifte.

Bij de volgende applicatieaanmelding herstelt FoxIDs _session:profileId voor dezelfde geauthenticeerde gebruiker. De transformatie van de authenticatiemethode maakt een nieuwe _internal:profileId voor die stroom. Dezelfde aanpak geldt wanneer FoxIDs tussen JWT en SAML claims vertaalt.

Doorgeven, protocolmapping en externe API's

Interne claims en sessieclaims hebben geen vermelding in Forward claims nodig; de algemene lengtegrenzen blijven gelden. Gereserveerde claimnamen blijven ongewijzigd bij JWT/SAML protocolmapping, inclusief automatische mapping. Gebruik een Map claimtransformatie om waarden tussen voorvoegsels te kopiëren; protocolmappings kunnen geen gereserveerde claimtypen maken.

Geen van de drie gereserveerde naamruimten wordt in tokens of assertions uitgegeven, ook niet met * in Issue claims. Ze worden ook uitgesloten van aanvragen en antwoorden van de externe claims-API. Map een geselecteerde waarde naar een gewone claim voordat u die naar een API stuurt en map zo nodig een gewone antwoordclaim achteraf naar een gereserveerde claim.

De voorvoegsels zijn hoofdlettergevoelig en gereserveerd door FoxIDs. Gereserveerde claims uit een protocol of integratie-API worden vóór de transformaties verwijderd. Gereserveerde claims op bestaande gebruikers worden genegeerd; claimtaken kunnen ze niet op interne of externe gebruikers opslaan. Als een taak een andere authenticatiemethode start, gaat de huidige claimverzameling niet mee naar de nieuwe aanmeldstroom.

Sessieclaims

Gebruik _session: claims om kleine hoeveelheden toestand voor dezelfde geauthenticeerde gebruiker te bewaren tussen browseraanmeldingen bij verschillende applicaties. Sessies moeten op de authenticatiemethode zijn ingeschakeld; dit is de standaardinstelling. FoxIDs ondersteunt sessieclaims voor Login, External Login, OpenID Connect, SAML 2.0, WS-Federation en Environment Link authenticatiemethoden.

FoxIDs maakt opgeslagen sessieclaims beschikbaar vóór de transformaties van het eerste niveau. Ze blijven beschikbaar tijdens tussenliggende transformaties, Extended UI en het tweede niveau. Na succesvolle afronding slaat FoxIDs de resulterende sessieclaims op. Het verwijderen van een sessieclaim in een transformatie verwijdert ook de opgeslagen waarde. Om een opgeslagen sessiewaarde in applicatietransformaties te gebruiken, kopieert u deze naar een interne claim voordat de authenticatiemethode wordt afgerond.

Sessieclaims horen bij de oorspronkelijk geauthenticeerde gebruiker, onafhankelijk van wijzigingen aan sub door transformaties. Ze worden alleen hersteld bij een overeenkomend geauthenticeerd subject en een geldige, actieve sessie op dezelfde authenticatiemethode. Een methode die meerdere issuers accepteert, moet subjects ontvangen die uniek zijn over al die issuers. Een taak die authenticatie start, draagt sessieclaims niet over aan een andere methode; stromen die alleen tokens verwerken, lezen of bewaren geen browsersessieclaims.

Login en External Login kunnen hun browsersessie hergebruiken. Externe protocolgebaseerde authenticatiemethoden authenticeren nog steeds bij elke applicatieaanmelding bij de externe identiteitsprovider; FoxIDs herstelt de sessieclaims na verificatie van de geretourneerde identiteit. Sessieclaims volgen de sessielevensduur van de authenticatiemethode en zijn na afmelding of intrekking van de sessie niet meer beschikbaar.

Wanneer een nieuwe aanmelding dezelfde gebruiker verifieert terwijl de vorige sessie nog geldig is, bewaart FoxIDs de opgeslagen waarden van die sessie tijdens claimtransformaties en Extended UI totdat de transformaties van het tweede niveau succesvol zijn afgerond en deze waarden vervangen. Een voltooide nieuwe aanmelding start de absolute sessielevensduur van de authenticatiemethode opnieuw; hergebruik van een Login of External Login sessie volgt de geconfigureerde schuivende en absolute levensduur.

Login en External Login bewaren de oorspronkelijke claims in de browsersessie voordat claimtransformaties worden uitgevoerd. Nadat de transformaties van het tweede niveau succesvol zijn afgerond, werkt FoxIDs de sessieclaims voor de geauthenticeerde gebruiker bij, ook na Extended UI. Deze update behoudt de gewone claims en de vervaltijd van de sessie. Elke authenticatiemethode houdt één huidige gebruiker en één verzameling sessieclaims bij in de browser. Een nieuwe aanmelding volgt het normale sessiegedrag van de authenticatiemethode; de browser gebruikt de laatst ontvangen sessiecookie.

Voor sessieclaims gelden deze opslaggrenzen:

Grens	Waarde
Claimnaam	100 tekens inclusief `_session:`, met een geldige JWT claimnaam en een naam na het voorvoegsel die niet leeg is of uitsluitend uit witruimte bestaat
Afzonderlijke waarde	1.000 tekens
Aantal claims	10 naam/waarde-paren; elke waarde van een claim met meerdere waarden telt afzonderlijk
Totale waardelengte	2.000 tekens

Claims met ongeldige namen of lege waarden of waarden met uitsluitend witruimte worden overgeslagen. Langere waarden worden afgekapt. Claims worden op volgorde behandeld; de opslag stopt zodra de volgende geldige claim het maximumaantal of de totale waardelengte zou overschrijden. De algemene claimvalidatie tijdens de authenticatiestroom blijft gelden.

Een transformatie van de authenticatiemethode kan bijvoorbeeld een verwijzing naar een toegestaan impersonatietarget bewaren in _session:impersonation_target_id. Latere applicatieaanmeldingen via die methode kunnen hiermee de doelgebruiker laden en de rechten opnieuw controleren. Zie Impersonatie voor het volledige voorbeeld.

External claims - API

Je kunt je eigen API aanroepen vanuit FoxIDs met een claim transformation. Het API wordt aangeroepen met claims en de claims die het API retourneert kunnen worden toegevoegd met een add of replace actie. Het API wordt alleen aangeroepen als ten minste één geselecteerde claim bestaat. Je kunt * gebruiken om alle claims te selecteren en naar je API te sturen.

Gereserveerde _local:, _internal:, _session: en _impersonate: claims worden uitgesloten van API-aanvragen en -antwoorden. Map een geselecteerde gereserveerde waarde vóór de aanroep naar een gewone claim, of map een gewone antwoordclaim achteraf naar een gereserveerde claim.

Beschermde claims, zoals sid en auth_time, worden uit API-antwoorden verwijderd. De overige claims in het antwoord worden verwerkt volgens de geconfigureerde actie.

Use case scenario's:

Roep je API aan vanuit een authenticatiemethode telkens wanneer een gebruiker wordt geauthenticeerd in FoxIDs of bij een externe identity provider. Je kunt de gebruiker vervolgens in je database vinden en een user ID en misschien een customer ID teruggeven of iets anders relevants. Je kunt de gebruiker ook in je database aanmaken.
Roep je API aan vanuit een app registratie met de user ID (sub) en haal de rollen van de gebruiker op uit je database. Je API zou dan ofwel een lege lijst teruggeven of een lijst met role claims of misschien een complexere rechtenstructuur.

Claims uit API-antwoorden als lokale claims laden

Stel het optionele Target in bij External claims API om de claims uit het antwoord in volgende controles of transformaties te gebruiken. Als Target is ingesteld op target, wordt een claim met de naam sub uit het API-antwoord _local:target:sub, en wordt role omgezet naar _local:target:role. De API retourneert gewone claim-namen; FoxIDs voegt het lokale voorvoegsel toe nadat het antwoord is gefilterd en gevalideerd. De volledige lokale claim-naam moet binnen de limiet van 100 tekens blijven. Laat Target leeg om claims uit het antwoord rechtstreeks aan de huidige claim-verzameling toe te voegen of daarin te vervangen.

Meerdere API-aanroepen en interne gebruikerszoekopdrachten kunnen hetzelfde target vullen. Add claim voegt de geretourneerde waarden toe. Replace claim vervangt de geretourneerde claim-typen onder dat target en behoudt de overige. Een leeg antwoord laat bestaande target-claims ongewijzigd.

Lokale target-claims zijn beschikbaar binnen de huidige transformatieset. Map een waarde zoals _local:target:sub naar _internal:selected_user_id om deze in latere sets te gebruiken.

Implementeer API

Je moet een eenvoudig API implementeren dat FoxIDs aanroept wanneer de claim transformation wordt uitgevoerd. Bekijk de sample code.

Het API heeft een base URL en de functionaliteit is verdeeld in mappen. Op dit moment wordt alleen de claims map (functionaliteit) voor het opvragen van een lijst met claims ondersteund.

Als de base URL voor het API https://somewhere.org/myclaimsstore is, dan is de URL voor de claims map https://somewhere.org/myclaimsstore/claims.

FoxIDs Cloud roept je API aan vanaf IP adres 57.128.60.142. Het uitgaande IP adres kan wijzigen en er kunnen in de loop van de tijd meer worden toegevoegd.

Request

Beveiligd met HTTP Basic auth: gebruikersnaam external_claims, wachtwoord = geconfigureerd secret.

Het API wordt aangeroepen met HTTP POST en een JSON body.

Dit is een request JSON body met twee input claims:

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

Response - Success

Bij success moet het API HTTP code 200 retourneren en een lijst van claims (de lijst kan leeg zijn).

FoxIDs negeert claims waarvan type of value ontbreekt, null is, leeg is of alleen witruimte bevat. Als tracelogging van berichten is ingeschakeld, bevat de responstrace de ontvangen claims voordat ze worden gefilterd. Lange traceberichten worden afgekapt.

Bijvoorbeeld de sub van de gebruiker (user ID / username), customer ID en rollen:

{
    "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

Het API moet HTTP code 401 (Unauthorized) en een error (required) retourneren als Basic auth wordt geweigerd. Voeg optioneel een foutbeschrijving toe in ErrorMessage.

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

Als er andere fouten optreden, moet het API HTTP code 500 of een andere passende foutcode retourneren. Het wordt aanbevolen om een technische foutbeschrijving ErrorMessage toe te voegen voor diagnostiek (deze wordt alleen gelogd en nooit aan de eindgebruiker getoond).

Foutmeldingen van het API in ErrorMessage worden NIET aan de gebruiker getoond; ze worden alleen gelogd.

API Sample

De sample ExternalClaimsApiSample laat zien hoe je het API implementeert in ASP.NET Core.

Je kunt deze Postman collection gebruiken om je API aan te roepen en te testen met Postman.

Configure

Configureer FoxIDs om je API aan te roepen via een claim transformation in FoxIDs Control Client.

Navigeer naar de sectie Claim Transform
Klik Add claim transform
Klik External claims API
Selecteer Add claim of Replace claim
Voeg de geselecteerde claims toe, bijvoorbeeld sub, in Select claims
Voeg de base API URL zonder de claims map toe in API URL
Voeg het API secret toe
Stel eventueel Target in om claims uit het antwoord als lokale claims te laden
Klik Update

Claim transform voorbeelden

Splits de `name` claim in de twee claims `given_name` en `family_name`

De transformatie splitst de waarde in de name claim bij de eerste spatie en voegt respectievelijk de given_name en family_name claims toe, als ze nog niet bestaan. Als er meer dan één spatie in de name claim waarde zit, worden geen nieuwe given_name en family_name claims toegevoegd omdat ze al bestaan.

Gebruik twee Regex map claim transformaties.

Transform name to given_name and family_name

Vind de family_name claim waarde met regex ^\S+\s(?<map>\S+)$
Vind de given_name claim waarde met regex ^(?<map>\S+)\s\S+$

Verwijder de standaard toegevoegde authenticatiemethode naam uit `sub`

De authenticatiemethode naam wordt standaard toegevoegd aan de sub claim waarde als een prefix gescheiden door een pipe, bijvoorbeeld some-auth-method|my-external-user-id.

Je kunt een replace claim gebruiken op de sub claim om de standaard toegevoegde prefix waarde te verwijderen.

De transformatie splitst de waarde in de sub claim en vervangt de claim met een nieuwe sub die alleen de originele ID bevat.

Gebruik een Regex map claim transformatie en selecteer de Replace claim actie.

Remove default added post authentication method name

Zoek de ID zonder de standaard toegevoegde post authentication method naam met regex ^([^|]+)\|(?<map>.+)$

Je kunt hetzelfde doen in een SAML 2.0 authenticatiemethode met de claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier (die de SAML 2.0 Authn Response NameID waarde bevat) in plaats van de sub claim.

Vergelijk `email` met `_local:mfa:email` en voeg `amr` toe

Het voorbeeld wordt uitgevoerd in een authenticatiemethode die als MFA-onderdeel wordt gebruikt. Het vergelijkt de geretourneerde claim email van de methode met _local:mfa:email van de Login-gebruiker. Als de twee e-mailwaarden gelijk zijn en overeenkomen met een reguliere expressie, wordt de claim amr toegevoegd met de naam van de authenticatiemethode als waarde (de methodenaam wordt als amr-waarde geconfigureerd).

De Login-MFA-flow gebruikt de toegevoegde claim amr om te valideren dat het MFA-onderdeel succesvol is voltooid. De geretourneerde claim email en andere claims van de authenticatiemethode worden niet samengevoegd met de claims van de Login-authenticatiemethode.

Gebruik een Concatenate claim transformatie gevolgd door een Regex match claim transformatie.

Vergelijk email en voeg amr toe

Concatenate: Nieuwe claim _local:compare_emails, actie Replace claim, concatenate claims email en _local:mfa:email, concatenate format string {0}|{1}.
Regex match: Nieuwe claim amr, actie Replace claim, select claim _local:compare_emails, regex value match ^([^|]+)\|\1$, nieuwe waarde ingesteld op de naam van de authenticatiemethode (bijvoorbeeld 9fk5z3vg).

Impersonatie

Gebruik de transformatie Impersonation op een authenticatiemethode om claims voor een andere gebruiker uit te geven, terwijl de oorspronkelijk geauthenticeerde gebruiker als actor behouden blijft. Sessies moeten op de authenticatiemethode zijn ingeschakeld; dat is standaard het geval.

Laad het target met Query internal user, een externe claims API of beide, met Target ingesteld op bijvoorbeeld target. Controleer de rechten van de geauthenticeerde gebruiker en alle vereiste targetclaims voordat u het target selecteert met een Impersonation transformatie. Target is verplicht en heeft in de Control Client de standaardwaarde target. Een aanvraagparameter van de applicatie selecteert een target; deze verleent geen recht op impersonatie.

Bewaar een verwijzing naar het geselecteerde target in een sessieclaim om de zoekopdracht bij latere applicatieaanmeldingen te herhalen. De verwijzing kan een interne gebruikers-ID of een externe profiel-ID zijn en hoeft niet overeen te komen met het uitgegeven sub van het target. Het onderstaande voorbeeld met een interne gebruiker gebruikt impersonation_target_id voor zowel de aanvraagparameter als de sessieclaim; dit zijn voorbeeldnamen die u aan uw stroom aanpast.

Het geselecteerde target moet precies één unieke, niet-lege sub bevatten. Anders gaat de transformatie verder zonder dit target te selecteren. Een zoekopdracht naar een uitgeschakelde interne gebruiker levert geen claims op. Gebruik een voorwaardelijke fouttaak als uw beleid vereist dat de aanmelding wordt afgewezen wanneer een target niet kan worden geselecteerd.

De transformatie bereidt _impersonate: claims voor die na geslaagde transformaties van het tweede niveau worden verwerkt. Zo wordt _local:target:sub omgezet in _impersonate:sub en _local:target:_local:internal_user_id in _impersonate:_local:internal_user_id. U kunt deze claims ook voorbereiden met gewone transformaties. Ze blijven beschikbaar tussen transformatiesets van de authenticatiemethode en gedurende Extended UI.

Bij voltooiing vervangt FoxIDs de gewone identiteitsclaims van de gebruiker door de gewone claims van het target, behoudt de geverifieerde authenticatiecontext en voegt een act claim toe waarvan sub de oorspronkelijk geauthenticeerde gebruiker identificeert. Dit actorsubject is de FoxIDs sub van de gebruiker voordat impersonatie diens claims vervangt. Applicatietransformaties ontvangen deze effectieve identiteit. Gereserveerde hulpclaims worden niet aan applicaties uitgegeven.

Interne doelaccounts

Wanneer _impersonate:_local:internal_user_id aanwezig is, controleert FoxIDs of de interne gebruiker bestaat en is ingeschakeld, inclusief het toepasselijke Access Structure beleid, en koppelt het doelaccount naast het oorspronkelijke account aan de sessie en grants. Als de interne doelgebruiker ongeldig is, niet bestaat of is uitgeschakeld, wordt geen impersonatie uitgevoerd.

Het uitschakelen of verwijderen van een van beide gekoppelde accounts trekt de actieve sessie en refresh token grants in. Intrekking van Access Structure toegang en controles van tijdgebonden lidmaatschappen gelden ook voor het gekoppelde target. Voor een target dat uitsluitend door een API zonder interne accountkoppeling wordt geleverd, bepalen de geconfigureerde API en transformaties bij iedere aanmelding of het target beschikbaar is.

Voorbeeld: een interne gebruiker impersoneren

Met dit voorbeeld kan een medewerker met de claimwaarde allow_impersonation in role een interne gebruiker selecteren en die gebruiker bij latere applicatieaanmeldingen blijven impersoneren. Een aanmelding zonder geselecteerd target gaat verder als de oorspronkelijke gebruiker.

Het diagram volgt de acht hieronder geconfigureerde transformaties. De doelreferentie blijft tussen aanmeldingen behouden; de claims van de doelgebruiker en de rechten van de medewerker worden bij elke aanmelding opnieuw gecontroleerd.

Impersonatie van een interne gebruiker: kies het doel, controleer rechten, laad de gebruiker en bewaar de doelreferentie voor latere aanmeldingen

Configureer impersonation_target_id in Allowed request parameters op iedere applicatieregistratie die de parameter verstuurt. De applicatie levert één interne gebruikers-ID als parameterwaarde, die FoxIDs beschikbaar maakt als _local:params:impersonation_target_id. Zie Aanvraagparameters van applicaties. Zorg ervoor dat de claims van de medewerker role=allow_impersonation bevatten.

Voeg de volgende acht items in deze volgorde toe aan Second-level claim transforms van de Login authenticatiemethode.

Map: herstel de opgeslagen targetverwijzing. Gebruik Replace claim, stel Select claim in op _session:impersonation_target_id en New claim op _local:impersonation_target_id.
Map: neem een target uit de applicatie over. Gebruik Replace claim, stel Select claim in op _local:params:impersonation_target_id en New claim op _local:impersonation_target_id. Een meegegeven parameter vervangt de opgeslagen selectie. Zonder parameter blijft de waarde uit stap 1 behouden.
Match claim and value: controleer de rol van de medewerker. Gebruik Replace claim, stel Select claim in op role, Match value op allow_impersonation, New claim op _local:impersonation_check_passed en New value op true.
Match claim: sta aanmelding zonder target toe. Gebruik Replace claim, if not match, stel Select claim in op _local:impersonation_target_id, New claim op _local:impersonation_check_passed en New value op true.

De lokale controleclaim betekent dat de aanmelding mag doorgaan: de medewerker heeft de vereiste rol of er is geen target geselecteerd. De rolcontrole vindt plaats voordat het target de claims van de oorspronkelijke gebruiker vervangt.

Claimtransformaties van het tweede niveau 1–4: selecteer het target en controleer de rol van de oorspronkelijke gebruiker

Match claim and return error: wijs een onbevoegde selectie af. Gebruik If not match en selecteer _local:impersonation_check_passed. Stel Error in op access_denied en Error message op You are not allowed to impersonate another user.
Query internal user: laad het target. Gebruik Replace claim, stel Lookup claim in op _local:impersonation_target_id, Lookup claim on internal user op sub, Claims from internal user op * en Target op target. De zoekopdracht vergelijkt de interne gebruikers-ID en laadt de claims van de gebruiker, inclusief doorgestuurde Access Structure claims en lokale hulpclaims, onder _local:target:. Zo worden bijvoorbeeld _local:target:sub en _local:target:_local:internal_user_id geleverd.
Impersonation: selecteer het geladen target. Gebruik Replace claim en stel Target in op target.
Map: bewaar het target voor latere aanmeldingen. Gebruik Replace claim, stel Select claim in op _local:target:_local:internal_user_id en New claim op _session:impersonation_target_id. Hierdoor wordt de stabiele ID van de geladen gebruiker opgeslagen als verwijzing voor de volgende aanmelding.

Claimtransformaties van het tweede niveau 5–8: wijs onbevoegde selecties af, laad en impersoneer de interne gebruiker en bewaar de targetverwijzing

Als uw beleid beperkt welke gebruikers mogen worden geïmpersoneerd, voegt u de targetcontroles tussen stap 6 en 7 toe. Controleer bijvoorbeeld _local:target:role of de Access Structure hulpclaim _local:target:_local:access_node.

Als de zoekopdracht geen target oplevert, worden deze acht stappen zonder impersonatie voltooid en blijft een eerder opgeslagen targetverwijzing behouden. Voeg na de zoekopdracht een voorwaardelijke fouttaak toe als een niet-beschikbaar target de aanmelding moet afwijzen, of verwijder expliciet de sessieclaim als de opgeslagen selectie moet worden gewist.

Impersonatie voortzetten en wijzigen

Iedere applicatieaanmelding voert de transformaties van de authenticatiemethode opnieuw uit. In het bovenstaande voorbeeld lezen de transformaties de targetverwijzing uit _session:impersonation_target_id wanneer _local:params:impersonation_target_id ontbreekt, laden de actuele targetclaims en herhalen de rechtencontroles voordat impersonatie wordt geselecteerd. De opgeslagen verwijzing blijft gebonden aan de oorspronkelijk geauthenticeerde gebruiker en dezelfde authenticatiemethode.

Selecteer een ander target door een nieuwe verwijzing via de aanvraagparameter mee te geven en de opgeslagen sessieclaim te vervangen nadat het nieuwe target de controles heeft doorstaan. Beëindig impersonatie door de opgeslagen verwijzing te wissen en de transformaties zonder geldig impersonatietarget te voltooien.

Een geslaagde voltooiing met hetzelfde target behoudt de sid. Een ander target selecteren, impersonatie starten of zonder geldig target voltooien maakt een nieuwe sid aan en trekt de eerdere actieve sessie en refresh token grants in.

UserInfo en het inwisselen van grants wijzen een ingetrokken actieve sessie af. Applicaties en API's die tokens lokaal valideren, moeten hun eigen regels voor sessies en tokenlevensduur blijven toepassen. SAML single logout gebruikt de uitgiftewaarden die voor iedere applicatie zijn vastgelegd.

Actieve sessies en refresh token grants tonen het geïmpersoneerde subject en de oorspronkelijke actor in de Control Client en Control API. Auditevents voor aanmeldingen bevatten de actor. Afzonderlijke impersonatie-auditevents registreren start, wijziging en beëindiging, inclusief vorige en huidige sessie-ID's.