Konfiguration

Konfigurationsdateien

Konfigurationsdateien werden vom Identity Service in der folgenden Reihenfolge verarbeitet:

  1. WEB-INF/classes/default-application.properties (NICHT VERÄNDERN)
    In dieser Datei befinden sich alle Konfigurationsoptionen mit ihren Standardwerten.

  2. WEB-INF/classes/custom-application.properties
    Wenn eine Änderung des Datenverzeichnis (data.directory.location) nötig ist, muss die Änderung in dieser Datei erfolgen. Alle weiteren Anpassungen erfolgen in der nachfolgenden Datei.

  3. [data.directory.location]/application.properties
    Das Bearbeiten dieser Datei ist der empfohlene Weg Konfigurationsänderungen vorzunehmen. Das Datenverzeichnis (data.directory.location) ist in der Standardinstallation das Verzeichnis ${user.home}/.identity-service.

Das Format der Konfigurationsdateien muss dem Java Properties Dateiformat entsprechen.

Beispiel .properties
# Die Dateien müssen UTF-8 kodiert sein, sonst können Umlaute zu Fehlern führen!
# Am sichersten ist die Kodierung von Umlauten in Unicode-Syntax z.B: ä = \u00E4 (vgl. http://0xcc.net/jsescape/)

# Kommentare erfolgen mit Raute

# die Syntax ist:
key = value

# Eine Value kann einen anderen Key referenzieren
key1 = http://${key.with.server}/test

Umgebungsvariablen

Sie können die Werte aller Konfigurationsparameter auch mit Umgebungsvariablen setzen. Diese überschreiben immer die Werte, die Sie in den application.properties setzen. Das ist hilfreich, wenn der Identity Service zum Beispiel in einem Docker-Container betrieben wird.

Sie müssen die Namen der Konfigurationsparameter aus den application.properties für die Verwendung als Umgebungsvariablen anpassen: Ersetzen Sie alle Buchstaben des Namen durch Großbuchstaben sowie den Punkt . durch den Unterstrich _.

Beispiel: security.oauth.provider wird zu SECURITY_OAUTH_PROVIDER. Dieses Muster gilt für alle Konfigurationsparameter.

Konfigurationsparameter

Allgemeine Einstellungen

In diesem Abschnitt werden die Parameter beschrieben, die am häufigsten in einer Standardinstallation verändert werden müssen. Weitere Parameter sind in der Datei WEB-INF/classes/default-application.properties in Kommentaren beschrieben.

data.directory.location

Datenverzeichnis, in das die lokale Konfiguration der Manager UI abgelegt wird.

Für den Fall, dass der Tomcat-Server als Windows-Dienst betrieben wird, liegt das .identity-service Verzeichnis im Nutzerverzeichnis des Tomcat-Nutzers, der den Dienst gestartet hat. Pfad-Trenner müssen entweder als / oder \\ angegeben werden.

Tomcat Nutzer
Wenn kein Tomcat-Nutzer angelegt wurde, wird der Tomcat-Server mit dem Systemnutzer ausgeführt (nicht empfohlen!). In diesem Fall wird das Verzeichnis unter folgendem Pfad angelegt: C:/Windows/System32/config/systemprofile/.identity-service or %systemroot%/ServiceProfiles/LocalService/.identity-service.

Ein abweichendes Datenverzeichnis kann in der Datei WEB-INF/classes/custom-application.properties konfiguriert werden.

Standardwert: $\{user.home\}/.identity-service

configuration.watch.changes

Überwachung der Datei ${data.directory.location}/application.properties.

Bei Aktivierung können Konfigurationseinstellungen ohne Neustart der Web-Applikation geändert werden. Die Konfigurationsdatei muss beim Starten der Web-Applikation vorhanden sein, damit sie überwacht werden kann.

Standardwert: true

Datenbank-Anbindung

Identity Service verwendet standardmäßig eine HSQL-Datenbank, die in der Auslieferung enthalten ist. Sie wird zu Testzwecken automatisch im Dateisystem erstellt und erfordert keine weitere Konfiguration.
Verwenden Sie die HSQL-Datenbank nicht in produktiven Umgebungen.

HSQLDB

