Erweiterungen

Das Zugriffsrechte-Format des security.manager NEXT erlaubt die Nutzung von Erweiterungspunkten, um die Anwendungsmöglichkeiten von Zugriffsrechten zu erweitern.

User Information Service

In security.manager NEXT können Sie den Namen und die Rollen der anfragenden Person als Nutzerattribute bei der Definition von Einschränkungen referenzieren. In manchen Situationen ist es jedoch hilfreich, in Einschränkungen auch solche Nutzerattribute zu referenzieren, die von anderen Komponenten Ihres Systems, zum Beispiel einem LDAP, zur Verfügung gestellt werden. Oftmals sind Personen dort Projekten oder anderen organisatorischen Einheiten zugeordnet, die Sie für die Definition von Einschränkungen wie hier angedeutet verwenden möchten:

{
    ...
    "restrictions": {
        "project_features_only": {
            "type": "feature",
            "query": "PROJECT_ID in ${user.projects}"
        }
    }
}

Die User Information Service-Erweiterung definiert eine REST Schnittstelle für Dienste, die von der SOI verwendet werden können, um zusätzliche Attribute für eine Person abzufragen. Indem Sie einen solchen Dienst bereitstellen, können Sie Berechtigungen definieren, die auf zusätzlichen Nutzerattributen beruhen. Im Beispiel oben stellt ein Dienst das projects-Attribut bereit.

Die Implementierung eines User Information Service kann außerdem Personen weitere Rollen zuordnen. Diese Rollen werden den regulären Rollen hinzugefügt, die einer Person bereits durch ArcGIS Enterprise Rollen (bzw. Gruppen) zugeordnet werden. Bei der Definition von Berechtigungen können die zusätzlichen Rollen dann wie üblich in der "roles"-Liste verwendet werden, um Zugriffsrechte an sie zu binden.

REST Service API

Der User Information Service ist eine zusätzliche Infrastrukturkomponente die Sie bereitstellen müssen. Der Dienst muss die API Spezifikation implementieren, die im OpenAPI-Format beschrieben ist.

API Überblick

Wenn diese Erweiterung für eine Zugriffsregel aktiviert ist, sendet die SOI eine HTTP POST-Anfrage für jede eingehende Kartendienst-Anfrage.

Die Anfrage an den User Information Service hat folgende Form:

Beispiel-Anfrage an den User Information Service

{
    "userId": "gisuser1",
    "anonymous": false,
    "roles": ["editor", "authenticated"]
}

Auf Basis dieser Informationen entscheidet der User Information Service, welche Daten über die angegebene Person er zurückgibt. Die Antwort enthält ein einzelnes "data"-Element, das die zusätzlichen Nutzerattribute und Nutzerrollen für die angefragte Person aufzählt:

Beispiel-Antwort eines User Information Service

{
    "data": {
        "projectIds": ["project_a", "Project_b"],
        "activeUser": true,
        "securityLevel": 42,
        "roles": ["x-role-department-a", "x-role-department-b"]
    }
}

Weitere Beispiele und Informationen finden Sie in der API Spezifikation

Implementierungserwägungen

Sobald die Erweiterung für einen Kartendienst aktiviert ist, sendet die SOI für jede eintreffende Nutzer-Anfrage eine Anfrage an den User Information Service. Die Ergebnisse der Anfrage werden von der SOI nicht zwischengespeichert, sodass bei der nächsten Anfrage wieder der User Information Service angefragt wird. Es liegt damit in der Verantwortung der Implementierung des User Information Service, Anfragen zu Nutzerattributen so schnell wie möglich zu beantworten und geeignete Caching-Verfahren zu implementieren, damit die eigentliche Anfrage an den Kartendienst möglichst wenig verzögert wird.

Beispielimplementierung

Eine Beispielimplementierung der Schnittstelle ist auf GitHub verfügbar.

Sie demonstriert die Integration externer Datenquellen

basierend auf einem LDAP Verzeichnisdienst, und
basierend auf Daten aus einer JSON-Datei.

Die Beispielimplementierung dient lediglich zur Veranschaulichung und ist nicht für den produktiven Einsatz geeignet. Sie können sie jedoch als Ausgangspunkt für Ihre eigene Entwicklung verwenden.

Konfiguration der Erweiterung

Wenn Sie zusätzliche Nutzerattribute in einem Zugriffsrecht referenzieren möchten, müssen Sie die User Information Service-Erweiterung zunächst im Abschnitt "extensions" einer Zugriffsrechte-Datei konfigurieren.

Für die Konfiguration nutzen Sie die folgenden Eigenschaften:

url: URL des User Information Service, der die zusätzlichen Nutzerattribute liefert.
enabled (optional): Aktiviert oder deaktiviert die Erweiterung.

Ist der Wert false, werden externe Nutzerattribute nicht abgefragt.

Default: true
insecure (optional): Akzeptieren oder Ablehnen von unsicheren HTTPS-Verbindungen zum User Information Service.

Falls true, werden auch Verbindungen mit Server-Zertifikaten, die nicht von einer bekannten Root CA ausgestellt wurden, akzeptiert.

