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.

Om du skapar en ny claim med en first level claim transform eller claim task, är claimen lokal för autentiseringsmetoden, utom för en Login autentiseringsmetod. I en autentiseringsmetod vidarebefordras claimen om claim typen läggs till i listan Forward claims, eller om * (standard) ingår i listan.

Om du skapar en ny claim med en claim transform eller claim task, är claimen lokal för applikationsregistreringen. I en applikationsregistrering måste du lägga till claimen eller * i listan Issue claims. Alternativt, för OpenID Connect, lägg claimen till ett scopes lista Voluntary claims och begär scopet från din applikation.

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.

Och claim tasks.

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

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.

Lokala claims tillagda i AddLocalClaims:

• _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)

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 - utför åtgärden om claim typen matchar
• Match claim and value - utför åtgärden om claim typen och claim värdet matchar
• Regex match - utför åtgärden om claim typen matchar och claim värdet matchar regex

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

• Map - utför åtgärden om claim typen matchar, mappa sedan claim värdet till en ny claim
• Regex map - utför åtgärden om claim typen matchar och claim värdet matchar regex gruppen, mappa sedan gruppvärdet till en ny claim

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

• Constant - utför åtgärden alltid (lägg till ersätt en claim med ett konstant värde)
• Concatenate - utför åtgärden om en eller flera claim typer matchar, concatenera claim värdena till en ny claim
• External claims API - kalla ett externt API med de valda claims för att lägga till eller ersätta claims med externa claims
• DK XML privilege to JSON - konvertera DK privilege till JSON.

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

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

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

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.

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.

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.

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

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.

1. Navigera till Claim Transform sektionen
2. Klicka Add claim transform
3. Klicka External claims API
4. Välj Add claim eller Replace claim
5. Lägg till de valda claims t.ex. sub i Select claims
6. Lägg till base API URL utan mappen claims i API URL
7. Lägg till API secret
8. 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.

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

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 jämför den aktuellt autentiserade användarens email med den redan autentiserade MFA-användarens _local:mfa:email. Om de två email värdena är lika och matchas med ett regex match, läggs amr claimet till med autentiseringsmetodens namn som värde (autentiseringsmetodens namn är konfigurerat som amr värde).

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

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