Kommandozeilenwerkzeug (CLI)

Das Kommandozeilenwerkzeug secmanctl erlaubt die Verwaltung von Zugriffsrechten auf ArcGIS Server Services, die durch den security.manager NEXT geschützt werden.

Verwendung

$ secmanctl <Kommando> [Optionen]

secmanctl stellt folgende Kommandos bereit:

login: Authentifizierung über ArcGIS Enterprise und Erzeugen eines Tokens
apply: Setzen von Zugriffsrechten auf einen ArcGIS Server Service
sync: Setzen von Zugriffsrechten auf mehrere ArcGIS Server Services gleichzeitig, basierend auf einer lokalen Ordnerstruktur
groups: Anzeige der ArcGIS Enterprise Gruppen
help: Anzeigen der Hilfe

Globale Optionen

Alle Kommandos unterstützen die folgenden globalen Optionen:

--version

Gibt die Version des secmanctl-Werkzeugs aus.

--debug

Kann zur Fehleranalyse wie folgt genutzt werden:

Im Fehlerfall werden ausführliche Trace-Informationen in der Konsole ausgegeben.
Darüber hinaus wird eine Log-Datei erzeugt, die weitere Informationen zur Fehleranalyse enthält. Die Log-Datei wird in einem temporären Ordner gespeichert. Der Pfad zu dieser Datei wird in der Ausgabe dieses Kommandos angezeigt.

--insecure

Erlaubt die Verbindung zu HTTPS-Endpunkten, deren Zertifikate nicht von einer bekannten Root CA ausgestellt wurden.

-v, --verbose

Definiert, wie ausführlich die Ausgaben des Prozesses sind.

Die Option kann mehrfach verwendet werden, um die Menge an Ausgabeinformationen weiter zu erhöhen.

Wird die Option weggelassen, so werden nur die wichtigsten Informationen ausgeben.
Wird die Option einfach verwendet durch -v oder --verbose, werden mehr Details ausgeben.
Die Verwendung von -vv oder --verbose --verbose führt zum höchsten Grad der Ausführlichkeit.

--help

Gibt Nutzungsinformationen für ein Kommando (secmanctl <Kommando> --help) oder für das Werkzeug selbst (secmanctl --help) aus.

Kommandos

`login`

Fragt ein Authentifizierungstoken von einem ArcGIS Server ab. Dieses Token wird benötigt in der Regel, um die Kommandos apply, sync und groups auszuführen.

Um ein Authentifizierungstoken vom ArcGIS Server abzufragen, ist die Angabe von Nutzername und Passwort erforderlich. Dies kann wie folgt erfolgen:

Nicht-interaktiver Login: Nutzername und Passwort können durch die Optionen --username und --password (oder die entsprechende Kurzform) übergeben werden.
Interaktiver Login: Wenn diese beiden Parameter nicht angegeben werden, wird das Kommando interaktiv ausgeführt. Dabei wird der Nutzer aufgefordert, diese beiden Parameter einzugeben.
Einlesen des Passworts von stdin: Das Passwort kann alternativ über die Standard-Eingabe (stdin) eingelesen werden. So kann es beispielsweise mithilfe des Pipe-Operators an das Kommando übergeben werden.

Wenn die Option --plain gesetzt wird, wird die Rückgabe dieses Kommandos auf den Wert des zurückgegebenen Tokens reduziert. Dieses bietet sich für automatisierte Szenarien an, in denen der Token-Wert in einer Variable gespeichert werden soll.

Nutzeraccounts, die Multi-Faktor-Authentifizierung (MFA) verwenden, werden zur Zeit nicht unterstützt. Wir empfehlen die Nutzung von secmanctl login in Verbindung mit Nutzeraccounts ohne MFA bzw. die Anmeldung mit dem primären Site-Administratorkonto. Wenn das primäre Site-Administratorkonto verwendet wird, stehen Funktionen, die Portal-Authentifizierung benötigen, nicht zur Verfügung (wie z.B. secmanctl groups).

Verwendung

$ secmanctl login [Optionen]

Beispiel: Nicht-interaktiver Login