Mehrere parallele Installationen von Identity Service können nicht auf dieselbe HSQL-Datenbank verweisen. Ändern Sie in diesem Fall für eine Instanz den Parameter data.directory.location.

Microsoft SQL Server

Setzen Sie bei Verwendung von Microsoft SQL Server bei der Anlage der Datenbank die Collation auf ein case-sensitives Format (zum Beispiel Latin1_General_CS_AS).

Ändern Sie die Datenbankverbindung, indem Sie die folgenden Eigenschaften bearbeiten:

db.use

Legt fest, ob eine direkte Datenbankverbindung (JDBC) oder eine container-managed Datenbankverbindung (JNDI) aufgebaut wird.

Verwenden Sie JNDI, wenn mehrere Webanwendungen im Container (z.B. Apache Tomcat) vorhanden sind, die auf dieselbe Datenbank zugreifen (siehe Apache Tomcat JNDI-Dokumentation ). Bei JDBC ist keine Container-Konfiguration notwendig.

Erlaubte Werte: jndi, jdbc
Standardwert: jdbc

db.type

Herstellerspezifischer Typ des verwendeten Datenbanksystems.

Dieser wird intern verwendet, um korrekte und optimierte Datenbankanfragen zu erzeugen.

Erlaubte Werte:

Datenbank Typ Beispiel-URL

PostgreSQL

postgresql

jdbc:postgresql://localhost:5432/identity

Oracle Database

oracle

jdbc:oracle:thin:@myhost:1521:orcl

Microsoft SQL Server

sqlserver

jdbc:sqlserver://localhost:1433;databaseName=identity

HSQLDB

hsqldb

jdbc:hsqldb:file:$\{data.directory.location\}/storage/db;shutdown=true

Standardwert: hsqldb

db.hibernate.schemaUpdate

Definiert, ob und wie das Datenbankschema automatisch angepasst wird.

Erlaubte Werte: validate, update
Standardwert: update

Direkte Datenbankverbindung (JDBC)

Um eine direkte Datenbankverbindung zu nutzen, konfigurieren Sie zusätzlich zu den drei o.g. Parametern die folgenden Werte:

db.jdbc.url

JDBC Datenbankverbindungs-URL.

Dieser Wert ist vom verwendeten Datenbanksystem abhängig (siehe oben stehende Tabelle).

Standardwert: jdbc:hsqldb:file:$\{data.directory.location\}/storage/db;shutdown=true

db.jdbc.username

Login-Name des Datenbankzugangs.

Standardwert: sa

db.jdbc.password

Passwort des Datenbankzugangs.

db.jdbc.maxActiveConnections

Maximale Anzahl aktiver Datenbankverbindungen im verwendeten Connection-Pool.

Standardwert: 50

db.jdbc.minActiveConnections

Minimale Anzahl aktiver Datenbankverbindungen im verwendeten Connection-Pool.

Standardwert: 1

Wenn eine JDBC-Verbindung verwendet wird, muss der für die Datenbank passende JDBC-Treiber in das Verzeichnis %IDENTITY_SERVICE%/WEB-INF/lib kopiert werden.

Container-managed Datenbankverbindung (JNDI)

Um eine Datenbankverbindung über JNDI einzurichten, müssen zusätzlich zu den drei o.g. Parametern die folgenden Werte konfiguriert werden:

db.jndi.name

JNDI-Name, über den die Datenbank vom Container erfragt werden kann.

Standardwert: java:comp/env/jdbc/identity

