Verwaltung von Zugriffsrechten mit der CLI

Überblick

Neben der Möglichkeit Zugriffsrechte (policies) über security.manager NEXT Manager UI zu definieren, können Sie diese für einen Kartenservice alternativ über die Kommandozeile setzen. Das Kommandozeilenwerkzeug secmanctl stellt Kommandos zur Verfügung, um auf Kartenservices, manuell oder automatisiert, lokal verwaltete Zugriffsrechte setzen zu können. Die Dateien mit Zugriffsrechten für einen Kartenservice werden über die REST-Schnittstelle des ArcGIS Server Administratorverzeichnisses gesetzt. Zugriffsrechte müssen den Regeln des Zugriffsrechte-Formats des security.manager NEXT entsprechen.

Zugriffsrechte erstellen und synchronisieren

Das Setzen von Zugriffsrechten auf Kartenservices eines ArcGIS Servers mittels Kommandozeile umfasst folgende Schritte:

  1. Erstellen von Zugriffsrechten in einem lokalen Verzeichnis

  2. Ausführen von secmanctl login, um ein ArcGIS Server Authentifikationstoken zu erhalten

  3. Ausführen von secmanctl sync, um die lokal definierten Zugriffsrechte zu setzen

Schritt 1: Erstellen von Zugriffsrechten

Erstellen Sie zunächst ein Zugriffsrechtverzeichnis, das die Zugriffsrechte aller zu verwaltenden Kartenservices enthält. Der Name des Verzeichnisses kann beliebig gewählt werden, es empfiehlt sich allerdings der ArcGIS Server Hostname, wie zum Beispiel gis-test. In diesem Verzeichnis legen Sie nun den Unterordner services an.

Erstellen Sie unter gis-test/services, und analog zur Ordnerstruktur auf dem ArcGIS Server, für jeden zu schützenden Service eine JSON-Datei mit dem Namen des Service, z.B. SampleWorldCities.json. Die Zugriffsrechte müssen dem JSON-Format für Zugriffsrechte entsprechen.

In diesem Verzeichnis werden alle Zugriffsrechte der Kartenservices eines ArcGIS Servers verwaltet, ähnlich einer Datenbank. Um Änderungen an Zugriffsrechten nachverfolgen zu können, oder um die Daten zu sichern, empfiehlt sich die Verwendung eines Versionskontrollsystems, z.B. Git.

Nach der Bearbeitung der Dateien in gis-test/services/…​ müssen Sie die Zugriffsrechte auf dem ArcGIS Server setzen, bevor der security.manager NEXT diese anwenden kann. Das Setzen von Zugriffsrechten aus dem Verzeichnis wird Synchronisation genannt und ist im Schritt 3 beschrieben.

Bevor Sie Zugriffsrechte synchronisieren können, benötigen Sie ein ArcGIS Server Token.

Schritt 2: Erzeugen eines ArcGIS Server Tokens

Um ein ArcGIS Server Token zu erhalten, führen Sie das Kommando secmanctl login aus. Verwenden Sie einen ArcGIS Verbundserver, benötigen Sie dazu einen Account beim ArcGIS Enterprise-Portal mit Administrationsrechten, bei dem Multi-Faktor-Authentifizierung deaktiviert ist. Verwenden Sie stattdessen einen ArcGIS Server, der nicht mit einem Portal verbunden ist, benötigen Sie einen ArcGIS Server-Account mit Administrationsrechten.

$ secmanctl login -d https://gis-test.example.com:6443/arcgis -u adminuser

✔ Enter password: *********
Login successful.
Authenticated against: https://gis-test.example.com/portal
Valid until:           2020-11-11T13:12:03.802Z
Requires SSL:          Yes

Bo54NHPSbHoclN-wGQXhwWIpO_jX2bxk4xhMh7GK31y9I_qpjJZy00qAV_QRylGsPfgO7fcMv_QJmvn4FB5s_8kK0JTVyi8rzmDofpz175KXhAuH0SbGVsuqNZgJadEfkUP3pHG1pXuADoxP9JAeQ3-F9_5Q2UzXhQYQJpvpjgw.

Das Token wird in der letzten Zeile der Ausgabe ausgegeben. Speichern Sie das Token in einer Variable oder kopieren Sie es für weitere Kommandos.

Es gibt mehrere Möglichkeiten ein Passwort zu übergeben. Führen Sie secmanctl login --help aus, um mehr über die Optionen des Kommandos zu erfahren.

Schritt 3: Synchronisieren von Zugriffsrechten

