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 - matcha claimen och hitta exakt en intern användare baserat på claim värdet. Requesten misslyckas om fler än en användare hittas. Lägg till ersätt därefter användarens claims.
• Query external user - matcha claimen och hitta exakt en extern användare baserat på claim värdet. Requesten misslyckas om fler än en användare hittas. Lägg till ersätt därefter användarens claims.

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

• Match claim and return error - returnera ett fel om claim typen matchar eller inte matchar.
• Match claim and value and return error - returnera ett fel om claim typen och claim värdet matchar eller inte matchar.
• Regex match and return error - returnera ett fel om claim typen och claim värdet matchar eller inte matchar regex.
• Match claim and start authentication - starta ett nytt login flöde genom att initiera en autentiseringsmetod om claim typen matchar eller inte matchar.
• Match claim and value and start authentication - starta 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 - starta ett nytt login flöde genom att initiera en autentiseringsmetod om claim typen matchar och claim värdet matchar eller inte matchar regex.

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 ^(nemlogin\|)(?<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).