$ secmanctl login -d https://gis.example.com:6443/arcgis -u adminuser -p ./secret.txt
Login successful.
Authenticated against: https://gis.example.com/portal
Valid until:           2020-10-21T11:08:21.843Z
Requires SSL:          Yes

8cq4PACs9UaroGVLnqkfJCU2BEBHFXOpd518Hbggb31kL7l6Fjhx974oCQYwjLnj0hdsEfTGKKFJLUi-KFqiArfGevUMN8EJnAnswZuZwFn3wIbYqfY9D1Jmjy_8gZOTfl_HzL3u5cSVu5AdunxPsVdBudqqSgJmE-O23jTCHhI.

Beispiel: Interaktiver Login

$ secmanctl login -d https://gis.example.com:6443/arcgis
Enter username: · admin
Enter password: · **********
...

Beispiel: Passwort von `stdin`

$ ./get-password | secmanctl login -u admin -p - -d https://gis.example.com:6443/arcgis
Login successful.
Authenticated against: https://gis.example.com/portal
...

Optionen

-d, --server-url <Server-URL>: ArcGIS Server Basis-URL wie https://gis.example.com:6443/arcgis.

Wird von secmanctl verwendet, um ein Token zu generieren. Wenn es sich um einen Verbundserver handelt, wird sich secmanctl an dem verbundenen Portal authentifizieren.
-u, --username <Nutzername>: Nutzername eines Nutzers, für den ein Authentifizierungstoken erzeugt werden soll.

Um die anderen Kommandos von secmanctl mit dem generierten Token erfolgreich verwenden zu können, müssen Sie hier den Nutzernamen eines Administrator-Nutzers angeben.
-p, --password <Passwort-Datei>: Text-Datei im ASCII oder UTF-8 Format, deren erste Zeile das Passwort des Nutzers ist.
--iwa: Aktiviert die Unterstützung für Integrierte Windows Authentifizierung (IWA).

Die Windows-Benutzerkennung wird hierbei für die Authentifizierung gegenüber dem ArcGIS Enterprise-Portal verwendet. Bei einem nicht mit einem ArcGIS Enterprise-Portal verbundenen ArcGIS Server ist bei Verwendung von IWA das Login-Kommando nicht erforderlich.
-e, --expires <Minuten> (optional): Gültigkeitsdauer des Authentifizierungstokens in Minuten.

Der Maximalwert wird durch Einstellungen des Servers (oder des Portals) bestimmt.

Standardwert: 60
--plain (optional): Ausgabe nur des Token-Werts und Unterdrückung aller anderen Informationen.

`apply`

Setzt eine JSON-Datei mit Zugriffsrechten für einen Kartenservice auf dem ArcGIS Server. Wenn security.manager NEXT für diesen Service noch nicht aktiviert ist, wird er durch dieses Kommando aktiviert.

Unter Verwendung der --dry-Option werden keine Änderungen auf dem ArcGIS Server durchgeführt. Stattdessen wird die Ausführung des Kommandos simuliert, und Änderungen, die ohne die --dry-Option durchgeführt würden, werden als Ergebnis ausgegeben.

Sie können ebenfalls das sync-Kommando in Verbindung mit der --service-Option verwenden, um Änderungen an den Zugriffsrechten eines einzelnen Services vorzunehmen.

Verwendung

$ secmanctl apply [options]

Beispiel

$ secmanctl apply -i policies/policy.json -d https://gis.example.com:6443/arcgis -s water/wells -t MghzyNeWubQtTgZfMQTx8rasda.. --dry -vv

Optionen

-i, --input-file <Datei>: Pfad zur Zugriffsrechte-Datei, die gesetzt werden sollen.

Verwenden Sie - (Minus), um aus der Standard-Eingabe (stdin) zu lesen.

Beispiel: policies/policy.json
-d, --server-URL <Server-URL>: ArcGIS Server Basis-URL.

Über diese URL muss das ArcGIS Server Administratorverzeichnis (/arcgis/admin) erreichbar sein. Bei Verwendung der Integrierten Windows Authentifizierung (IWA) muss hier die Web-Adaptor-URL verwendet werden.

Beispiel: https://gis.example.com:6443/arcgis
-s, --service [<Ordner>/]<Service-Name>: Ordner (optional) und Name des Kartenservice, für den die Zugriffsrechte-Datei gesetzt werden sollen.

