Iru Query Language

Wenn Sie zuordnen, was eine Anwendung bei der Anmeldung erhält (das Subject (NameID) für eine SAML-App oder Subject und Claims für eine OIDC-App), ist jeder Wert ein IQL-Ausdruck. Mit IQL können Sie Daten aus dem Profil eines Benutzers abrufen und den Wert umformen, bevor er gesendet wird.

IQL (Iru Query Language) ist die Ausdruckssprache von Iru für Zuordnungen und wird an mehreren Stellen verwendet:

Die Attribute und Claims, die eine Anwendung bei der Anmeldung erhält.
Die Felder, die eine verbundene Quelle Ihrem Verzeichnis zuordnet (siehe Attributzuordnung).
Auto Group-Regeln und Listenfilter.

Dieselbe Syntax funktioniert überall, wo IQL vorkommt.IQL basiert auf CEL (Common Expression Language), dem offenen Standard für Ausdruckssprachen, sodass jeder in CEL gültige Ausdruck auch in IQL gültig ist.

Während der Eingabe schlägt der Zuordnungseditor die verfügbaren Felder, Funktionen und Operatoren vor und zeigt eine Live-Vorschau des Ergebnisses. Ein Ausdruck muss im Editor und erneut beim Speichern die Typprüfung bestehen, sodass Fehler sichtbar werden, bevor sie jemals eine Anmeldung oder Synchronisierung erreichen.

Auf Ihre Daten verweisen

Worauf Sie verweisen, hängt davon ab, wo der Ausdruck ausgeführt wird:

Anwendungszuordnung beginnt beim Objekt user, dessen Felder die Profilattribute Ihres Verzeichnisses sind:
user.email user.username user.id
Die Standardwerte spiegeln dies wider: Das Subject einer OIDC-App ist standardmäßig user.id, und das Subject einer SAML-App ist standardmäßig user.username.
Directory Sync-Zuordnung verweist auf die Feldnamen der Quelle. Ein gültiger IQL-Bezeichner wird direkt so geschrieben, wie er aus dem verbundenen System kommt. Er beginnt mit einem ASCII-Buchstaben oder Unterstrich, und der Rest besteht aus ASCII-Buchstaben, Ziffern und Unterstrichen:
email_work first_name
Jeder andere Name wird über seinen exakten Namen aus __source gelesen. Dazu gehören Leerzeichen, Symbole, ein Punkt innerhalb eines einzelnen Feldnamens, Zeichen außerhalb von ASCII und IQL-Schlüsselwörter. Zum Beispiel __source["Email - Work"]. Siehe Werte mit IQL transformieren.

Bei Feldnamen wird die Groß-/Kleinschreibung beachtet. Auf verschachtelte Werte greifen Sie mit einem Punkt zu (user.profile.team), auf eine Liste oder Map mit [...] (siehe unten).

Bausteine

Form	Beispiel	Bedeutung
Feld / Variable	`first_name`, `user.email`	Ein Wert nach Name oder ein Feld eines Werts.
Methodenaufruf	`user.email.upperAscii()`	Eine Funktion, die auf einem Wert aufgerufen wird.
Indizierung	`parts[0]`	Ein Element einer Liste nach nullbasierter Position.
Map-Schlüssel	`entry["label"]`	Der unter einem Zeichenfolgenschlüssel gespeicherte Wert.
Gruppierung	`(a + b) * c`	Klammern zur Steuerung der Auswertungsreihenfolge.

Literale

"hello"                             // string (double quotes)
'hello'                             // string (single quotes)
42                                  // whole number
3.14                                // decimal number
true   false                        // booleans
null                                // null
["a", "b", "c"]                     // list
{"label": "work", "primary": true}  // map (string keys)

Zeichenfolgen unterstützen die üblichen Escape-Sequenzen wie \n, \t, \\, \" und \uXXXX.

Operatoren

Arithmetik
Vergleich
Logisch
Mitgliedschaft und Auswahl

Operator	Beispiel	Funktion
`+`	`first_name + " " + last_name`	Addiert Zahlen oder verkettet Zeichenfolgen.
`-` `*` `/`	`a * b`	Subtrahieren, multiplizieren, dividieren.
`%`	`a % b`	Rest (Modulo).

Operator	Beispiel	Funktion
`==` `!=`	`user.domain == "acme.com"`	Gleich, ungleich.
`<` `<=` `>` `>=`	`user.level >= 3`	Größenvergleiche.

Operator	Beispiel	Funktion
`&&`	`a && b`	Und.
`\|\|`	`a \|\| b`	Oder.
`!`	`!a`	Nicht.

Operator	Beispiel	Funktion
`in`	`user.domain in ["acme.com", "acme.io"]`	Wahr, wenn der Wert in einer Liste oder ein Schlüssel in einer Map enthalten ist.
`? :`	`name != "" ? name : "unknown"`	Bedingung: einen oder einen anderen Wert wählen.

Rangfolge

Von der stärksten zur schwächsten Bindung. Setzen Sie im Zweifel Klammern.

1) a.b   a()   a[i]   ()      // member access, calls, indexing, grouping
2) !a    -a                   // unary not, negation
3) *  /  %                    // multiply, divide, remainder
4) +  -                       // add, subtract (and string +)
5) <  <=  >  >=  in           // comparison and membership
6) ==  !=                     // equality
7) &&                         // and
8) ||                         // or
9) ? :                        // conditional

Zeichenfolgenfunktionen

Zeichenfolgenoperationen werden als Methoden auf einem Wert geschrieben, in der Form value.method(...):

