Zugriffsrechte-Format

Überblick

Zugriffsrechte für einen Service werden im JSON-Format definiert. Die JSON-Datei besteht aus dem Bereich "policies" sowie den optionalen Bereichen "properties", "restrictions" und "extensions".

{
    "policies": [],
    "properties": {},       //Optional
    "restrictions": {},     //Optional
    "extensions": {}        //Optional
}

Die Reihenfolge, in der diese Eigenschaften definiert werden, ist unerheblich. Die optionalen Eigenschaften können Sie entweder weglassen oder ihnen wie im Beispiel oben jeweils das leere Objekt {} zuordnen.

Automatische Vervollständigung und Syntaxprüfung

Das hier beschriebene JSON-Format für Zugriffsrechte ist auch als JSON-Schema beschrieben. Mithilfe des Schemas können Sie sicherstellen, dass Ihre JSON-Datei den Vorgaben entspricht. Außerdem können Editoren wie Visual Studio Code auf Basis des Schemas Vorschläge, Beschreibungen sowie eine automatische Vervollständigung für Elemente bei der Eingabe anbieten.

Fügen Sie der JSON-Datei die folgende "$schema" Eigenschaft hinzu, um die automatische Vervollständigung zu aktivieren:

{
    "$schema": "https://raw.githubusercontent.com/conterra/policies-json/1.2.0/schema/policies.schema.json",
    "policies": [],
    "properties": {},
    "restrictions": {},
    "extensions": {}
}

Eine Kopie des JSON-Schemas ist Teil der security.manager NEXT Auslieferung und verfügbar unter [SECMAN_DIR]/resources/policies.schema.json. Damit können Sie die automatische Vervollständigung auch nutzen, wenn Sie in Ihrer Umgebung keinen Zugriff auf https://raw.githubusercontent.com/conterra/policies-json/…​ haben. Um diese Kopie zu verwenden, passen Sie die $schema Eigenschaft wie folgt an (ersetzen Sie [SECMAN_DIR] mit dem konkreten Verzeichnispfad):

{
    "$schema": "[SECMAN_DIR]/resources/policies.schema.json",
    "policies": [],
    "properties": {},
    "restrictions": {},
    "extensions": {}
}

Zugriffsrechte

Die Elemente des "policies"-Arrays definieren die Regeln, die für den Zugriff auf einen Service gelten. Ein einzelnes Zugriffsrecht ist eine Kombination aus Layern, Rollen und optionalen Einschränkungen.

Um Personen, die der Rolle role_division_42 zugeordnet sind, Zugriff auf die Layer mit den IDs 0 und 1 zu erteilen, definieren Sie folgende Regel:

{
    "policies": [
        {
            "layers": ["0", "1"],
            "roles": ["role_division_42"]
        }
    ]
}

Layer

Die "layers"-Eigenschaft eines "policies"-Elements ist ein Array von Layer-IDs, so wie sie ein Kartenservice definiert. Layer-IDs können explizit, als Intervall oder als "*", d.h. alle Layer, angegeben werden.

Das folgende Beispiel definiert zwei Zugriffsrechte. Das erste Zugriffsrecht wird auf die Layer 0 und 3 bis 5 angewendet, während das zweite Zugriffsrecht auf alle Layer des Service wirkt:

{
    "policies": [
        {
            "layers": ["0", "3-5"],
            "roles": ["enhancedSecurity_any"]
        },
        {
            "layers": ["*"],
            "roles": ["role_division_42"]
        }
    ]
}

Rollen

Die "roles"-Eigenschaft eines "policies"-Elements ist ein Array von Rollen-IDs. Eine Rollen-ID bezieht sich auf eine Portal-Gruppe oder ArcGIS Server Rolle, die einer Person zugeordnet ist, die eine Serviceanfrage durchführt. Bei einer Authentifizierung durch ArcGIS Enterprise werden die Rollen-IDs eines Zugriffsrechts mit den IDs der Portal-Gruppen oder Namen der ArcGIS Server Rollen der anfragenden Person verglichen.

Beispiel: Eine Person ist der Portal-Gruppe "Division 42" zugeordnet, deren Gruppen-ID im Portal 41477fa98f444444855e1e0b7b132b45 ist. Folgende Regel erlaubt ihr den Zugriff auf den Layer 0 eines Service:

{
    "policies": [
        {
            "layers": ["0"],
            "roles": ["41477fa98f444444855e1e0b7b132b45"]
        }
    ]
}