Beispiel: water/wells, SampleWorldCities
-t, --token <Token>: Authentifizierungstoken eines ArcGIS Administrator-Nutzers.

Dieses wird von secmanctl genutzt, um sich gegenüber dem ArcGIS Server Administration Directory zu authentifizieren. Bei Verwendung von IWA mit einem nicht mit einem ArcGIS Enterprise Portal verbundenen ArcGIS Server muss kein Token angegeben werden.
--iwa: Aktiviert die Unterstützung für Integrierte Windows Authentifizierung (IWA).

Die Windows-Benutzerkennung wird hierbei für die Authentifizierung gegenüber dem ArcGIS Server verwendet.
-f, --folder <Pfad> (optional): Pfad zu einem Zugriffsrechtverzeichnis.

Dies erlaubt die Verwendung von globalen Eigenschaften und Einschränkungen für die angegebene Input-Datei.
--dry (optional): Validiert die JSON-Datei und prüft, ob ein Kartenservice vorhanden ist, dessen Name mit dem der JSON-Datei übereinstimmt.

Es findet keine Veränderung der Zugriffsrechte auf dem Kartenservice statt.

`sync`

Verwenden Sie secmanctl sync, um das Zugriffsrechtverzeichnis mit den gesetzten Zugriffsrechten auf dem ArcGIS Server zu synchronisieren. Wenn security.manager NEXT für einen Service noch nicht aktiviert wurde, wird er durch dieses Kommando aktiviert, sofern eine Zugriffsrechte-Datei für diesen Service vorhanden ist.

Die Verzeichnis-Struktur, die von diesem Kommando verwendet wird, ist in Verzeichnis für Zugriffsrechte definiert.

Unter Verwendung der --delete-Option wird security.manager NEXT auf den Services, für die keine lokale Zugriffsrechte-Datei vorhanden ist, deaktiviert.

Wenn das sync-Kommando nur auf ausgewählten Ordnern ausgeführt werden soll, kann die --include-folders-Option verwendet werden, um diese Ordner anzugeben. Diese Option kann insbesondere in Verbindung mit der --delete-Option hilfreich sein.

Wie das apply-Kommando unterstützt auch das sync-Kommando eine --dry-Option. Bei Verwendung der --dry-Option werden keine Änderungen an den Zugriffsrechten eines Service vorgenommen. Stattdessen wird die Ausführung des Kommandos simuliert, und Änderungen, die ohne Verwendung der --dry-Option durchgeführt würden, werden ausgegeben.

Verwendung

$ secmanctl sync [Optionen]

Beispiel

$ secmanctl sync -f ./myRootFolder -d https://gis.example.com:6443/arcgis -t MghzyNeWubQtTgZfMQTx8rasda.. --delete --dry -vv

Optionen

-f, --folder <Pfad>: Pfad zu einem Zugriffsrechtverzeichnis.
-d, --server-URL <Server-URL>: ArcGIS Server Basis-URL.

Über diese URL muss das ArcGIS Server Administratorverzeichnis (/arcgis/admin) erreichbar sein. Bei Verwendung der Integrierten Windows Authentifizierung (IWA) muss hier die Web-Adaptor-URL verwendet werden.

Beispiel: https://gis.example.com:6443/arcgis
-t, --token <Token>: Authentifizierungstoken eines ArcGIS Administrator-Nutzers.

Dieses wird von secmanctl genutzt, um sich gegenüber dem ArcGIS Server Administration Directory zu authentifizieren. Bei Verwendung von IWA mit einem nicht mit einem ArcGIS Enterprise Portal verbundenen ArcGIS Server muss kein Token angegeben werden.
--iwa: Aktiviert die Unterstützung für Integrierte Windows Authentifizierung (IWA).

Die Windows-Benutzerkennung wird hierbei für die Authentifizierung gegenüber dem ArcGIS Server verwendet.
-s, --service [<Ordner>/]<Service-Name> (optional): Beschränkt die Synchronisierung auf einen einzelnen Service.

Beispiel: 'oceans' oder 'water/wells'
-j, --jobs <Anzahl> (optional): Ausführung von bis zu Anzahl gleichzeitiger Update-Vorgänge.