Darüber hinaus sind folgende Schritte in der Konfiguration des Tomcats zu befolgen:

  1. Öffnen Sie die Datei server.xml, die sich im Verzeichnis conf des Apache Tomcat befindet.

  2. Fügen Sie zum Element <GlobalNamingResources> das folgende Element hinzu:

    server.xml
    <Resource name="identitydb" auth="Container"
      type="javax.sql.DataSource"
      maxTotal="50"
      maxIdle="1"
      maxWaitMillis="10000"
      defaultAutoCommit="false"
      username="postgres"
      password="postgres"
      driverClassName="org.postgresql.Driver"
      url="jdbc:postgresql://localhost:5432/identity" />

    Dieses Element ist beispielhaft auf die PostgreSQL-Datenbank angepasst. Wenn Sie eine andere Datenbank als PostgreSQL verwenden, passen Sie die Attribute driverClassName und URL an. In der oben stehenden Tabelle sind die Werte für die verschiedenen Datenbanken aufgeführt.

  3. Passen Sie die Attribute username und password des Elements an die Gegebenheiten in Ihrem System an.

  4. Kopieren Sie die JAR-Datei des von Ihnen verwendeten JDBC-Datenbanktreibers in das Verzeichnis lib des Apache Tomcat.

  5. Öffnen Sie die Datei context.xml im Verzeichnis META-INF der Identity Service-Webanwendung und entfernen Sie die Kommentare um das Element <ResourceLink name="jdbc/identity" global="identitydb" type="javax.sql.DataSource"/>, um es zu aktivieren.

  6. Speichern Sie alle veränderten Dateien und starten Sie Apache Tomcat neu.

Container-managed Datenbankverbindung (JNDI mit HikariCP)

Wir empfehlen die Verwendung des Datenbank Connection Pool HikariCP .

Die Konfiguration in der server.xml ändert sich dann wie folgt:

server.xml
<Resource name="identitydb" auth="Container"
        factory="com.zaxxer.hikari.HikariJNDIFactory"
        type="javax.sql.DataSource"
        minimumIdle="1"
        maximumPoolSize="50"
        connectionTimeout="10000"
        dataSourceClassName="org.postgresql.ds.PGSimpleDataSource"
        dataSource.url="jdbc:postgresql://localhost:5432/identity"
        dataSource.user="postgres"
        dataSource.password="postgres" />

Zusätzlich müssen neben dem Datenbanktreiber folgende Bibliotheken im Tomcat lib Verzeichnis ergänzt werden:

Konfiguration des Loggings

logging.logger.level

Detailgrad des Log-Nachrichten

Mögliche Werte: TRACE, DEBUG, INFO, WARN, ERROR
Standardwert: WARN

logging.file.location

Ort, an dem die Log-Datei gespeichert wird.

Der Standardwert entspricht dem logs Verzeichnis des Tomcat. Es ist möglich, die Log-Datei im Datenverzeichnis von Identity Service zu erzeugen, in dem der Wert ${data.directory.location}/logs verwendet wird.

Standardwert: ${catalina.base}/logs

logging.file.prefix

Namen der Log-Dateien.

Standardwert: ct-identity-service

Zusätzliche Logging-Optionen werden in der Datei default-application.properties beschrieben, z.B. zum Aktivieren oder Deaktivieren des Loggings in die Konsole, in Dateien und GELF-Protokollierung.

Sicherheitseinstellungen

Eine Änderung der Einstellungen hat üblicherweise keinen Einfluss auf aktive Sitzungen. Neue Einstellungen werden erst nach einem erneuten Login eines Nutzers übernommen. Aktive Sitzungen können sofort beendet werden sollen, indem der Wert der Eigenschaft security.sharedSecret verändert wird.
security.ssl.trustAny

Aktiviert die Unterstützung für selbst signierte Zertifikate bei HTTPS-Verbindungen.

Aktivieren Sie diese Einstellung in Produktionsumgebungen nicht.

Erlaubte Werte: true, false
Standardwert: false

security.login.redirect.trusted.hosts

Komma-separierte Liste von akzeptierten Hostnamen.

Diese Liste definiert, welche Ziele zur Weiterleitung (Redirect) akzeptiert werden, wenn Identity Service am Ende des Login-Prozesses den Browser zur nächsten Seite weiterleitet. Dies stellt sicher, dass Angreifer niemanden unter Vorlage einer entsprechenden URL auf eine bösartige Seite lenken können.

Wenn eine Applikation zum Login auf Identity Service umleitet und die Applikation unter einem anderen Hostnamen als Identity Service aufgerufen wird, müssen hier die entsprechenden Hostnamen hinzugefügt werden. Dies ist z.B. häufig bei der Nutzung von Entwicklungsprojekten der Fall.

Sie können Wildcards verwenden, um z.B. Redirects auf alle Rechner einer Domäne zu erlauben.