Außerdem können Sie die folgenden Rollen-IDs verwenden, um unabhängig von konkreten Rollenzuordnungen Zugriff zu erlauben:

  • enhancedSecurity_any

  • enhancedSecurity_authenticated

Ein Zugriffsrecht für die Rolle enhancedSecurity_any gilt unabhängig davon, ob eine Person bei ArcGIS Enterprise angemeldet ist oder welche Rolle sie besitzt. Allerdings muss der Service, für den diese Regel definiert wird, in ArcGIS Enterprise öffentlich freigegeben sein, damit sie wirken kann.

Die Rolle enhancedSecurity_authenticated können Sie nutzen, um nur Personen Zugriff zu erteilen, die bei ArcGIS Enterprise angemeldet sind.

Im folgenden Beispiel ist es allen Personen erlaubt, auf Layer 0 zuzugreifen. Angemeldete Personen können sowohl auf Layer 0 als auch auf Layer 1 zugreifen:

{
    "policies": [
        {
            "layers": ["0"],
            "roles": ["enhancedSecurity_any"]
        },
        {
            "layers": ["1"],
            "roles": ["enhancedSecurity_authenticated"]
        }
    ]
}

Einschränkungen

Mithilfe von Einschränkungen (Restrictions) können Sie den Zugriff auf Layer genauer eingrenzen. Das "restrictions"-Array eines Zugriffsrechts enthält eine Liste von IDs, die Elemente des "restrictions"-Objekts auf oberster Ebene der JSON-Datei referenzieren.

Das folgende Beispiel zeigt ein Zugriffsrecht, das die Einschränkung "california" referenziert, die weiter unten in der Datei definiert wird.

{
    "policies": [
        {
            "layers": ["0"],
            "roles": ["${guests}"],
            "restrictions": ["california"]
        }
    ],
    "restrictions": {
        "california": {
            "type": "spatial",
            "featuretypeurl": "https://gis.example.com:6443/arcgis/rest/services/USA/FeatureServer/0",
            "featurequery": "state = 'California'"
        }
    }
}

Im Abschnitt Definition von Einschränkungen erfahren Sie mehr über die Konfiguration von Einschränkungen.

Eigenschaften

Das "properties"-Array besteht aus Schlüssel-Wert-Paaren, mit denen Sie Eigenschaften definieren können, die an anderer Stelle in dieser Datei verwendet werden können. Die Werte von Eigenschaften müssen Strings sein. Die Schlüssel müssen mit einem Buchstaben beginnen und dürfen nur aus den Zeichen a-z, A-Z, 0-9 sowie '_' (Unterstrich) und '-' (Minus) bestehen. Sie können die Werte in anderen Elementen verwenden, indem Sie diese mit ${property_name} referenzieren. Auf diese Weise können Sie Eigenschaften beschreibende Namen geben.

Im folgenden Beispiel wird die Rollen-ID 41477fa98f444444855e1e0b7b132b45 der Eigenschaft "guests" zugeordnet. Sie kann daher auf folgende Weise in einem Zugriffsrecht referenziert werden:

{
    "policies": [
        {
            "layers": ["0"],
            "roles": ["${guests}"]
        }
    ],
    "properties": {
        "guests": "41477fa98f444444855e1e0b7b132b45"
    }
}

Definition von Einschränkungen

Eine Regel kann den Zugriff auf Layer begrenzen, indem Sie ihr Einschränkungen (Restrictions) zuordnen.

Das folgende Beispiel zeigt ein Zugriffsrecht, das die Einschränkung "california" referenziert, die im "restrictions"-Element auf oberster Ebene definiert ist.

{
    "policies": [
        {
            "layers": ["0"],
            "roles": ["${guests}"],
            "restrictions": ["california"]
        }
    ],
    "restrictions": {
        "california": {
            "type": "spatial",
            "featuretypeurl": "https://gis.example.com:6443/arcgis/rest/services/USA/FeatureServer/0",
            "featurequery": "state = 'California'"
        }
    }
}

Der Name einer Einschränkung (wie zum Beispiel california in obigem Beispiel) darf nur aus den Zeichen a-z, A-Z, 0-9 sowie '_' (Unterstrich) und '-' (Minus) bestehen. Er muss mit einem Buchstaben beginnen.

Sie können folgende Arten von Einschränkungen verwenden:

Räumlich

Zugriff auf ein räumliches Gebiet einschränken

Feld

Zugriff auf Felder eines Layers einschränken