Methode	Beispiel	Funktion
`upperAscii` / `lowerAscii`	`user.email.lowerAscii()`	Wandelt den Wert in Groß- oder Kleinbuchstaben um.
`trim`	`first_name.trim()`	Entfernt umgebende Leerzeichen.
`split`	`user.email.split("@")`	Teilt anhand eines Trennzeichens in eine Liste auf; indizieren Sie sie mit `[n]`.
`replace`	`phone.replace("-", "")`	Ersetzt jedes Vorkommen einer Teilzeichenfolge durch eine andere.
`contains`	`user.email.contains("+")`	Wahr, wenn der Wert eine Teilzeichenfolge enthält.
`startsWith` / `endsWith`	`user.email.endsWith("@acme.com")`	Prüft, wie der Wert beginnt oder endet.
`indexOf`	`username.indexOf(".")`	Position einer Teilzeichenfolge oder `-1`, wenn nicht vorhanden.
`matches`	`user.email.matches("^[a-z]+@acme\\.com$")`	Wahr, wenn der Wert einem regulären Ausdruck entspricht.
`size`	`user.email.split("@").size()`	Länge einer Zeichenfolge oder Liste. Auch als `size(value)` verfügbar.

Bedingungen und Standardwerte

Der Bedingungsoperator ist die einfachste Möglichkeit, einen Ersatzwert bereitzustellen, wenn ein Wert leer sein könnte:

// Use the first name, or fall back to the username when it's empty
user.firstName != "" ? user.firstName : user.username

Für eine umfassendere Behandlung von Null-Werten bietet IQL außerdem Optional-Hilfsfunktionen (Null-sicher), siehe unten.

Optionale Werte

Mit Optional-Hilfsfunktionen können Sie mit Werten arbeiten, die fehlen könnten, ohne einen Fehler zu verursachen. Ein Optional enthält entweder einen Wert oder ist leer.

Erstellen
Sicher zugreifen
Entpacken
Transformieren

optional.of(value)            // wrap a value as an optional
optional.ofNonZeroValue(value) // empty if the value is "zero" (see below)
optional.none()               // an empty optional

ofNonZeroValue behandelt Folgendes als leer: eine leere Zeichenfolge "", 0, false, eine leere Liste [], eine leere Map {} und null.

value.?field     // optional field access (yields an optional)
list[?i]         // optional index (empty instead of an error if out of range)

opt.hasValue()          // true if the optional holds a value
opt.value()             // the inner value (errors if empty)
opt.orValue(fallback)   // the value, or the fallback if empty
a.or(b)                 // the first of two optionals that has a value

opt.optMap(x, expr)      // transform the inner value if present, else stay empty
opt.optFlatMap(x, expr)  // like optMap, when expr itself returns an optional

// A default when a field is empty
optional.ofNonZeroValue(first_name).orValue("anon")

// Split an email and safely take the domain, falling back to ""
optional.ofNonZeroValue(email_work).optMap(e, e.split("@"))[?1].orValue("")

Kommentare und Leerzeichen

Leerzeichen sind nicht signifikant, und // leitet einen Kommentar ein, der bis zum Ende der Zeile reicht:

user.firstName + " " + user.lastName   // build a display name

Beispiele

// A field, as-is
user.email

// Upper-case the value
user.email.upperAscii()

// Build a display name from two fields
user.firstName + " " + user.lastName

// The local part of an email, before the "@"
user.email.split("@")[0]

// A field from the user's first address
user.addresses[0].city

// Choose a fallback when a field is blank
user.firstName != "" ? user.firstName : user.username

// A structured value, built as a map
{"email": user.email, "primary": true}

Verwenden Sie die Vorschau im Zuordnungseditor, um vor der Veröffentlichung zu bestätigen, dass ein Ausdruck das erwartete Ergebnis liefert; sie zeigt genau den Wert, den Iru senden oder speichern wird.

Nächste Schritte

Anwendungszuordnung

Ordnen Sie IQL-Werte der Assertion oder dem Token zu, die eine Anwendung erhält.

Attributzuordnung

Verwenden Sie dasselbe IQL, um eine verbundene Quelle Ihrem Verzeichnis zuzuordnen.

Automatische Gruppen

Steuern Sie die Gruppenmitgliedschaft mit IQL-Regeln über Profilattribute.

Profilattribute

Die user-Felder, auf die Ihre Ausdrücke zugreifen.

Erste Schritte

Verzeichnis

Anwendungen

Authentifizierung & Richtlinien

Administration

Architektur & Sicherheit

Leitfaden für Endbenutzer

Iru Query Language

Auf Ihre Daten verweisen

Bausteine

Literale

Operatoren

Rangfolge

Zeichenfolgenfunktionen

Bedingungen und Standardwerte

Optionale Werte

Kommentare und Leerzeichen

Beispiele

Nächste Schritte

Anwendungszuordnung

Attributzuordnung

Automatische Gruppen

Profilattribute

​Auf Ihre Daten verweisen

​Bausteine

​Literale

​Operatoren

​Rangfolge

​Zeichenfolgenfunktionen

​Bedingungen und Standardwerte

​Optionale Werte

​Kommentare und Leerzeichen

​Beispiele

​Nächste Schritte

Anwendungszuordnung

Attributzuordnung

Automatische Gruppen

Profilattribute

Auf Ihre Daten verweisen

Bausteine

Literale

Operatoren

Rangfolge

Zeichenfolgenfunktionen

Bedingungen und Standardwerte

Optionale Werte

Kommentare und Leerzeichen

Beispiele

Nächste Schritte