Nachdem Sie ein Token erhalten haben, führen Sie secmanctl sync aus, um das Zugriffsrechtverzeichnis mit den gesetzten Zugriffsrechten auf dem ArcGIS Server zu synchronisieren. Bei der Ausführung werden auf dem Server alle Zugriffsrechte aktualisiert, die sich von den lokalen unterscheiden. Falls lokal eine Datei mit Zugriffsrechten für einen Service existiert, für den der security.manager NEXT noch nicht aktiviert wurde, so wird dieser beim Setzen der Regel aktiviert.

Die Synchronisation wird wie folgt ausgeführt:

$ secmanctl sync -f ./gis-test -d https://gis-test.example.com:6443/arcgis -t Bo54NHPSbHocl…
Synchronize './gis-test' to 'https://gis-test.example.com:6443/arcgis'

DIFFERENCE                CURRENT [-> DESIRED]
=======================   ================================
[<>] /SampleWorldCities   protected(modified) -> protected
[=>] admin/countries      unprotected -> protected

Applied 2 of 2 changes
Synchronization took 2.50 sec
[SUCCESS]

Das Kommando gibt zuerst alle Änderungen aus, bevor die veränderten Zugriffsrechte auf dem ArcGIS Server gesetzt werden. Im obigen Fall werden die Zugriffsrechte der Kartenservices SampleWorldCities und admin/countries aktualisiert. Für SampleWorldCities wurden die serverseitigen Zugriffsrechte mit den lokalen ersetzt. Für admin/countries wurde der security.manager NEXT aktiviert und die lokal vorhandenen Zugriffsrechte auf dem ArcGIS Server gesetzt.

Setzen Sie die Optionen -v oder -vv, um eine ausführlichere Ausgabe zu erhalten, die auch Services ohne Zustandsänderung auflistet.

Probelauf

Vor allem bei großen oder komplexen Änderungen an Zugriffsrechten ist es gute Praxis vor der eigentlichen Synchronisation einen Probelauf ("dry run") durchzuführen. Im --dry-Modus führt secmanctl sync keine Zustandsänderungen auf dem Server oder im Zugriffsrechtverzeichnis aus, sondern prüft lediglich auf Validierungsfehler oder zu setzende Änderungen. Diese werden wie folgt ausgegeben:

Probelauf des sync Kommandos
$ secmanctl sync -f ./gis-test -d https://gis-test.example.com:6443/arcgis -t Bo54NHPSbHocl… --dry
[DRY RUN] Nothing will be changed in this execution of 'sync'
Synchronize './gis-test' to 'https://gis-test.example.com:6443/arcgis'

DIFFERENCE                CURRENT [-> DESIRED]
=======================   ================================
[<>] /SampleWorldCities   protected(modified) -> protected

[DRY RUN] Applied 1 of 1 changes
Synchronization took 937 ms
[SUCCESS]

Im obigen Beispiel unterscheiden sich die gesetzten Zugriffsrechte von den lokalen Zugriffsrechten. Die Zustände aller anderen Kartenservices stimmen überein.

Sobald alle möglichen Änderungen zufriedenstellend sind, kann dasselbe Kommando ohne die --dry Option ausgeführt werden, um die Änderungen tatsächlich auszuführen.

Übliche Aufgaben

Validierung von Zugriffsrechten

Die --dry Option kann verwendet werden, um lokale Zugriffsrechte auf syntaktische Korrektheit zu überprüfen. Vor dem Setzen von Zugriffsrechten mittels secmanctl apply oder secmanctl sync, werden die entsprechenden JSON-Dateien aus dem Zugriffsrechtverzeichnis validiert. Invalide Dateien werden nicht gesetzt und es wird ein entsprechender Status ausgegeben.

Das folgende Beispiel zeigt die Ausgabe eines apply Kommandos im Falle einer invaliden JSON-Datei:

$ secmanctl apply -i us_airports_invalid.json -d https://gis-test.example.com:6443/arcgis -t MghzyNeWubQtTgZfMQTx8rasda.. -s us_airports --dry
[DRY RUN] Nothing will be changed in this execution of 'apply'

DIFFERENCE                CURRENT [-> DESIRED]
=======================   ================================
[ER] /us_airports.json    invalid

[DRY RUN] No changes found
[ERROR]
Errors occurred during analysis of changes:
    '/us_airports_invalid.json':
        Error: Validation error: Undefined restriction 'DOES_NOT_EXIST'.

Errors detected, please check the output above.

Sicherung von Zugriffsrechten vom ArcGIS Server

Quelle und Ziel des sync Kommandos können mit der --reverse Option vertauscht werden, um die serverseitig gesetzten Zugriffsrechten lokal herunterladen zu können. Dies kann hilfreich sein, wenn Sie eine Sicherung vom aktuellen Zustand der gesetzten Zugriffsrechte auf dem ArcGIS Server machen wollen.