Objekt

Zugriff auf Objekte eines Layers einschränken

Editierung

Editieren von Geometrien und Attributen verbieten

Einschränkungen, die in einem Zugriffsrecht referenziert werden, gelten immer für alle in diesem Zugriffsrecht angegebenen Layer. Wenn Sie für unterschiedliche Layer unterschiedliche Einschränkungen definieren möchten, müssen dazu separate Zugriffsrechte angelegt werden.

Räumliche Einschränkungen

Mittels räumlicher Einschränkungen können Sie festlegen, für welchen geographischen Bereich eines Layers Daten zugegriffen werden können. Räumliche Einschränkungen legen fest, welche Bereiche in einem Kartenbild sichtbar sind. Im Falle der Abfrage von Objekten (Features) bestimmen Sie mit räumlichen Einschränkungen, dass nur solche Features zurückgegeben werden, die im erlaubten Bereich liegen.

Den erlaubten Bereich definieren Sie als Referenz auf Geometrien, die von einem ArcGIS Feature-Service bereitgestellt werden. Diese Referenz besteht aus folgenden Informationen:

type

Typ der Einschränkung, muss den Wert "spatial" besitzen.

featuretypeurl

URL, die einen Feature-Service Layer referenziert.

Neben einer absoluten URL können auch relative URLs der Form /<folder>/<service>/FeatureServer/0 verwendet werden.
Die Verwendung relativer URLs erlaubt auch die Nutzung nicht-öffentlicher Feature-Services der gleichen Server-Site für räumliche Einschränkungen.

featurequery

Definition Expression (oder WHERE clause), mit der die Features abgefragt werden, die den erlaubten Bereich beschreiben.

Sie können als Teil der Query Nutzerattribute verwenden, beispielsweise in der Form OWNER = '${user.username}' oder DEPARTMENT IN ${user.roles}.

Die Regel im folgenden Beispiel erlaubt Zugriff auf jene Objekte von Layer 1, die innerhalb oder auf dem Rand von Features des Layers https://gis.example.com:6443/arcgis/rest/services/RestricionAreas/FeatureServer/0 liegen, deren Eigenschaft area_name gleich 51 ist.

{
    "policies": [
        {
            "layers": ["1"],
            "roles": ["${guests}"],
            "restrictions": ["area51"]
        }
    ],
    "restrictions": {
        "area51": {
            "type": "spatial",
            "featuretypeurl": "https://gis.example.com:6443/arcgis/rest/services/RestricionAreas/FeatureServer/0",
            "featurequery": "area_name = '51'"
        }
    }
}

Räumliche Einschränkungen werden grundsätzlich auf alle Layer des Kartenservice angewendet. Bei Feature-Services wird die räumliche Einschränkung auf die jeweils konfigurierten Layer angewendet.

Feldeinschränkungen

Mit Feldeinschränkungen können Sie festlegen, dass bestimmte Felder eines Layers oder einer Tabelle nicht zugreifbar, d.h. weder sichtbar noch editierbar, sein sollen. Die Felder, die verborgen werden sollen, müssen als Liste von Feldnamen angegeben werden.

Für die Definition einer Feldeinschränkung im "restrictions"-Element auf oberster Ebene des Dokuments müssen Sie folgende Eigenschaften angeben:

type

Typ der Einschränkung, muss den Wert "field" besitzen.

hiddenfields

Array von Strings, der die Feldnamen eines Layers oder einer Tabelle aufzählt, auf die nicht zugegriffen werden darf.

Einschränkung

Replikate werden bei vorhandenen Feldeinschränkungen nicht unterstützt.

Folgendes Zugriffsrecht legt eine Einschränkung für Felder des Layers 42 fest. Personen, die nicht angemeldet sind, dürfen nicht auf die Felder DIVISION_SIZE und DIVISION_REVENUE zugreifen.

{
    "policies": [
        {
            "layers": ["42"],
            "roles": ["enhancedSecurity_any"],
            "restrictions": ["secret_division_data"]
        }
    ],
    "restrictions": {
        "secret_division_data": {
            "type": "field",
            "hiddenfields": ["DIVISION_SIZE", "DIVISION_REVENUE"]
        }
    }
}

Objekteinschränkungen

Sollen bestimmte Objekte (Features) eines Layers oder einer Tabelle für Mitglieder bestimmter Rollen nicht sichtbar sein, können Sie Objekteinschränkungen verwenden. Dazu geben Sie einen Abfrageausdruck (Definition Query) an, mit dem Sie festlegen, auf welche Objekte eine Person zugreifen kann.