Diese Option kann genutzt werden, um die Anzahl paralleler Update-Vorgänge zu reduzieren oder zu erhöhen.

Standardwert: 8
--delete (optional): Aktiviert das Löschen von Zugriffsrechten auf dem Server, wenn sich keine Zugriffsrechte-Datei für die Services in dem mit -f bestimmten Ordner befindet.

--include-folders <Liste-von-Ordernamen> (optional): Verwendung von nur den ArcGIS Server-Ordnern, die als kommaseparierte Liste angegeben werden.

/ bezeichnet das Stammverzeichnis.

Beispiel: water,traffic
--dry (optional): Simuliert die Synchronisierung, ohne Zugriffsrechte der Services zu verändern.

Änderungen, die ohne diese Option durchgeführt würden, werden ausgegeben.
--reverse (optional): Diese Option lädt die aktuell gesetzten Zugriffsrechte vom ArcGIS Server herunter.

Wenn Sie (noch) kein lokales Zugriffsrechtverzeichnis verwenden, kann dies hilfreich sein, um eine lokale Sicherung zu erstellen.
Um die Zugriffsrechte aus einzelnen Ordnern herunterzuladen, kann die Option mit --include-folders kombiniert werden.
Diese Option synchronisiert keine globalen Elemente für Zugriffsrechte und sollte nicht auf einem bestehenden Zugriffsrechtverzeichnis angewendet werden!

`groups`

Mit diesem Kommando können Sie die Gruppen abfragen, die aktuell im Portal angelegt sind. Wenn Sie einen ArcGIS Server verwenden, der nicht mit einem Portal verbunden ist, werden mit diesem Kommando stattdessen die im ArcGIS Server definieren Rollen abgefragt.

In der Ausgabe werden die Gruppennamen, die Gruppen-IDs und die Eigentümer der Gruppen (Eigentümer nur für Verbundserver) angezeigt.

Verwendung

$ secmanctl groups [options]

Beispiel

$ secmanctl groups -d https://gis.example.com:6443/arcgis -t MghzyNeWubQtTgZfMQTx8rasda.. --by-title "\"Dezernat A\" OR Vertrieb*"

Beispiel: Anpassung der JSON-Ausgabe

$ secmanctl groups -d https://gis.example.com:6443/arcgis -t MghzyNeWubQtTgZfMQTx8rasda.. --json --json-key-pattern "g_{owner}_{title}"

{
  "g_admin_dezernat_a": "7f383170dc414da99",
  "g_admin_dezernat_b": "asabb335653nrt534",
  "g_musterman_mygroup": "x34383170dc414da"
}

Optionen

-d, --server-URL <Server-URL>

ArcGIS Server Basis-URL.

Über diese URL muss das ArcGIS Server Administratorverzeichnis (/arcgis/admin) erreichbar sein. Bei Verwendung der Integrierten Windows Authentifizierung (IWA) muss hier die Web-Adaptor-URL verwendet werden.

Beispiel: https://gis.example.com:6443/arcgis

-t, --token <Token>

Authentifizierungs-Token eines ArcGIS Administrator-Nutzers.

Dieses wird von secmanctl genutzt, um sich gegenüber dem ArcGIS Server Administration Directory zu authentifizieren. Bei Verwendung von IWA mit einem nicht mit einem ArcGIS Enterprise Portal verbundenen ArcGIS Server muss kein Token angegeben werden.

--iwa

Aktiviert die Unterstützung für Integrierte Windows Authentifizierung (IWA).

Die Windows-Benutzerkennung wird hierbei für die Authentifizierung gegenüber dem ArcGIS Server bzw. ArcGIS Enterprise-Portal verwendet.

--by-title <Suchtext> (optional)

Beschränkt das Ergebnis auf Gruppen, die mithilfe des angegebenen Suchtextes gefunden werden.

Wenn Sie einen Verbundserver verwenden, wird die Fuzzy-Suchfunktion für Gruppen genutzt, die das Portal bereitstellt. Wenn Sie einen nicht verbundenen ArcGIS Server einsetzen, werden alle Rollen zurückgegeben, die den Suchtext enthalten — ohne Berücksichtigung von Groß- und Kleinschreibung.