Standard: localhost
Beispiel: *.gishost.org

security.oauth.clientId

OAuth Client-ID, die im Rahmen der Registrierung des Identity Service am Identitätsanbieter vergeben wurde.

security.oauth.clientSecret

OAuth Client-Secret, das im Rahmen der Registrierung des Identity Service am Identitätsanbieter vergeben wurde.

security.oauth.token.minimalLifetimeSecondsLeft

Minimale Lebensdauer eines Zugriff-Tokens in Sekunden, bevor es erneuert werden sollte.

security.oauth.provider

Definiert den aktuellen Identitätsanbieter. Mögliche Werte sind arcgis oder keycloak.

security.oauth.provider.arcgis.url

Die URL zum ArcGIS Enterprise-Portal oder zur ArcGIS Online Organisation. Beispiel: https://myorg.maps.arcgis.com oder https://www.example.com/portal.

security.oauth.provider.arcgis.url.internal

Die URL zum ArcGIS Enterprise-Portal, welche für die interne Kommunikation verwendet werden soll. Die Konfiguration ist optional, standardmäßig wird der Wert von security.oauth.provider.arcgis.url verwendet. Beispiel: https://myhost.example.com/portal.

security.oauth.provider.arcgis.organizations

Wenn Sie security.oauth.provider.arcgis.url=https://www.arcgis.com gesetzt haben, können Sie hierüber das Login auf bestimmten ArcGIS Online Organisationen einschränken. Geben Sie mehrere Organisationen als Komma-separierte Liste an. Beispiel: myorg.maps.arcgis.com,anotherorg.maps.arcgis.com

security.oauth.provider.arcgis.roles

Definiert eine Übersetzung von Rollen- und Gruppennamen aus dem ArcGIS Enterprise-Portal oder ArcGIS Online in angepasste Rollennamen. Applikationen, die mit dem Identity Service verbunden sind, können dann die angepassten Rollennamen verwenden. Die Syntax ist folgende: <name1>=<role1>,<role2>; <name2>=<role3>

Beispiel: Der Wert org_admin=maAdmin,otherAdmin; Editors::admin=maEditor definiert, dass die Rolle org_admin als maAdmin und otherAdmin verfügbar gemacht wird. Außerdem wird die Gruppe Editors des Gruppenbesitzers admin in die Rolle maEditor übersetzt.

Anstatt Gruppenname und Besitzer anzugeben kann auch die ID der Gruppe verwendet werden:

Beispiel: Der Wert org_admin=maAdmin,otherAdmin; 12a12ab1a1a12345678abc1abc1abcd1=maEditor definiert, dass die Gruppe 12a12ab1a1a12345678abc1abc1abcd1 in die Rolle maEditor übersetzt wird.

Der Standardwert ist org_admin=maAdmin,solrAdmin,mon_Administrator,tc_Administrator;org_publisher=maEditor.

security.oauth.provider.arcgis.roles.encodeGroupsWithTitleAndOwner

Dieser Wert legt fest, ob Gruppen aus ArcGIS Enterprise-Portal oder ArcGIS Online in der Form 'Titel::Besitzer' kodiert werden sollen.

Ist der Wert true werden Gruppen in der Form Titel::Besitzer kodiert. Ist der Wert false erfolgt diese Kodierung nicht und die ID der Gruppe wird verwendet.

Der Standardwert ist true.

security.oauth.provider.arcgis.roles.includeMappedRolesOnly

Wenn der Wert true ist, werden nur Rollen ausgegeben, die in security.oauth.provider.arcgis.roles definiert sind. Wenn der Wert false ist, werden hingegen alle Rollen ausgegeben.

Der Standardwert ist true.

security.oauth.provider.keycloak.url

Die Basis-URL von Keycloak, z.B. https://www.example.com/authn

security.oauth.provider.keycloak.realm

Der Name des Keycloak-Realm, für den Zugriffe erlaubt sind.

security.oauth.provider.keycloak.scopes

Erlaubt die Definition von eigenen OpenID Connect-Scopes, die beim Login und beim Abfragen von Tokens gesendet werden. Wenn der Wert leer ist, wird standardmäßig openid,profile,email,offline_access verwendet.