Verwenden Sie die --reverse-Option nicht, um die Zugriffsrechte auf dem ArcGIS Server mit Ihrem lokales Zugriffsrechtverzeichnis zu synchronisieren, sonst werden vorhandene Zugriffsrechte überschrieben.

Das folgende Beispiel zeigt die Anwendung der --reverse Option:

$ secmanctl sync --reverse -f ./gis-test -d https://gis-test.example.com:6443/arcgis -t MghzyNeWubQtTgZfMQTx8ras..
Synchronize 'https://gis-test.example.com:6443/arcgis' to './gis-test'

DIFFERENCE                CURRENT [-> DESIRED]
=======================   ================================
[=>] /SampleWorldCities   unprotected -> protected
[=>] water/wells          unprotected -> protected
[=>] water/bassins        unprotected -> protected

Applied 3 of 3 changes
Synchronization took 674 ms
[SUCCESS]

Als Ergebnis wurden drei JSON-Dateien mit Zugriffsrechten heruntergeladen und im angegebenen Verzeichnis gespeichert.

Zugriffsrechte aus ausgewählten Ordnern setzen

Das sync Kommando bietet mit der --include-folders Option die Möglichkeit, ausgewählte Ordner mit dem ArcGIS Server zu synchronisieren.

Das folgende Beispiel zeigt wie ausschließlich der Ordner water synchronisiert werden kann:

$ secmanctl sync -v -f ./gis-test -d https://gis.example.com:6443/arcgis -t MghzyNeWubQtTgZfMQTx8rasda.. --dry --include-folders water
[DRY RUN] Nothing will be changed in this execution of 'sync'
Synchronize './gis-test' to 'https://gis-test.example.com:6443/arcgis'

DIFFERENCE                CURRENT [-> DESIRED]
===================   ================================
[<>] water/wells      protected(modified) -> protected
[<>] water/bassins    protected(modified) -> protected

[DRY RUN] Applied 2 of 2 changes
[SUCCESS]
Durch die Angabe von --include-folders / erfolgt die Synchronisation nur mit den Services, die direkt innerhalb des Stammverzeichnisses liegen.

Besonders in der Kombination mit der --delete Option kann es sinnvoll sein, die --include-folders Option zu verwenden. Auf diese Weise werden bei der Synchronisation nur die Zugriffsrechte gelöscht, die sich auf dem ArcGIS Server innerhalb des angegebenen Ordners befinden.

Offline-Editierung für einen geschützten Feature-Service aktivieren

Erzeugen Sie für den geschützten Feature-Service eine Konfigurationsdatei in der Form <servicename>.conf.json. Die Datei muss im Zugriffsrechtverzeichnis parallel zum JSON-File <servicename>.json abgelegt sein.

Fügen Sie folgenden Inhalt hinzu:

{
    "soi.supportReplicas": true
}

Wenden Sie die Konfiguration mittels sync-Kommando zusammen mit den definierten Zugriffsrechten auf dem Server an.

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

Synchronize './gis-test' to 'https://dev0259w.conterra.de/arcgis'

DIFFERENCE                          CURRENT [-> DESIRED]
================================    ================================
[<>] sandbox/aviation_editing       protected(modified) -> protected

Applied 1 of 1 changes
Synchronization took 953 ms
[SUCCESS]
Additional information:
    'sandbox/aviation_editing':
        Note: Replica support was set to 'true'

Referenzieren von Gruppen-IDs durch die Verwendung von Eigenschaften

Das JSON-Ausgabeformat des Kommandos groups hilft, besser lesbare Zugriffsrechte zu definieren. Das gilt insbesondere, wenn Sie einen ArcGIS Verbundserver absichern, denn in diesem Fall müssen Sie die technischen IDs von Portal-Gruppen statt deren Namen als Rollen in den Zugriffsrechten verwenden.

Das folgende Beispiel zeigt die Ausgabe des groups Kommandos mit der --json Option für einen Verbundserver.

$ secmanctl groups -d https://gis-test.example.com:6443/arcgis -t MghzyNeWubQtTgZfMQTx8rasda.. --json

{
    "any_user": "enhancedSecurity_any",
    "authenticated_users": "enhancedSecurity_authenticated",
    "dezernat_a": "49537170bc3041e1b291d7146290d51c",
    "featured_maps_and_apps": "345c76ba732a4a7bac4227bb6c3aa701",
    "others": "84ac890b7627461e8b0dd0376bb8a0c2"
}

Sie können die Ausgabe verwenden, um innerhalb eines Zugriffsrechts Eigenschaften ("properties") zu deklarieren. Diese können Sie dann an anderer Stelle referenzieren.

Im folgenden Beispiel wird die ID der Gruppe dezernat_a mit dem Ausdruck ${dezernat_a} referenziert.

