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.

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.

Und Claim Tasks.

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

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 - prüft, ob der ausgewählte Claim Typ vorhanden ist. Bei Add- und Replace-Aktionen wird der ausgehende Claim mit dem neuen Wert geschrieben, wenn der Claim vorhanden ist. if not match-Aktionen werden ausgeführt, wenn der Claim fehlt. Eine Remove-Aktion entfernt den ausgewählten ausgehenden Claim, wenn der Claim vorhanden ist.
• Match claim and value - prüft, ob der ausgewählte Claim Typ mit dem konfigurierten Wert vorhanden ist. Bei Add- und Replace-Aktionen wird der ausgehende Claim mit dem neuen Wert geschrieben, wenn Claim Typ und Wert übereinstimmen. if not match-Aktionen werden ausgeführt, wenn der Claim vorhanden ist, der Wert aber nicht übereinstimmt. Eine Remove-Aktion entfernt den ausgewählten ausgehenden Claim, wenn Claim Typ und Wert übereinstimmen.
• Regex match - prüft, ob der ausgewählte Claim Typ vorhanden ist und der Claim Wert dem konfigurierten regulären Ausdruck entspricht. Bei Add- und Replace-Aktionen wird der ausgehende Claim mit dem neuen Wert geschrieben, wenn der reguläre Ausdruck übereinstimmt. if not match-Aktionen werden ausgeführt, wenn der Claim vorhanden ist, der Wert aber nicht dem regulären Ausdruck entspricht. Eine Remove-Aktion entfernt den ausgewählten ausgehenden Claim, wenn der reguläre Ausdruck übereinstimmt.

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

• Map - kopiert den ausgewählten Claim Wert in den ausgehenden Claim. Mit Add claim, if new claim does not exist wird der Wert nur geschrieben, wenn der ausgehende Claim noch nicht vorhanden ist.
• Regex map - extrahiert die benannte Regex Gruppe map aus dem ausgewählten Claim Wert und schreibt den extrahierten Wert in den ausgehenden Claim. Mit Add claim, if new claim does not exist wird der Wert nur geschrieben, wenn der ausgehende Claim noch nicht vorhanden ist.

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

• Constant - schreibt immer den konfigurierten konstanten Wert in den ausgehenden Claim.
• Concatenate - erstellt den ausgehenden Claim aus Werten der ausgewählten Claims. Der Formatstring verwendet Platzhalter wie {0}, {1} und {2} für die ausgewählten Claim Werte in Reihenfolge.
• External claims API - sendet ausgewählte Claims an ein externes API. Vom API zurückgegebene Claims werden hinzugefügt oder ersetzen ausgehende Claims.
• DK XML privilege to JSON - konvertiert einen DK privilege XML Claim zu JSON Claims, einen Claim für jedes PrivilegeGroup XML Element.

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

• Query internal user - verwendet den Lookup Claim Wert, um genau einen internen Benutzer zu finden, und fügt danach ausgewählte Claims dieses internen Benutzers im aktuellen Claim Set hinzu oder ersetzt sie.
• Query external user - verwendet den Lookup Claim Wert, um genau einen externen Benutzer zu finden, und fügt danach ausgewählte Claims dieses externen Benutzers im aktuellen Claim Set hinzu oder ersetzt sie.
• Save claim on internal user - verwendet den Lookup Claim Wert, um genau einen internen Benutzer zu finden, und fügt danach den ausgewählten Claim auf diesem internen Benutzer mit Werten aus dem ausgewählten Update Value Claim im aktuellen Claim Set hinzu oder ersetzt ihn.
• Save claim on external user - verwendet den Lookup Claim Wert, um genau einen externen Benutzer zu finden, und fügt danach den ausgewählten Claim auf diesem externen Benutzer mit Werten aus dem ausgewählten Update Value Claim im aktuellen Claim Set hinzu oder ersetzt ihn.