ArcGIS Enterprise-Portal Fuzzy-Suche

Folgende Zeichen müssen mit einem \ escaped werden: + - && || ! ( ) { } [ ] ^ " ~ * ? : /, zum Beispiel --by-title "Group with $Parentheses$". Generelle Hinweise zur Suche sowie der möglichen Such-Syntax können der offiziellen Such-Referenz entnommen werden.

--limit <anzahl> (optional)

Beschränkt die Anzahl der auszugebenden Gruppen auf den angegebenen Wert.

Standardmäßig ist die Anzahl der auszugebenden Gruppen unbeschränkt.

Standardwert: -1

--json (optional)

Erzeugt JSON formatierte Ausgabe.

Die Ausgabe ist für die Verwendung innerhalb einer properties.json Datei optimiert.

--json-key-pattern <pattern> (optional)

Ermöglicht die Definition eines Musters für die Gruppenschlüssel in der JSON-Ausgabe.

Die Ausdrücke {title}, {owner} und {id} können darin verwendet werden.

Standardwert: {title}

`help`

Das help-Kommando zeigt Hilfeinformationen zu einem bestimmten Kommando an.

Verwendung

$ secmanctl help [Kommando]

Beispiel

$ secmanctl help sync

Verzeichnis für Zugriffsrechte

Einige der Kommandos arbeiten auf einem speziellen Zugriffsrechtverzeichnis. Dieses Verzeichnis soll die Struktur der Services und Ordnern eines ArcGIS Servers widerspiegeln. Das Verzeichnis kann einen beliebigen Namen haben. Unterhalb des Zugriffsrechtverzeichnisses legen Sie einen Ordner mit dem vorgegebenen Namen services an, in dem die Zugriffsrechte gespeichert werden.

Es wird empfohlen, den Hostnamen des ArcGIS Servers als Namen für das Zugriffsrechtverzeichnis zu verwenden.

Das folgende Beispiel gibt die Struktur für ein Verzeichnis mit Zugriffsrechten für einen bestimmten ArcGIS Server wieder.

arcgis-public/
├── services/                   // vorgegebener Ordner
│   ├── oil/                    // Ordner, analog zum Ordner 'oil' auf dem ArcGIS Server
│   │   ├── pipelines.json      // Zugriffsrechte für den Service "oil/pipelines"
│   │   ├── pipelines.conf.json // optional, SOI-Konfigurationsdatei für den Service "oil/pipelines"
│   │   └── rigs.json           // Zugriffsrechte für den Service "oil/rigs"
│   ├── water/                  // Ordner, analog zum Ordner 'water' auf dem ArcGIS Server
│   │   ├── bassins.json        // Zugriffsrechte für den Service "water/bassins"
│   │   └── wells.json          // Zugriffsrechte für den Service "water/wells"
│   └── aerial_photography.json // Zugriffsrechte für den Service "aerial_photography"
└── extensions.json             // optional, enthält die globale Konfiguration von Erweiterungen
└── properties.json             // optional, enthält globale Eigenschaften
└── restrictions.json           // optional, enthält globale Einschränkungen

SOI-Konfigurationsdatei

Die Konfiguration der SOI für einen geschützten Dienst wird in einer Datei mit dem Namen <servicename>.conf.json vorgenommen. Es ist nur dann notwendig diese Datei anzulegen, wenn von den Standardwerten abweichende Einstellungen vorgenommen werden sollen, siehe Abschnitt Konfigurationswerte unten. Wenn für einen geschützten Dienst keine Konfigurationsdatei vorhanden ist, werden die jeweiligen Standardwerte angewendet.

Beispiel einer <servicename>.conf.json-Datei

{
    "soi.supportReplicas": true
}

Konfigurationswerte

soi.supportReplicas: Aktiviert die Unterstützung von Replikatoperationen.

Wenn der Wert auf false (Standard) gesetzt wird, werden Replikatoperationen auf geschützten Diensten nie zugelassen. Wenn der Wert auf true gesetzt wird, werden Replikatoperationen auf geschützten Diensten zugelassen.

Standardwert: false

Globale Elemente für Zugriffsrechte

Für Zugriffsrechte können Sie globale Elemente definieren.