Für die Definition einer Objekteinschränkung im "restrictions"-Element auf oberster Ebene des Dokuments müssen Sie folgende Eigenschaften angeben:

type

Typ der Einschränkung, muss den Wert "feature" besitzen.

query

Abfrageausdruck, in der vom ArcGIS Server unterstützten SQL-Syntax, analog zur Einschränkung einzelner Layer z.B. in ArcMap oder ArcGIS Pro.

Sie können als Teil des Abfrageausdrucks Attribute des anfragenden Nutzers referenzieren.

Folgendes Zugriffsrecht legt eine Einschränkung für Objekte des Layers 42 fest. Alle angemeldeten Personen dürfen nur auf Objekte zugreifen, deren Feld DIVISION_NAME den Wert North besitzt.

{
    "policies": [
        {
            "layers": ["42"],
            "roles": ["enhancedSecurity_authenticated"],
            "restrictions": ["northern_division"]
        }
    ],
    "restrictions": {
        "northern_division": {
            "type": "feature",
            "query": "DIVISION_NAME = 'North'"
        }
    }
}

Nutzerattribute

Folgende Attribute des anfragenden Nutzers können in einem Abfrageausdruck verwendet werden:

Attribut Beschreibung Beispiel

${user.username}

Der Nutzername der anfragenden Person, so wie er zum Anmelden beim Portal order ArcGIS Server benutzt wird.

OWNER = '${user.username}'
Fragt alle Objekte ab, deren Feld OWNER dem Nutzernamen der anfragenden Person entspricht.

${user.roles}

  • ArcGIS Server: List of names of all roles assigned to the requesting user.

  • ArcGIS Verbundserver: List of IDs of all portal groups the requesting user belongs to.

DEPARTMENTS IN ${user.roles}
Fragt alle Objekte ab, deren Feld DEPARTMENT einer der Rollen oder Gruppen-IDs der anfragenden Person entspricht.

Die Einschränkung auf lediglich zwei verfügbare Nutzerattribute ist durch ArcGIS Enterprise bedingt. Um Objekteinschränkungen abhängig von weiteren Informationen über die zugreifende Person durchzusetzen, können Sie security.manager NEXT um einen User Information Service erweitern.

Editier-Einschränkungen

Standardmäßig kann jeder Benutzer mit Zugriff auf einen Feature-Service sowohl Geometrie- als auch Attribut-Daten bearbeiten. Dies kann für bestimmte Ebenen und Gruppen verweigert werden.

type

Typ der Einschränkung, muss den Wert "readonly" besitzen.

Folgendes Zugriffsrecht verbietet das Editieren für alle Layer durch Benutzer der Gruppe enhancedSecurity_authenticated.

{
    "policies": [
        {
            "layers": ["*"],
            "roles": ["enhancedSecurity_authenticated"],
            "restrictions": ["editing_denied"]
        }
    ],
    "restrictions": {
        "editing_denied": {
            "type": "readonly"
        }
    }
}

Ist jemand mehr als einer Gruppe zugeordnet und für mehrere dieser Gruppen existieren Zugriffsrechte für einen bestimmten Layer, so wird der Zugriff unter Berücksichtigung der Gesamtheit aller in dieser Zugriffsrechte definierten Einschränkungen gewährt.

Das bedeutet:

  • Räumliche Einschränkungen: Zugriff ist nur auf die Fläche erlaubt, in der sich alle in den relevanten Zugriffsrechten definierten Geometrien überschneiden.

  • Feldeinschränkungen: Die Felder werden verborgen, die in zumindest einer der relevanten Zugriffsrechte ausgeschlossen werden.

  • Objekteinschränkungen: Zugriff wird nur auf die Objekte gewährt, die in allen relevanten Zugriffsrechten erlaubt sind.

  • Editier-Einschränkungen: Das Editieren ist nicht erlaubt, wenn in mindestens einem Zugriffsrecht eine Editier-Einschränkung definiert ist.

Erweiterungen

Im optionalen Abschnitt "extensions" aktivieren und konfigurieren Sie zusätzliche Fähigkeiten für Zugriffsrechte.

{
    "policies: [],
    ...
    "extensions": {                 // optional
        "<extension_name>" : { }    // extension configuration
    }
}

Im Abschnitt Erweiterungen können Sie mehr über verfügbare Erweiterungen und deren Konfiguration erfahren.