Default: false
headers (optional): Liste von statischen HTTP Header-Feldern, die an den User Information Service gesendet werden.

Mithilfe dieser Eigenschaft können Sie z.B. Authentifizierung-Tokens festlegen, die an den User Information Service gesendet werden sollen. Stellen Sie in diesem Fall sicher, dass Sie für den User Information Service einen HTTPS-Endpunkt als url angeben.

Konfigurationsbeispiel

{
    "policies": [...],
    ...
    "extensions": {
        "userInfoService": {
            "url": "https://localhost:3333/userinfo-json/fetch",
            "enabled": true,                  // optional
            "insecure": false,                // optional
            "headers": {                      // optional
                "Authorization": "Bearer 123"
            }
        }
    }
}

Wenn Sie die CLI im Zusammenspiel mit einem Zugriffsrechteverzeichnis verwenden, können Sie die User Information Service-Erweiterung auch global konfigurieren. Sie brauchen die Konfiguration dann nicht in jeder Zugriffsrechte-Datei zu wiederholen. Wenn Sie die Erweiterung dennoch zusätzlich in einer Zugriffsrechte-Datei konfigurieren, überschreiben Sie damit für den zugehörigen Kartendienst die global gesetzten Eigenschaften der Erweiterung.

So können Sie zum Beispiel die global aktivierte User Information Service-Erweiterung für einen einzelnen Dienst deaktivieren, indem Sie folgende Konfiguration in die Zugriffsrechte-Datei aufnehmen:

Abschalten einer global aktivierten Erweiterung

{
    "policies": [...],
    ...
    "extensions": {
        "userInfoService": {
            "enabled": false
        }
    }
}

Nutzerattribute referenzieren

Einzelne Nutzerattribute, die vom User Information Service zurückgegeben werden, können folgende JSON-Datentypen besitzen: String, Boolean, Number, Array (alle Elemente eines Arrays müssen denselben Datentyp besitzen). Wenn Sie Nutzerattribute referenzieren, müssen Sie den Datentyp eines Attributes berücksichtigen. Zum Beispiel müssen Referenzen auf String-Attribute in Vergleichen in einfache Anführungszeichen eingefasst werden.

Die folgende Tabelle zeigt die Nutzung von Attributen unterschiedlicher Datentypen:

Datentyp Beispiel

Datentyp	Beispiel
String	`OWNER = '${user.email}'`
Number	`LEVEL_MIN <= ${user.level}`
Boolean	`ACTIVE_ONLY_STRING = '${user.enabled}'`
Array	`PROJECT_ID IN ${user.projects}`

String

OWNER = '${user.email}'

Number

LEVEL_MIN <= ${user.level}

Boolean

ACTIVE_ONLY_STRING = '${user.enabled}'

Array

PROJECT_ID IN ${user.projects}

Wenn die Abfrage der Nutzerattribute durch die SOI fehlschlägt, wird die Berechtigungsprüfung unterbrochen. Stattdessen lehnt die SOI die Anfrage an den Kartendienst ab.

Verwenden Sie die Markierung "insecure", um auch Werte zu erlauben, die keine SQL-Literale sind.

Beispiele für Einschränkungen

Im folgenden Beispiel werden Nutzerattribute verwendet, um den Zugriff auf Objekte abhängig von deren Feld PROJECT_ID einzuschränken. Personen können ein Objekt nur dann zugreifen, wenn der Wert von PROJECT_ID in der Liste der Werte des Nutzerattributs projects zu finden ist:

Beispiel einer Objekteinschränkung

{
    ...
    "restrictions": {
        "project_features_only": {
            "type": "feature",
            "query": "PROJECT_ID in ${user.projects}"
        }
    }
}

Sie können Nutzerattribute auch bei der Definition von räumlichen Einschränkungen einsetzen. Im folgenden Fall wird das erlaubte Gebiet einer räumlichen Einschränkung abhängig vom Wert des Nutzerattributes securityLevel definiert:

Beispiel einer räumlichen Einschränkung

{
    ...
    "restrictions": {
        "sales_area_only": {
            "type": "spatial",
            "featuretypeurl": "https://gis.example.com:6443/arcgis/rest/services/RestrictedArea/FeatureServer/0",
            "featurequery": "SECURITY_LEVEL_MIN <= ${user.securityLevel}"
        }
    }
}

Im folgenden Beispiel liefert der User Information Service einen projectFilter, welcher als Abfrageausdruck in einer Objekteinschränkung verwendet wird. Wie im Abschnitt Nutzerattribute beschrieben, prüft security.manager NEXT ob ein Nutzerattribut für die Verwendung in einem Abfrageausdruck zulässig ist. Das Attribut user.projectFilter wird in der Objekteinschränkung project_features_only als insecure markiert und somit ohne geprüft zu werden und unverändert in die Objekteinschränkung übernommen.

Projektfilter in der Antwort des User Information Service

{
    "data": {
        "projectFilter": ["PROJECT in ('Project1','Project2')"]
        ...
    }
}

Verwendung des Filters in der Objekteinschränkung

{
    ...
    "restrictions": {
        "project_features_only": {
            "type": "feature",
            "query": "${user.projectFilter;insecure}"
        }
    }
}