Claim Transforms und Claim Tasks

Jede FoxIDs Authentifizierungsmethode und Anwendungsregistrierung verarbeitet Claims und unterstützt Claim Transforms und Claim Tasks. Das bedeutet, dass mehrere Sätze von Claim Transforms und Claim Tasks für jede Benutzerauthentifizierung ausgeführt werden können. Zuerst werden Claim Transforms und Claim Tasks an der Authentifizierungsmethode ausgeführt und danach an der Anwendungsregistrierung.

Zusätzliche Teilmengen von Claim Transforms und Claim Tasks können ausgeführt werden, wenn ein Benutzer oder ein externer Benutzer erstellt wird.

Claim transform flow diagram

Wenn Sie mit einem First Level Claim Transform oder Claim Task ein neues Claim erstellen, ist das Claim lokal für die Authentifizierungsmethode, außer bei einer Login Authentifizierungsmethode. In einer Authentifizierungsmethode wird das Claim weitergeleitet, wenn der Claim Typ zur Liste Forward claims hinzugefügt wird oder wenn * (Standard) in der Liste enthalten ist.

Wenn Sie mit einem Claim Transform oder Claim Task ein neues Claim erstellen, ist das Claim lokal für die Anwendungsregistrierung. In einer Anwendungsregistrierung müssen Sie das Claim oder * zur Liste Issue claims hinzufügen. Alternativ können Sie bei OpenID Connect das Claim zur Liste Voluntary claims eines Scopes hinzufügen und den Scope von Ihrer Anwendung anfordern.

Bitte sehen Sie die Claim Transform Beispiele.

Aktivieren Sie Log claim trace in den Log settings, um die Claims vor und nach der Transformation in den Logs zu sehen.

Claim Transforms können in einer Login Authentifizierungsmethode konfiguriert werden.

FoxIDs authentication method claim transform

Und Claim Tasks.

FoxIDs authentication method claim task

Ebenso können Claim Transforms und Claim Tasks als First Level und Second Level in einer OpenID Connect Authentifizierungsmethode konfiguriert werden.

FoxIDs application registration claim transform

Claims werden standardmäßig als JWT Claims dargestellt. Wenn die Authentifizierungsmethode SAML 2.0 ist, werden die First Level Claims als SAML 2.0 Claims dargestellt. Wenn die Anwendungsregistrierung SAML 2.0 ist, werden die Claims als SAML 2.0 Claims dargestellt.

Ein Claim Transform und Claim Task führt eine von bis zu sieben verschiedenen Aktionen aus, abhängig vom jeweiligen Typ.

Claim Transform und Claim Task Aktionen:

Add claim - neues Claim hinzufügen
Add claim, if not match - Add Aktion ausführen, wenn die Bedingung nicht zutrifft
Replace claim - neues Claim hinzufügen und bestehende Claims entfernen, wenn eine oder mehrere vorhanden sind
Replace claim, if not match - Replace Aktion ausführen, wenn die Bedingung nicht zutrifft
Remove claim - Claims entfernen, wenn eine oder mehrere vorhanden sind
If match - Aktion ausführen, wenn die Bedingung zutrifft
If not match - Aktion ausführen, wenn die Bedingung nicht zutrifft

Claim Transforms und Claim Tasks werden in der Reihenfolge ausgeführt, und die Aktionen werden daher in der Reihenfolge ausgeführt. Das bedeutet, dass es möglich ist, eine lokale Variable zu erstellen, indem ein Claim hinzugefügt wird und später in der Sequenz Entscheidungen auf Basis des Claims getroffen werden. Ein Claim ist lokal im Claim Transforms und Claim Tasks Satz, wenn es mit _local: beginnt.

Wenn Claim Transforms und Claim Tasks in einem Login Flow laufen, fügt FoxIDs automatisch lokale Claims aus der Login Request hinzu, bevor die Transformationen ausgeführt werden. Diese _local: Claims sind für Entscheidungen innerhalb der Transform Task Sequenz gedacht und werden aus dem Output entfernt.

Lokale Claims, die in AddLocalClaims hinzugefügt werden:

_local:login_action - Login Request Aktion, gespeichert als camelCase
_local:user_id - Login Request User ID (nur wenn angegeben)
_local:max_age - Login Request max age (nur wenn gesetzt und größer als 0)
_local:login_hint - Login Request hint (nur wenn angegeben)
_local:acr - Login Request ACR Werte als space delimited Liste (nur wenn angegeben)

Mit der Aktion Add claim, if not match ist es möglich, ein Claim (lokale Variable) hinzuzufügen, wenn ein anderes Claim oder ein Claim Wert nicht existiert.

Claim Transform Typen, die alle Aktionen unterstützen:

Match claim - Aktion ausführen, wenn der Claim Typ übereinstimmt
Match claim and value - Aktion ausführen, wenn der Claim Typ und der Claim Wert übereinstimmen
Regex match - Aktion ausführen, wenn der Claim Typ übereinstimmt und der Claim Wert dem Regex entspricht

