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.

Als je een nieuwe claim maakt met een first level claim transform of claim task, is de claim lokaal voor de authenticatiemethode, behalve bij een Login authenticatiemethode. In een authenticatiemethode wordt de claim doorgestuurd als de claim type is toegevoegd aan de Forward claims lijst, of als * (standaard) in de lijst is opgenomen.

Als je een nieuwe claim maakt met een claim transform of claim task, is de claim lokaal voor de app registratie. In een app registratie moet je de claim of * toevoegen aan de Issue claims lijst. Als alternatief, voor OpenID Connect, voeg de claim toe aan de Voluntary claims lijst van een scope en vraag de scope aan vanuit je applicatie.

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.

En claim tasks.

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

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.

Lokale claims toegevoegd in AddLocalClaims:

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

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 - voer de actie uit als de claim type overeenkomt
• Match claim and value - voer de actie uit als de claim type en claim waarde overeenkomen
• Regex match - voer de actie uit als de claim type overeenkomt en de claim waarde overeenkomt met de regex

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

• Map - voer de actie uit als de claim type overeenkomt, map daarna de claim waarde naar een nieuwe claim
• Regex map - voer de actie uit als de claim type overeenkomt en de claim waarde overeenkomt met de regex groep, map daarna de groepswaarde naar een nieuwe claim

Claim transform typen die Add claim en Replace claim ondersteunen:

• Constant - voer de actie altijd uit (voeg vervang een claim met een constante waarde)
• Concatenate - voer de actie uit als één of meer claim typen overeenkomen, concateneer daarna de claim waarden naar een nieuwe claim
• External claims API - roep een extern API aan met de geselecteerde claims om claims toe te voegen of te vervangen met externe claims
• DK XML privilege to JSON - converteer DK privilege naar JSON.

Claim task typen die Add claim en Replace claim ondersteunen:

• Query internal user - match de claim en vind precies één interne gebruiker op basis van de claim waarde. De request faalt als er meer dan één gebruiker wordt gevonden. Voeg vervang daarna de claims van de gebruiker.
• Query external user - match de claim en vind precies één externe gebruiker op basis van de claim waarde. De request faalt als er meer dan één gebruiker wordt gevonden. Voeg vervang daarna de claims van de gebruiker.

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

• Match claim and return error - geef een fout terug als de claim type overeenkomt of niet overeenkomt.
• Match claim and value and return error - geef een fout terug als de claim type en claim waarde overeenkomen of niet overeenkomen.
• Regex match and return error - geef een fout terug als de claim type en claim waarde overeenkomen of niet overeenkomen met de regex.
• Match claim and start authentication - start een nieuwe login flow door een authenticatiemethode te initiëren als de 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 de claim type en claim waarde overeenkomen of niet overeenkomen.
• Regex match and start authentication - start een nieuwe login flow door een authenticatiemethode te initiëren als de claim type overeenkomt en de claim waarde overeenkomt of niet overeenkomt met de regex.

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.

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.

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.

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

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.

1. Navigeer naar de sectie Claim Transform
2. Klik Add claim transform
3. Klik External claims API
4. Selecteer Add claim of Replace claim
5. Voeg de geselecteerde claims toe, bijvoorbeeld sub, in Select claims
6. Voeg de base API URL zonder de claims map toe in API URL
7. Voeg het API secret toe
8. 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.

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

Zoek de ID zonder de standaard toegevoegde post authentication method naam met regex ^(nemlogin\|)(?<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.