Bei Query internal user und Save claim on internal user wird der Lookup Claim aus dem aktuellen Claim Set gelesen. Der Wert Lookup claim on internal user definiert, wie der interne Benutzer abgeglichen wird:

• sub entspricht der User ID des internen Benutzers.
• email, phone_number und preferred_username suchen zuerst in den Identifiers des internen Benutzers mit einem Abgleich ohne Beachtung der Groß-/Kleinschreibung, sofern Groß-/Kleinschreibung relevant ist. Wenn kein Benutzer über einen Identifier gefunden wird, wird die Suche in den gespeicherten Claims des Benutzers fortgesetzt.
• Die Suche wird danach in den gespeicherten Claims des internen Benutzers nach demselben Claim Typ und einem Wert fortgesetzt, der ohne Beachtung der Groß-/Kleinschreibung übereinstimmt. Das gilt für alle Lookup Claim Typen, wenn zuerst kein Benutzer gefunden wurde.

Wenn die Suche genau einen internen Benutzer findet, fügt Query internal user ausgewählte Claims dieses Benutzers im aktuellen Claim Set hinzu oder ersetzt sie. Save claim on internal user fügt den ausgewählten Claim auf diesem Benutzer mit Werten aus dem ausgewählten Update Value Claim hinzu oder ersetzt ihn. Wenn kein Benutzer gefunden wird oder wenn über Claims mehr als ein Benutzer gefunden wird, werden keine internen Benutzerclaims hinzugefügt oder gespeichert.

Bei Query external user und Save claim on external user wird der Lookup Claim aus dem aktuellen Claim Set gelesen und gegen die ausgewählte externe Benutzerquelle abgeglichen. Verwenden Sie link_claim als Lookup Claim auf dem externen Benutzer, um über den Link Claim Wert des externen Benutzers abzugleichen.

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

• Match claim and return error - gibt einen Fehler zurück, wenn der Claim Typ übereinstimmt oder nicht übereinstimmt.
• Match claim and value and return error - gibt einen Fehler zurück, wenn Claim Typ und Claim Wert übereinstimmen oder nicht übereinstimmen.
• Regex match and return error - gibt einen Fehler zurück, wenn Claim Typ und Claim Wert dem regulären Ausdruck entsprechen oder nicht entsprechen.
• Match claim and log event - schreibt den ausgewählten Claim Wert in das Log, wenn der Claim Typ übereinstimmt.
• Match claim and start authentication - startet einen neuen Login Flow durch Initiieren einer Authentifizierungsmethode, wenn der Claim Typ übereinstimmt oder nicht übereinstimmt.
• Match claim and value and start authentication - startet einen neuen Login Flow durch Initiieren einer Authentifizierungsmethode, wenn Claim Typ und Claim Wert übereinstimmen oder nicht übereinstimmen.
• Regex match and start authentication - startet einen neuen Login Flow durch Initiieren einer Authentifizierungsmethode, wenn Claim Typ und Claim Wert dem regulären Ausdruck entsprechen oder nicht entsprechen.

Für Return Error Tasks wird der Protokollfehler konfiguriert, der an den Client oder Requester zurückgegeben wird. OpenID Connect und OAuth 2.0 Konfigurationen geben einen Error und optional eine Error Description zurück. SAML 2.0 Konfigurationen geben einen SAML Statuscode und eine Message zurück.

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.

1. Navigieren Sie zum Abschnitt Claim Transform
2. Klicken Sie Add claim transform
3. Klicken Sie External claims API
4. Wählen Sie Add claim oder Replace claim
5. Fügen Sie die ausgewählten Claims z. B. sub in Select claims hinzu
6. Fügen Sie die Base API URL ohne den Ordner claims in API URL hinzu
7. Fügen Sie das API secret hinzu
8. 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.

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

Finden Sie die ID ohne den standardmäßig hinzugefügten post authentication method Namen mit Regex ^([^|]+)\|(?<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.

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