{
  "properties": {
      "dezernat_a": "49537170bc3041e1b291d7146290d51c",
      "featured_maps_and_apps": "345c76ba732a4a7bac4227bb6c3aa701",
      "others": "84ac890b7627461e8b0dd0376bb8a0c2"
  },
  "policies": [
      {
          "layers": ["0", "1"],
          "roles": ["${dezernat_a}"]
      }
  ]
}

Mit der Möglichkeit globale Zugriffsrecht-Elemente zu definieren, können Gruppennamen in der globalen Datei properties.json als Eigenschaften definiert werden. In diesem Fall ist es sinnvoll, ein gemeinsames Präfix für Gruppen wie group_ zu verwenden. Über die Option --json-key-pattern können Sie die Namen der Eigenschaften flexibel erzeugen.

$ secmanctl groups -d https://gis-test.example.com:6443/arcgis -t MghzyNeWubQtTgZfMQTx8rasda.. --json --json-key-pattern 'group_{title}'

{
    "group_any_user": "enhancedSecurity_any",
    "group_authenticated_users": "enhancedSecurity_authenticated",
    "group_dezernat_a": "49537170bc3041e1b291d7146290d51c",
    "group_featured_maps_and_apps": "345c76ba732a4a7bac4227bb6c3aa701",
    "group_others": "84ac890b7627461e8b0dd0376bb8a0c2"
}

Umleitung der Ausgabe in eine Datei

Während der Verarbeitung von Befehlen werden Informationen auf die Standard-Ausgabe stdout geschrieben. Fehler werden auf stderr geschrieben.

stdout und stderr können wie folgt in Dateien umgeleitet werden (Beispiele für Microsoft Windows):

  • Die Ausgabe von stdout in eine Datei umleiten

    • secmanctl …​ > out.txt

    • Alle normalen Informationen werden in die Datei out.txt geschrieben, Fehler werden nicht geschrieben.

  • Die Ausgaben von stdout und stderr werden in eine Datei umgeleitet

    • secmanctl …​ > out.txt 2>&1

    • Die Ausgaben beider Datenströme werden in die Datei out.txt geschrieben.

Eigene TLS/SSL Zertifikate akzeptieren

Die security.manager NEXT CLI basiert auf Node.js , welches wie einige Browser über eine eigene Verwaltung vertrauenswürdiger Root CA (Certificate Authority) Zertifikate verfügt. Sie können eigene vertrauenswürdige Zertifikate (z.B. einer firmeninternen Root CA) mittels der NODE_EXTRA_CA_CERTS Umgebungsvariable konfigurieren (Offizielle Dokumentation ). Die Variable muss den Pfad zu einer Datei enthalten, die ein oder mehrere Zertifikate im PEM Format enthält.

Beispiel (Linux shell)
$ NODE_EXTRA_CA_CERTS=/path/to/certs.pem secmanctl login -d $SERVER
Beispiel (Windows Command Prompt)
> set NODE_EXTRA_CA_CERTS=C:\path\to\certs.pem
> secmanctl.exe login -d %SERVER%

Das Setzen von Zugriffsrechten automatisieren

Zur Ausführung von secmanctl apply oder secmanctl sync ist ein Authentifizierungs-Token für den ArcGIS Server erforderlich. Dieses Token kann mit secmanctl login über den ArcGIS Server erzeugt werden.

Wenn Sie die Ausführung von Befehlen automatisieren wollen, z.B. im Kontext einer Build-Pipeline, kann der Befehl login ausgeführt und das Token an den folgenden Aufruf von apply oder sync übergeben werden.

Das folgende Beispiel zeigt ein Beispiel für eine Batch-Datei, wie sie unter Microsoft Windows verwendet werden kann:

automate_sync.bat
@echo off
rem Script Variables
set secmanctl=".\bin\secmanctl.exe"
set SERVER="https://gis-test.example.com:6443/arcgis"
set ROOT=".\gis-test"

rem login
call %secmanctl% login -d %SERVER% -u admin -p pw.txt --plain > token.txt
set /p TOKEN=<token.txt
del token.txt

rem sync
call %secmanctl% sync -d %SERVER% -f %ROOT% -t %TOKEN%

Für ein Shell-Skript unter Linux kann eine automatisierte Anmeldung analog implementiert werden:

automate_sync.sh
# Script Variables
secmanctl="./bin/secmanctl"
SERVER="https://gis-test.example.com:6443/arcgis"
ROOT="./gis-test"

#login
TOKEN=$($secmanctl login -d $SERVER -u admin -p pw.txt --plain)

# sync
$secmanctl sync -d $SERVER -f $ROOT -t $TOKEN