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 Authentifizierungs-Token von einem ArcGIS Server ab. Dieses Token wird benötigt, 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 mit Hilfe 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.

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 der ArcGIS Server mit einem ArcGIS Portal föderiert ist, wird sich secmanctl an diesem 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.

-e, --expires <Minuten> (optional)

Gültigkeitsdauer des Authentifizierungstokens in Minuten. Der Standardwert beträgt 60 Minuten. Der Maximalwert wird durch Einstellungen des Servers (oder des Portals) bestimmt.

--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. Statt dessen 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. Beispiel: policies/policy.json. Verwenden Sie ‘-’, um aus der Standard-Eingabe (stdin) zu lesen.

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

ArcGIS Server Basis-URL, z.B. https://gis.example.com:6443/arcgis. Über diese URL muss das ArcGIS Server Administratorverzeichnis (/arcgis/admin) erreichbar sein.

-s, --service [<Ordner>/]<Service-Name>

Ordner (optional) und Name des Kartenservice, für den die Zugriffsrechte-Datei gesetzt werden sollen. Beispiele: water/wells, SampleWorldCities.

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

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

Um den aktuellen Zustand der gesetzten Zugriffsrechte auf dem ArcGIS Server in der lokalen Verzeichnisstruktur abzubilden, kann die --reverse-Option verwendet werden.

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, z.B. https://gis.example.com:6443/arcgis. Über diese URL muss das ArcGIS Server Administratorverzeichnis (/arcgis/admin) erreichbar sein.

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

-s, --service [<Ordner>/]<Service-Name> (optional)

Beschränkt die Synchronisierung auf einen einzelnen Service, z.B. 'oceans' oder 'water/wells'.

-j, --jobs <Anzahl> (optional)

Ausführung von bis zu 'Anzahl' gleichzeitiger Update-Vorgänge (Standardwert: 8). Diese Option kann genutzt werden, um die Anzahl paralleler Update-Vorgänge zu reduzieren oder zu erhöhen.

--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, z.B. 'water,traffic'. '/' Bezeichnet das Stammverzeichnis.

--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 kehrt den Synchronisationsprozess um. Es werden keine Änderungen auf dem ArcGIS Server vorgenommen, statt dessen aber im lokalen Verzeichnis für Zugriffsrechte. Dies kann hilfreich sein, um die aktuell gesetzten Zugriffsrechte vom ArcGIS Server abzufragen und diese lokal zu speichern.

Wenn diese Option zusammen mit --include-folders verwendet wird, werden nur Dateien aus diesen Ordnern heruntergeladen. Nicht existierende Ordner werden angelegt.

groups

Mit diesem Kommando können Sie die Gruppen abfragen, die aktuell im ArcGIS Enterprise angelegt sind. In der Ausgabe werden die Gruppennamen, die Gruppen-IDs und die Eigentümer der Gruppen 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, z.B. https://gis.example.com:6443/arcgis. Über diese URL muss das ArcGIS Server Administratorverzeichnis (/arcgis/admin) erreichbar sein.

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

--by-title <Suchtext> (optional)

Beschränkt das Ergebnis auf Gruppen, die mit Hilfe des angegebenen Suchtextes gefunden werden. Dabei handelt es sich um eine Fuzzy-Suchfunktion des ArcGIS Portals.

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 kann der offiziellen Such-Referenz entnommen werden.

--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. Der Standardwert ist {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"
│   │   └── 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"
└── properties.json             // optional, enthält globale Eigenschaften
└── restrictions.json           // optional, enthält globale Einschränkungen

Globale Elemente für Zugriffsrechte

Eigenschaften

Im Zugriffsrechtverzeichnis können Sie globale Eigenschaften in einer properties.json-Datei definieren. 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.

Beispiel einer properties.json-Datei
{
    "$schema": "https://raw.githubusercontent.com/conterra/policies-json/1.0.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 globale 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.0.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.0.0/schema/policies.schema.json",
    "policies": [
        {
            "layers": [ "1", "2" ],
            "roles": [  "${group1}" ],
            "restrictions": [
                "restriction_only_Ireland"
            ]
        }
    ]
}