Claim Transform Typen, die Add claim, Replace claim und Add claim, if new claim does not exist unterstützen:

Map - Aktion ausführen, wenn der Claim Typ übereinstimmt, dann den Claim Wert auf ein neues Claim abbilden
Regex map - Aktion ausführen, wenn der Claim Typ übereinstimmt und der Claim Wert der Regex Gruppe entspricht, dann den Gruppenwert auf ein neues Claim abbilden

Claim Transform Typen, die Add claim und Replace claim unterstützen:

Constant - Aktion immer ausführen (Claim mit konstantem Wert hinzufügen oder ersetzen)
Concatenate - Aktion ausführen, wenn ein oder mehrere Claim Typen übereinstimmen, dann die Claim Werte zu einem neuen Claim zusammenführen
External claims API - ein externes API mit den ausgewählten Claims aufrufen, um Claims mit externen Claims hinzuzufügen oder zu ersetzen
DK XML privilege to JSON - DK privilege zu JSON konvertieren.

Claim Task Typen, die Add claim und Replace claim unterstützen:

Query internal user - Claim abgleichen und genau einen internen Benutzer basierend auf dem Claim Wert finden. Die Anfrage schlägt fehl, wenn mehr als ein Benutzer gefunden wird. Danach die Claims des Benutzers hinzufügen oder ersetzen.
Query external user - Claim abgleichen und genau einen externen Benutzer basierend auf dem Claim Wert finden. Die Anfrage schlägt fehl, wenn mehr als ein Benutzer gefunden wird. Danach die Claims des Benutzers hinzufügen oder ersetzen.

Claim Task Typen, die If match und If not match unterstützen:

Match claim and return error - Fehler zurückgeben, wenn der Claim Typ übereinstimmt oder nicht übereinstimmt.
Match claim and value and return error - Fehler zurückgeben, wenn Claim Typ und Claim Wert übereinstimmen oder nicht übereinstimmen.
Regex match and return error - Fehler zurückgeben, wenn Claim Typ und Claim Wert dem Regex entsprechen oder nicht entsprechen.
Match claim and start authentication - neuen Login Flow starten, indem eine Authentifizierungsmethode initiiert wird, wenn der Claim Typ übereinstimmt oder nicht übereinstimmt.
Match claim and value and start authentication - neuen Login Flow starten, indem eine Authentifizierungsmethode initiiert wird, wenn Claim Typ und Claim Wert übereinstimmen oder nicht übereinstimmen.
Regex match and start authentication - neuen Login Flow starten, indem eine Authentifizierungsmethode initiiert wird, wenn Claim Typ übereinstimmt und Claim Wert dem Regex entspricht oder nicht entspricht.

Die Start Authentication Claim Tasks können für Step up genutzt werden, wenn der Benutzer mit einem Faktor angemeldet ist und ein weiterer Faktor erforderlich ist, oder wenn zusätzliche Informationen (Claims) erforderlich sind.

External claims - API

Sie können Ihr eigenes API von FoxIDs über eine Claim Transformation aufrufen. Das API wird mit Claims aufgerufen und die vom API zurückgegebenen Claims können mit einer Add oder Replace Aktion hinzugefügt werden. Das API wird nur aufgerufen, wenn mindestens ein ausgewähltes Claim existiert. Sie können * verwenden, um alle Claims auszuwählen und an Ihr API zu senden.

Use case Szenarien:

Rufen Sie Ihr API aus einer Authentifizierungsmethode auf, jedes Mal wenn ein Benutzer entweder in FoxIDs oder bei einem externen identity provider authentifiziert wird. Sie können den Benutzer in Ihrer Datenbank finden und eine User ID und vielleicht eine Customer ID oder anderes Relevantes zurückgeben. Sie können den Benutzer auch in Ihrer Datenbank erstellen.
Rufen Sie Ihr API aus einer Anwendungsregistrierung mit der User ID (sub) auf und fragen Sie die Rollen des Benutzers in Ihrer Datenbank ab. Ihr API würde dann entweder eine leere Liste oder eine Liste von Role Claims oder möglicherweise eine komplexere Berechtigungsstruktur zurückgeben.

API implementieren

Sie müssen ein einfaches API implementieren, das FoxIDs aufruft, wenn die Claim Transformation ausgeführt wird. Bitte schauen Sie sich den Sample Code an.

Das API hat eine Base URL und die Funktionalität ist in Ordner unterteilt. Derzeit wird nur der Ordner claims (Funktionalität) zur Anforderung einer Liste von Claims unterstützt.

Wenn die Base URL des API https://somewhere.org/myclaimsstore ist, lautet die URL für den Ordner claims https://somewhere.org/myclaimsstore/claims.