Eigenschaften

Im Zugriffsrechtverzeichnis können Sie global Eigenschaften in einer properties.json-Datei definieren. Diese Eigenschaften können wie folgt verwendet werden:

Eigenschaften, die Sie in dieser Datei definieren, können Sie in allen Zugriffsrechten des Verzeichnisses (und ggf. Unterordnern) über eine Dollar-Notation (etwa ${Regel}) referenzieren.
Analog können Sie Einschränkungen in einer restrictions.json-Datei definieren. Diese dürfen Eigenschaften aus der properties.json-Datei referenzieren.
Sie können auch Erweiterungen global definieren, indem eine extensions.json-Datei anlegen. Innerhalb dieser Datei können Sie ebenfalls Eigenschaften aus der properties.json-Datei referenzieren.

Beispiel einer properties.json-Datei

{
    "$schema": "https://raw.githubusercontent.com/conterra/policies-json/1.5.0/schema/policies.schema.json",
    "properties": {
        "group1": "84ac890b7627461e8b0dd0376bb8a0c2",
        "group2": "dffdab582c644df894bc1aed08609783"
    }
}

Die Datei entspricht dem generellen Zugriffsrechte-Format, darf aber nur das "properties"-Element enthalten.

Einschränkungen

Im Zugriffsrechtverzeichnis können Sie global Einschränkungen in einer restrictions.json-Datei definieren. Einschränkungen, die Sie in dieser Datei definieren, können Sie in allen Zugriffsrechten des Verzeichnisses (und ggf. Unterordnern) über den Namen der Einschränkungen referenzieren.

Beispiel einer restrictions.json-Datei

{
    "$schema": "https://raw.githubusercontent.com/conterra/policies-json/1.5.0/schema/policies.schema.json",
    "restrictions": {
        "restriction_only_Germany": {
            "type": "feature",
            "query": "country = 'Germany'"
        },
        "restriction_only_Ireland": {
            "type": "feature",
            "query": "country = 'Ireland'"
        }
    }
}

Die Datei entspricht dem generellen Zugriffsrechte-Format, darf aber nur das "restrictions"-Element enthalten.

Beispiel eines Zugriffsrechts mit referenzierter Einschränkung

{
    "$schema": "https://raw.githubusercontent.com/conterra/policies-json/1.5.0/schema/policies.schema.json",
    "policies": [
        {
            "layers": [ "1", "2" ],
            "roles": [  "${group1}" ],
            "restrictions": [
                "restriction_only_Ireland"
            ]
        }
    ]
}

Erweiterungen

Im Zugriffsrechtverzeichnis können Sie global Erweiterungen in einer extensions.json-Datei definieren. Globale Erweiterungen sind in allen Zugriffsrechtedateien verfügbar. Erweiterungen, die in Zugriffsrechtedateien selbst definiert sind, werden durch die globalen Erweiterungen nicht überschrieben.

Beispiel einer extensions.json Datei

{
    "$schema": "https://raw.githubusercontent.com/conterra/policies-json/1.5.0/schema/policies.schema.json",
    "extensions": {
            "userInfoService": {
                "enabled": true,
                "url": "https://localhost:3333",
                "insecure": false,
                "headers": {
                    "Authorization": "Bearer 123"
                }
            }
        }
}

Die Datei entspricht dem generellen Zugriffsrechte-Format, darf aber nur das "extensions"-Element enthalten.

Kommandozeilenwerkzeug (CLI)

Verwendung

Globale Optionen

Kommandos

login

Verwendung

Beispiel: Nicht-interaktiver Login

Beispiel: Interaktiver Login

Beispiel: Passwort von stdin

Optionen

apply

Verwendung

Beispiel

Optionen

sync

Verwendung

Beispiel

Optionen

groups

Verwendung

Beispiel

Beispiel: Anpassung der JSON-Ausgabe

Optionen

help

Verwendung

Beispiel

Verzeichnis für Zugriffsrechte

SOI-Konfigurationsdatei

Konfigurationswerte

Globale Elemente für Zugriffsrechte

Eigenschaften

Einschränkungen

Erweiterungen

`login`

Beispiel: Passwort von `stdin`

`apply`

`sync`

`groups`

`help`