security.oauth.provider.keycloak.revokeRefreshTokens

Aktiviert das Widerrufen von Refresh-Tokens während eines Logouts oder wenn eine Nutzersession abläuft. Das Widerrufen führt als Nebeneffekt zu einem globalen Logout des Nutzers am Keycloak. Um dieses Verhalten zu deaktivieren, setzen Sie den Wert auf false.

security.oauth.tokenRules

Definiert, an welche URLs das Senden von Zugriffs-Token erlaubt ist und wie diese übertragen werden sollen.

Der Wert ist eine Semikolon-separierte Liste von Regeln: <rule_1>[;<rule_n>]…​

Eine Regel ist eine Komma-separierte Liste von URLs gefolgt von einem Transportnamen: <url_1>[,<url_n>]…​[,<transport_mode>]

Unterstützte Transportnamen sind:

  • BEARER (default): Das Token soll als HTTP Header Authorization: Bearer <token> gesendet werden.

  • TOKEN: Das Token soll als URL Query Parameter …​&token=<token> gesendet werden.

  • ACCESS_TOKEN: Das Token soll als URL Query Parameter …​&access_token=<token> gesendet werden.

Beispiel:

http://www.example.com/arcgis,TOKEN;http://other.example.com/service1,http://other.example.com/service2,ACCESS_TOKEN

Das Beispiel definiert, dass ein Zugriffs-Token an http://www.example.com/arcgis als …​&token=<token> gesendet werden soll. Außerdem soll ein Zugriffs-Token an http://other.example.com/service1 und http://other.example.com/service2 , als …​&access_token=<token> gesendet werden.

Der Prefix deny: vor einer URL definiert, dass keine Zugriffs-Tokens an diese URL gesendet werden sollen. Beispiel: deny:http://my.example.com/service;

Einige Regeln werden automatisch für den konfigurierten Identitätsanbieter und den Identity Service erzeugt.

security.session.maxIdleTimeInSeconds

Die erlaubte Leerlaufzeit für Sitzungen in Sekunden. Sitzungen, die länger als dieser Wert nicht genutzt werden, werden durch eine Hintergrundaufgabe ungültig gemacht. Der Standardwert ist 3600 Sekunden (eine Stunde).

security.session.cookieName

Der Name des Sitzungs-Cookie. Der Standard ist ctIDENTITY.

security.session.cookieDomain

Der Name der Domain des Sitzungs-Cookie, z.B. example.com. Standardmäßig ist das Sitzungs-Cookie an keine Domain gebunden.

security.session.enforceSecureAndSameSiteNone

Erzwingt die Flags samesite=none und secure am Sitzungs-Cookie. Diese Einstellung kann für die Realisierung von Cross Domain Szenarien relevant sein. Der Standardwert ist false.

security.sharedSecret

Der Text, den Sie hier eintragen, wird als Schlüssel ("shared secret") für die Verschlüsselung von Daten verwendet, die zwischen verschiedenen Anwendungsteilen ausgetauscht werden müssen. Um unautorisierten Zugriff oder die Manipulation von Daten zu verhindern, muss der Schlüssel so vertraulich wie ein Passwort behandelt werden. Sie müssen den Schlüssel selbst erstellen. Er muss aus Sicherheitsgründen mindestens eine Länge von 32 Zeichen haben.

Einen sicheren Schlüssel erzeugen Sie beispielsweise mit diesen Kommandos:

Windows PowerShell
> [Convert]::ToBase64String((1..32|%{[byte](Get-Random -Minimum ([byte]::MinValue) -Maximum ([byte]::MaxValue))}))
Linux
$ openssl rand -base64 32

CORS-Einstellungen

Diese Einstellungen werden benötigt, um Cross Origin Requests zu ermöglichen.

cors.allowed.origins

Liste von Basis-URLs von Webseiten, die per CORS auf die angebotenen Serviceschnittstellen zugreifen dürfen.

* kann als Platzhalter genutzt werden.

Beispiele:

  • http://mydomain.net,http://otherdomain.de

  • http*://*.mydomain.net:*
    Das Beispiel erlaubt den Zugriff von jeder Subdomäne von mydomain.net via http and https von jedem Port.