FoxIDs Cloud ruft Ihr API von der IP Adresse 57.128.60.142 auf. Die ausgehende IP Adresse kann sich ändern und weitere können im Laufe der Zeit hinzugefügt werden.

Request

Gesichert mit HTTP Basic auth: Benutzername external_claims, Passwort = konfiguriertes Secret.

Das API wird mit HTTP POST und einem JSON Body aufgerufen.

Dies ist ein Request JSON Body mit zwei Input Claims:

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

Response - Success

Bei Erfolg muss das API HTTP Status 200 zurückgeben und eine Liste von claims (die Liste kann leer sein).

Beispielsweise die sub des Benutzers (User ID / Username), Customer ID und 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

Das API muss HTTP Status 401 (Unauthorized) und einen error (required) zurückgeben, wenn Basic auth abgelehnt wird. Optional kann eine Fehlerbeschreibung in ErrorMessage hinzugefügt werden.

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

Wenn andere Fehler auftreten, sollte das API HTTP Status 500 oder einen anderen passenden Fehlercode zurückgeben. Es wird empfohlen, eine technische Fehlermeldung in ErrorMessage für Diagnosezwecke hinzuzufügen (sie wird nur geloggt und nie dem Endbenutzer angezeigt).

Fehlermeldungen vom API in ErrorMessage werden NICHT dem Benutzer angezeigt; sie werden nur geloggt.

API Sample

Das Sample ExternalClaimsApiSample zeigt, wie das API in ASP.NET Core implementiert wird.

Sie können diese Postman collection verwenden, um Ihr API mit Postman aufzurufen und zu testen.

Configure

Konfigurieren Sie FoxIDs so, dass Ihr API über eine Claim Transformation im FoxIDs Control Client aufgerufen wird.

Navigieren Sie zum Abschnitt Claim Transform
Klicken Sie Add claim transform
Klicken Sie External claims API
Wählen Sie Add claim oder Replace claim
Fügen Sie die ausgewählten Claims z. B. sub in Select claims hinzu
Fügen Sie die Base API URL ohne den Ordner claims in API URL hinzu
Fügen Sie das API secret hinzu
Klicken Sie Update

Claim Transform Beispiele

`name` Claim in die zwei Claims `given_name` und `family_name` aufteilen

Die Transformation teilt den Wert im name Claim beim ersten Leerzeichen und fügt die given_name und family_name Claims hinzu, falls sie nicht bereits existieren. Wenn mehr als ein Leerzeichen im name Claim Wert enthalten ist, werden keine neuen given_name und family_name Claims hinzugefügt, da sie bereits existieren.

Verwenden Sie zwei Regex map Claim Transformationen.

Transform name to given_name and family_name

Den family_name Claim Wert mit Regex ^\S+\s(?<map>\S+)$ finden
Den given_name Claim Wert mit Regex ^(?<map>\S+)\s\S+$ finden

Standardmäßig hinzugefügten Authentifizierungsmethode Namen aus `sub` entfernen

Der Name der Authentifizierungsmethode wird standardmäßig dem sub Claim Wert als Prefix mit Pipe z. B. some-auth-method|my-external-user-id hinzugefügt.

Sie können ein Replace Claim auf dem sub Claim verwenden, um den standardmäßig hinzugefügten Prefix zu entfernen.

Die Transformation teilt den Wert im sub Claim und ersetzt das Claim mit einem neuen sub, das nur die ursprüngliche ID enthält.

Verwenden Sie eine Regex map Claim Transformation und wählen Sie die Replace claim Aktion.

Remove default added post authentication method name

Finden Sie die ID ohne den standardmäßig hinzugefügten post authentication method Namen mit Regex ^(nemlogin\|)(?<map>.+)$

Sie können dasselbe in einer SAML 2.0 Authentifizierungsmethode mit dem Claim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier (enthält den SAML 2.0 Authn Response NameID Wert) anstelle des sub Claims durchführen.

`email` mit `_local:mfa:email` vergleichen und `amr` hinzufügen

Das Beispiel vergleicht die email des aktuell authentifizierten Benutzers mit der email des bereits authentifizierten MFA-Benutzers _local:mfa:email. Wenn beide Email Werte gleich sind und per Regex match übereinstimmen, wird der amr Claim mit dem Namen der Authentifizierungsmethode als Wert hinzugefügt (der Name der Authentifizierungsmethode ist als amr Wert konfiguriert).

Verwenden Sie eine Concatenate Claim Transformation gefolgt von einer Regex match Claim Transformation.

Email vergleichen und amr hinzufügen

Concatenate: Neuer Claim _local:compare_emails, Aktion Replace claim, concatenate claims email und _local:mfa:email, concatenate format string {0}|{1}.
Regex match: Neuer Claim amr, Aktion Replace claim, select claim _local:compare_emails, regex value match ^([^|]+)\|\1$, neuer Wert auf den Namen der Authentifizierungsmethode gesetzt (zum Beispiel 9fk5z3vg).