CARA3 Konfiguration

Referenz: [CARA3_Konfiguration]

Versionsinformationen

In der folgenden Tabelle finden Sie die Änderungshistorie des vorliegenden Dokuments.

Version Bemerkung

3.8.0

Initiale Version des Dokuments

application.properties des CARA-Servers

In der Datei application.properties konfigurieren Sie die Anbindung des CARA-Servers an die Datenbank, seine Erreichbarkeit über HTTP oder HTTPS sowie die Verbindung zu Keycloak. Die Datei enthält außerdem Einstellungen für Hintergrundprozesse, Zertifikatsfunktionen und optionale CARA-Module. Einstellungen für optionale CARA-Module gelten nur, wenn das jeweilige Modul verwendet wird.

Die mitgelieferte Datei application.template.properties dient als Vorlage. Passen Sie insbesondere Datenbankverbindungen, Serveradressen und Zugangsdaten an Ihre Installation an.

Die folgenden Tabellen beschreiben die Konfigurationsparameter in application.properties. Die Spalte „Erforderlich“ zeigt, ob und unter welchen Bedingungen ein Konfigurationsparameter gesetzt werden muss. „Default“ nennt die Standardwerte einschließlich der Vorgaben aus application.template.properties. „–“ in der Spalte „Default“ bedeutet, dass hier kein allgemeiner Standardwert angegeben ist; ein leerer String ist davon zu unterscheiden.

Allgemeine Servereinstellungen und Logging

Diese Konfigurationsparameter betreffen die Identifikation der CARA-Instanz, das Logging und den Betrieb der Hintergrundprozesse. Sie legen außerdem das Standardverzeichnis für den Export von Domain-Dateien fest.

Konfigurationsparameter Erforderlich Default Beschreibung

application.key

nein

CARA-WS

Vom Betreiber vergebener Identifier zur Unterscheidung verschiedener CARA-Instanzen im Cluster-Betrieb; kann in den Logdateien als Teil des ThreadContext ausgegeben werden; sinnvoll v. a. bei Verwendung eines Log4j-2-Servers für SocketAppender, da hier Logmeldungen verschiedener CARA-Instanzen in dieselbe Datei geschrieben werden könnten.

logging.config

nein

–

Pfad zur Log4j-2-Konfigurationsdatei. Kann in application.properties oder beim Start als JVM-Systemparameter angegeben werden. In der mitgelieferten Log4j-2-Konfigurationsvorlage ist $LOG_DIR$ durch das gewünschte Logverzeichnis zu ersetzen.

Beispiel: -Dlogging.config=/some/path/log4j2.xml

caraModuleId

ja

0

Die ID des CARA-Moduls.

Dieser Wert muss in der Regel nie geändert werden. Er sollte immer den Wert 0 haben.

startScheduler

ja

true

Dieser Wert legt fest, ob der Scheduler zum Starten von Hintergrundprozessen gestartet werden soll.

Dieser Wert sollte immer auf true gesetzt werden.

scheduler.export.defaultDir

nein

export/

Der Pfad eines Verzeichnisses, in welchem vom "ExportProcessor" exportierte Domain-Dateien abgelegt werden.

Datenbank und Flyway

Die Datenbankkonfiguration umfasst die Verbindungsdaten und den Connection-Pool. Die Flyway-Einstellungen bestimmen, ob das Datenbankschema automatisch eingerichtet oder über Migrationsskripte aktualisiert wird.

Datenbankverbindung und Connection-Pool

Konfigurieren Sie zunächst die Verbindung zur CARA-Datenbank. Die weiteren Parameter steuern die Größe des Connection-Pools, Wartezeiten und die Prüfung ungenutzter Verbindungen.

In der Konfigurationsvorlage ist für jeden unterstützten Datenbanktyp eine Konfiguration vorhanden. Die zum verwendeten Datenbanksystem gehörende Konfiguration muss aktiviert werden; alle anderen müssen auskommentiert werden.

Konfigurationsparameter Erforderlich Default Beschreibung

jdbc.driver-class-name

ja

–

JDBC-Treiber-Klasse für die verwendete Datenbank.

Die passende Treiberklasse wird aus der mitgelieferten Konfigurationsvorlage übernommen.

jdbc.url

ja

–

Definition der Verbindung zur CARA-Datenbank. In der mitgelieferten Konfigurationsvorlage ist $DB_SERVER$ durch den Namen des Datenbankservers und $DB_INSTANCE$ durch den Namen der Datenbankinstanz zu ersetzen. Verwenden Sie die zum Datenbanksystem passende URL.

jdbc.username

ja

–

Benutzername für den Zugriff auf die CARA-Datenbank. Entspricht dem Platzhalter $DB_USER$ in der Konfigurationsvorlage.

jdbc.password

ja

–

Passwort für den Zugriff auf die CARA-Datenbank. Entspricht dem Platzhalter $DB_PASSWORD$ in der Konfigurationsvorlage.

jdbc.initial-size

nein

0

Anzahl initialer Verbindungen zur Datenbank.

jdbc.max-active

nein

8

Maximale Anzahl von Verbindungen, die gleichzeitig genutzt werden können.

jdbc.max-idle

nein

8

Maximale Anzahl unbenutzter Verbindungen im Connection-Pool.

jdbc.min-idle

nein

0

Minimale Anzahl unbenutzter Verbindungen im Connection-Pool.

jdbc.max-wait

nein

30000

Maximale Zeitspanne, die ein Prozess wartet, um eine Verbindung aus dem Connection-Pool zu bekommen. Ist diese Zeitspanne überschritten, wird eine Exception geworfen. (in Millisekunden)

jdbc.time-between-eviction-runs-millis

nein

60000

Zeitspanne zwischen zwei Überprüfungen auf Idle-Connections (in Millisekunden).

jdbc.num-tests-per-eviction-run

nein

–

Anzahl von Verbindungen, die bei einer Überprüfung von Idle-Connections geprüft werden.

jdbc.min-evictable-idle-time-millis

nein

120000

Zeitspanne, die eine Connection unbenutzt im Connection-Pool verbleiben darf, bevor sie überprüft wird.

jdbc.connection-properties

nein

Leerer String

Konfigurationsparameter, die vom JDBC-Treiber unterstützt werden.

Die unterstützten Konfigurationsparameter sind der Beschreibung des verwendeten JDBC-Treibers zu entnehmen.

jdbc.init-sql

nein

Leerer String

SQL-Anweisungen, die beim Öffnen einer Verbindung zur Datenbank einmalig ausgeführt werden.

jdbc.test-while-idle

nein

true

Zulässige Werte: true|false. Gibt an, ob ungenutzte Datenbankverbindungen, die sich im Connection-Pool befinden, automatisch geprüft werden sollen.

Für eine automatische Wiederaufnahme der DB-Verbindung ist hier der Wert true zu verwenden.

jdbc.validation-query

nein

Oracle: SELECT 1 FROM DUAL
PostgreSQL/MariaDB: SELECT 1

SQL-Statement, welches zum Testen einer Datenbankverbindung genutzt werden soll (zu verwenden in Kombination mit jdbc.test-while-idle=true).

jdbc.log-validation-errors

nein

true

Zulässige Werte: true|false. Gibt an, ob Fehler bei der Überprüfung einer ungenutzten Datenbankverbindung als ERROR in die CARA-WS-Logdatei geschrieben werden sollen. Ein mögliches Beispiel wäre etwa die Konfiguration einer ungültigen Validation Query.

Zusätzliche Konfigurationsparameter des Tomcat JDBC-Pools können in der application.properties-Datei des CARA-Servers mit dem Präfix jdbc. angegeben werden. Die Parameternamen werden dabei in Kleinbuchstaben mit Bindestrichen geschrieben, beispielsweise maxActive als jdbc.max-active. Die verfügbaren Parameter beschreibt die Dokumentation des Tomcat JDBC-Pools.

CARA überschreibt folgende Einstellungen unabhängig von den Angaben in application.properties:

  • jdbc.default-auto-commit: false

  • jdbc.default-transaction-isolation: READ_COMMITTED (JDBC-Wert 2)

  • jdbc.jdbc-interceptors: ConnectionState;StatementFinalizer

Beim Start protokolliert CARA auf Log-Level INFO Abweichungen von den Tomcat-Pool-Standardwerten. Kennwörter und weitere als sensibel eingestufte Werte werden maskiert.

Datenbankmigrationen mit Flyway

Mit spring.flyway.enabled steuern Sie, ob beim Start des CARA-Servers Datenbankmigrationen mit Flyway ausgeführt werden. Die übrigen Konfigurationsparameter legen die Baseline für ein bestehendes Datenbankschema ohne Flyway-Schema-Historie fest. Für eine Erstinstallation ist die abweichende Baseline-Version zu beachten, die in der Parameterbeschreibung angegeben ist.

Konfigurationsparameter Erforderlich Default Beschreibung

spring.flyway.enabled

nein

false

Dieser Wert legt fest, ob Flyway für Datenbankmigrationen genutzt werden soll oder nicht.

spring.flyway.baselineOnMigrate

nein

true

Legt fest, ob Flyway für ein bestehendes Datenbankschema ohne Flyway-Schema-Historie automatisch eine Baseline anlegt. Die Baseline-Version wird über spring.flyway.baselineVersion festgelegt.

spring.flyway.baselineVersion

nein

2.4.0

Version des Datenbankschemas, ab der Flyway die weiteren Datenbankmigrationen übernimmt. Für eine Erstinstallation mit Flyway muss der Wert auf 1 gesetzt werden. Dieser Wert gilt ausschließlich für eine neue CARA-Datenbank und darf nicht unverändert für eine Update-Installation übernommen werden. Wird Flyway bei einer bestehenden Installation eingeführt, ist die bereits installierte Datenbankschemaversion im Format x.y.z anzugeben; dies ist ab Version 2.4.0 möglich. Alle älteren Datenbankupdates müssen vor dem Start des CARA-Servers durchgeführt sein.

Erstinstallation mit Flyway

Diese Konfigurationsparameter liefern die Startwerte für das Flyway-basierte Datenbank-Setup, etwa für Anwendungszugangsdaten, den Plattformnamen und den E-Mail-Versand. Die Werte werden beim ersten Start einmalig in die CARA-Datenbank übernommen und anschließend in application.properties nicht mehr benötigt. Bei manueller Datenbankinstallation sind stattdessen die jeweils genannten Platzhalter in CaraDb.dat zu ersetzen.

Konfigurationsparameter Erforderlich Default Beschreibung

spring.flyway.placeholders.application.secret.admin

Bei Erstinstallation mit Flyway

–

Hier ist das Kennwort, mit dem sich das Admin-Operator-Frontend gegenüber dem CARA-Server authentisiert, anzugeben. Entspricht dem Platzhalter $APPSEC_ADMIN_OPERATOR$ bei manueller Datenbankinstallation.

spring.flyway.placeholders.application.secret.tcop

Bei Erstinstallation mit Flyway

–

Hier ist das Kennwort, mit dem sich das TC-Operator-Frontend gegenüber dem CARA-Server authentisiert, anzugeben. Entspricht dem Platzhalter $APPSEC_TC_OPERATOR$ bei manueller Datenbankinstallation.

spring.flyway.placeholders.platform.name

Bei Erstinstallation mit Flyway

–

Hier ist der Name der CARA-Plattform anzugeben. Entspricht dem Platzhalter $PLATFORM_NAME$ bei manueller Datenbankinstallation.

Dieser Name wird verwendet, um verschiedene, gleichzeitig installierte CARA-Instanzen unterscheiden zu können. Verwenden Sie einen kurzen, aussagekräftigen Namen.

spring.flyway.placeholders.admin.hosts

Bei Erstinstallation mit Flyway

–

Hier sind die IP-Adressen der Rechner anzugeben, auf denen die Admin-Frontends laufen. Mehrere Angaben werden durch Leerzeichen getrennt. Entspricht dem Platzhalter $ADMIN_HOSTS$ bei manueller Datenbankinstallation.

spring.flyway.placeholders.mail.server

Bei Erstinstallation mit Flyway

–

Hier ist die Mailserver-Adresse anzugeben. Entspricht dem Platzhalter $MAIL_SERVER$ bei manueller Datenbankinstallation.

spring.flyway.placeholders.mail.from

Bei Erstinstallation mit Flyway

–

Hier ist die Absenderadresse für E-Mail-Benachrichtigungen anzugeben. Entspricht dem Platzhalter $MAIL_FROM$ bei manueller Datenbankinstallation.

spring.flyway.placeholders.mail.subject

Bei Erstinstallation mit Flyway

–

Hier ist der Standardwert für den Betreff von E-Mail-Benachrichtigungen anzugeben. Entspricht dem Platzhalter $MAIL_SUBJECT$ bei manueller Datenbankinstallation.

HTTP, HTTPS und AJP

Diese Einstellungen bestimmen, wie der CARA-Server über das Netzwerk erreichbar ist. Unterscheiden Sie dabei zwischen dem direkten Zugriff und der Weiterleitung durch einen vorgeschalteten Webserver sowie zwischen HTTP, HTTPS und AJP.

Eingebetteter Tomcat und Reverse Proxy

Diese Konfigurationsparameter bestimmen, unter welchem Port und Kontextpfad der CARA-Server erreichbar ist. Die HTTP- und TLS-Einstellungen richten sich danach, ob Clients direkt auf den CARA-Server zugreifen oder ein vorgeschalteter Webserver die Anfragen weiterleitet.

Konfigurationsparameter Erforderlich Default Beschreibung

server.port

nein

8080

HTTP- bzw. HTTPS-Port des CARA-Servers. Werden mehrere Anwendungen auf derselben Maschine betrieben, muss für jede Anwendung ein eigener freier Port verwendet werden.

server.servlet.context-path

nein

Leerer String (Root-Kontext)

Kontextpfad, unter dem der CARA-Server erreichbar ist. Die Pfade in der Webserver-Konfiguration müssen mit diesem Wert übereinstimmen.

Beispiel: /cara-ws-server

server.tomcat.basedir

nein

tomcat/cara-ws-server

Basisverzeichnis des eingebetteten Tomcat zur Ablage temporärer Dateien. Relative Pfade beziehen sich auf den Ablageort der ausführbaren JAR-Datei. Als Arbeitsverzeichnis wird das Unterverzeichnis work verwendet.

server.forward-headers-strategy

nein

–

Legt fest, wie die vom vorgeschalteten Webserver weitergereichten Informationen zur ursprünglichen Anfrage ausgewertet werden. Bei der in der Installationsanleitung beschriebenen Weiterleitung über unverschlüsseltes HTTP auf FRAMEWORK setzen.

server.tomcat.redirect-context-root

nein

true

Legt fest, ob Tomcat Anfragen an den Root-Kontext umleitet. Bei der in der Installationsanleitung beschriebenen Weiterleitung über unverschlüsseltes HTTP auf false setzen.

server.*

nein

–

Weitere Konfigurationsparameter für den eingebetteten Tomcat werden von Spring Boot mit dem Präfix server. bereitgestellt. Siehe Spring-Boot-Referenz zu den Server-Konfigurationsparametern.

TLS-Konfiguration

Diese Konfigurationsparameter aktivieren HTTPS und legen den Keystore für das TLS-Server-Zertifikat fest. Bei TLS-Client-Authentifizierung werden zusätzlich der gewünschte Authentifizierungsmodus und der Truststore zur Validierung der Client-Zertifikate konfiguriert.

Konfigurationsparameter Erforderlich Default Beschreibung

server.ssl.enabled

Bei unverschlüsseltem HTTP oder AJP

true (bei SSL-Konfiguration)

Aktiviert HTTPS am eingebetteten Tomcat. Bei unverschlüsselter HTTP- oder AJP-Anbindung auf false setzen. Für HTTPS, beispielsweise ohne vorgeschalteten Webserver oder bei HTTPS-Weiterleitung durch den Webserver, auf true setzen und den Keystore konfigurieren.

server.ssl.key-store

Bei HTTPS

–

Pfad zum Keystore mit dem TLS-Server-Zertifikat und dem zugehörigen privaten Schlüssel. Für HTTPS erforderlich.

Beispiel: /some/example/path/keystore.jks

server.ssl.key-store-type

nein

–

Typ des Keystores mit dem TLS-Server-Zertifikat.

Beispiel: jks

server.ssl.key-store-password

Bei passwortgeschütztem HTTPS-Keystore

–

Passwort des Keystores mit dem TLS-Server-Zertifikat. Bei HTTPS entsprechend dem verwendeten Keystore konfigurieren.

server.ssl.client-auth

nein

–

TLS-Client-Authentifizierung: none fordert kein Client-Zertifikat an, want ermöglicht eine optionale und need verlangt eine verpflichtende Client-Authentifizierung. Für die Validierung der Client-Zertifikate ist der Truststore zu konfigurieren.

server.ssl.trust-store

Bei TLS-Client-Authentifizierung

–

Pfad zum Truststore für die Validierung der TLS-Client-Zertifikate. Wird bei TLS-Client-Authentifizierung benötigt.

Beispiel: /some/example/path/truststore.jks

server.ssl.trust-store-type

nein

–

Typ des Truststores für die Validierung der TLS-Client-Zertifikate.

Beispiel: jks

server.ssl.trust-store-password

Bei passwortgeschütztem Truststore für TLS-Client-Authentifizierung

–

Passwort des Truststores für die Validierung der TLS-Client-Zertifikate. Für die Validierung von TLS-Client-Zertifikaten konfigurieren, wenn Client-Authentifizierung verwendet wird.

AJP-Anbindung

Diese Einstellungen sind relevant, wenn ein vorgeschalteter Webserver die Anfragen über AJP an den eingebetteten Tomcat weiterleitet. Aktivierung, Port, lokale IP-Adresse und die Verwendung eines Secrets werden auf dem CARA-Server konfiguriert und mit der Webserver-Konfiguration abgestimmt.

Konfigurationsparameter Erforderlich Default Beschreibung

tomcat.ajp.enabled

nein

–

Aktiviert den AJP-Connector. Für die AJP-Anbindung auf true und zusätzlich server.ssl.enabled=false setzen.

tomcat.ajp.port

Bei AJP-Anbindung

–

Port des AJP-Connectors. Ein freier Port muss gewählt und in der Webserver-Konfiguration, beispielsweise in workers.properties für mod_jk, ebenfalls eingetragen werden.

tomcat.ajp.address

Bei AJP-Anbindung

–

Lokale IP-Adresse, auf der der AJP-Connector Verbindungen entgegennimmt.

tomcat.ajp.secretRequired

nein

–

Legt fest, ob der AJP-Connector ein Secret verlangt. Wert im Installationsbeispiel: false.

tomcat.ajp.*

nein

–

Mit Konfigurationsparametern mit diesem Präfix kann ein Tomcat-AJP-Connector für die Anbindung an einen vorgeschalteten Apache HTTP Server (HTTPd) aktiviert und konfiguriert werden.

Die unterstützten Konfigurationsparameter nach diesem Präfix sind in der Tomcat-AJP-Connector-Dokumentation beschrieben.

Authentifizierung und Zugriffsschutz

Dieser Bereich enthält die Einstellungen für die Verbindung zu Keycloak und die Synchronisierung mit der CARA-Datenbank. Weitere Konfigurationsparameter betreffen IP-basierte Zugriffsbeschränkungen und das BCrypt-Hashing von Passwörtern.

Keycloak und Synchronisierung

Diese Konfigurationsparameter legen die Verbindung zu Keycloak fest, insbesondere die Realm-URLs, Client-Zugangsdaten und TLS-Einstellungen. Weitere Parameter steuern die Übernahme von Benutzern und Anwendungen aus Keycloak in die CARA-Datenbank.

Konfigurationsparameter Erforderlich Default Beschreibung

openid.client.basic.client-id

ja

mtg-cara-server

Client-ID des CARA-Servers.

Dieser Wert muss in der Regel nie geändert werden. Es sollte immer der Wert mtg-cara-server gesetzt werden.

openid.client.basic.client-secret

ja

–

Client-Secret des CARA-Servers.

openid.client.admin.base-url

ja

–

Basis-URL der Keycloak-Admin-REST-API.

Beispiel: example.com/auth/admin/realms/mtg-ers

openid.client.truststore.path

nein

–

Pfad für den Truststore, der zur Pfadvalidierung des Keycloak-Server-Zertifikats verwendet wird. Wenn der Konfigurationsparameter nicht gesetzt ist, wird der standardmäßige Java-Truststore verwendet.

openid.client.truststore.password

Bei eigenem Keycloak-Truststore

–

Passwort für den Truststore, der zur Pfadvalidierung des Keycloak-Server-Zertifikats verwendet wird.

Muss gesetzt sein, wenn openid.client.truststore.path gesetzt ist.

openid.client.truststore.type

Bei eigenem Keycloak-Truststore

–

Typ des Truststores, der zur Pfadvalidierung des Keycloak-Server-Zertifikats verwendet wird. Gültige Werte sind: JKS, JCEKS, PKCS12.

Muss gesetzt sein, wenn openid.client.truststore.path gesetzt ist.

openid.client.tls-version

nein

TLSv1.2

TLS-Version, die zur Kommunikation mit dem Keycloak-Server verwendet wird. Gültige Werte sind: TLSv1.2, TLSv1.3.

openid.client.admin.timeout-in-seconds

nein

120

Timeout für die Verbindung zur Keycloak-Admin-REST-API in Sekunden.

spring.security.oauth2.resourceserver.jwt.issuer-uri

ja

–

Basis-URL des Keycloak-Realms.

Beispiel: example.com/auth/realms/mtg-ers

spring.security.oauth2.resourceserver.jwt.jwk-set-uri

Wenn keine OpenID-Connect-Discovery genutzt wird

–

URL zum Abruf der öffentlichen Signaturschlüssel des Keycloak-Realms. Die Schlüssel werden als JSON Web Keys (JWKs) zurückgegeben.

Beispiel: example.com/auth/realms/mtg-ers/protocol/openid-connect/certs

Kann entfallen, wenn die öffentlichen Signaturschlüssel über die unter spring.security.oauth2.resourceserver.jwt.issuer-uri konfigurierte OpenID-Connect-Discovery ermittelt werden.

spring.security.oauth2.client.registration.mtgcaraserver.provider

ja

keycloak

OAuth-Provider.

Dieser Wert muss in der Regel nie geändert werden. Es sollte immer der Wert keycloak gesetzt werden.

spring.security.oauth2.client.registration.mtgcaraserver.client-id

ja

${openid.client.basic.client-id}

Client-ID des CARA-Servers.

Der Wert sollte mit dem Wert des Konfigurationsparameters openid.client.basic.client-id übereinstimmen.

spring.security.oauth2.client.registration.mtgcaraserver.client-secret

ja

${openid.client.basic.client-secret}

Client-Secret des CARA-Servers.

Der Wert sollte mit dem Wert des Konfigurationsparameters openid.client.basic.client-secret übereinstimmen.

spring.security.oauth2.client.registration.mtgcaraserver.authorization-grant-type

ja

client_credentials

OAuth-Grant-Typ.

Dieser Wert muss in der Regel nie geändert werden. Es sollte immer der Wert client_credentials gesetzt werden.

spring.security.oauth2.client.provider.keycloak.token-uri

ja

–

URL des Token-Endpunkts des Keycloak-Realms.

Beispiel: example.com/auth/realms/mtg-ers/protocol/openid-connect/token

application.openid.unsync.enabled

nein

false

Zulässige Werte: true|false. Ermöglicht das Löschen von Keycloak-Benutzern sowie deren Rollen aus der CARA-Datenbank. Der Keycloak-Benutzer selbst (einschließlich seiner Admin-Rollen) wird in Keycloak nicht gelöscht und kann später erneut in die CARA-Datenbank synchronisiert werden. Das Löschen von Benutzern über das Admin-Frontend wird momentan nicht unterstützt. Der Konfigurationsparameter beeinflusst zum aktuellen Zeitpunkt lediglich, ob das Löschen von Benutzern über die Admin-API grundsätzlich möglich ist.

application.openid.sync-users-on-first-use.enabled

nein

true

Zulässige Werte: true|false. Legt fest, ob ein Keycloak-Benutzer, der noch nicht in CARA bekannt ist, beim ersten Login automatisch in die CARA-Datenbank synchronisiert wird. Voraussetzung hierfür ist, dass der Keycloak-Benutzer mindestens eine Admin-Rolle besitzt. Dann bekommt er bei der Synchronisation automatisch auch die Rolle "Administrator" zugewiesen und kann sich erfolgreich am Admin-Frontend anmelden.

application.openid.sync-applications-on-first-use.enabled

nein

false

Zulässige Werte: true|false. Legt fest, ob ein Keycloak-Client, der noch nicht als Applikation in CARA bekannt ist, beim ersten Authentifizieren an der CARA-API automatisch in die CARA-Datenbank synchronisiert wird. Voraussetzung hierfür ist, dass der Keycloak-Client die Realm-Rolle CARA_APPLICATION und mindestens eine Admin-Rolle besitzt. Dann bekommt die Applikation bei der Synchronisation automatisch auch die Applikationsrolle "Unrestricted Application" zugewiesen.

knownEmailIdentDataNames

nein

id.email,id.san.email,id.emailAddress0

Dieser Wert wird nur einmalig während der Migration der RA-Zertifikate zu Keycloak verwendet. Er sollte alle bekannten Ident-Daten-Namen enthalten, die eine RA-Zertifikats-E-Mail repräsentieren, und wird verwendet, um RA-Zertifikate als Keycloak-Benutzer automatisch zu migrieren.

Zugriffsbeschränkungen und Passwort-Hashing

Die folgenden Konfigurationsparameter regeln die erlaubten IP-Adressen für den Anwendungszugriff und die IP-Adressprüfung für Admin-API-Clients. Die Stärke des BCrypt-Hashings wird über einen eigenen Konfigurationsparameter festgelegt.

Konfigurationsparameter Erforderlich Default Beschreibung

server.tomcat.allowed-remote-addresses

nein

–

Erlaubte IP-Adressen, die auf die Anwendung zugreifen dürfen.

checkAdminApiClientsIpAddresses

nein

true

Mit diesem Konfigurationsparameter kann eingestellt werden, ob die IP-Adressprüfung für Admin-API-Clients durchgeführt werden soll oder nicht.

bCryptPasswordEncoderStrength

nein

10

Mit diesem Konfigurationsparameter kann die Rundenanzahl für das BCrypt-Hashing konfiguriert werden. Es werden 2 hoch bCryptPasswordEncoderStrength Runden durchgeführt. Gültige Werte für diesen Konfigurationsparameter sind ganzzahlige Werte aus dem Intervall [4,31].

HTTP-Verbindungen zum DMZ-Proxyserver

Der Connection-Pool verwaltet die HTTP-Verbindungen vom CARA-Server zum CARA-DMZ-Proxyserver. Die Konfigurationsparameter begrenzen die Anzahl der Verbindungen und legen deren Lebensdauer, Leerlaufzeiten und Wartezeiten für neue Verbindungsanfragen fest.

Dieser Abschnitt ist bei Verwendung des optionalen CARA-DMZ-Proxy-Moduls relevant.

Konfigurationsparameter Erforderlich Default Beschreibung

dmzProxyConnectionPoolMaxConnections

nein

5

Maximale Anzahl gleichzeitiger HTTP-Verbindungen im Pool

dmzProxyConnectionPoolMaxIdleTime

nein

20

Maximale Zeit in Sekunden, die eine Verbindung im Pool ohne Verwendung verbleiben kann, bevor sie als inaktiv betrachtet und möglicherweise geschlossen wird

dmzProxyConnectionPoolMaxLifeTime

nein

60

Maximale Lebensdauer einer Verbindung im Pool in Sekunden, unabhängig davon, ob sie aktiv genutzt wird oder nicht

dmzProxyConnectionPoolPendingAcquireTimeout

nein

60

Maximale Zeit in Sekunden, die eine Anfrage auf eine Verbindung im Pool warten kann, bevor sie abgebrochen wird

dmzProxyConnectionPoolPendingAcquireMaxCount

nein

5

Maximale Anzahl von ausstehenden Anfragen, die auf eine Verbindung warten dürfen

dmzProxyConnectionPoolEvictInBackground

nein

60

Zeitspanne in Sekunden, in der der Pool ungenutzte Verbindungen im Hintergrund überprüft und gegebenenfalls schließt

Zertifikatsfunktionen

Die folgenden Einstellungen betreffen die Vergabe von Zertifikats-Seriennummern und die Prüfung ausgestellter Zertifikate. Die Beschreibungen weisen darauf hin, wenn ein Konfigurationsparameter ein optionales Modul voraussetzt oder sich auf bestimmte Zertifikatstypen beschränkt.

Fortlaufende Zertifikats-Seriennummern

Bei der Verwendung fortlaufender Zertifikats-Seriennummern wird die nächste freie Seriennummer aus der Datenbank gelesen. Diese Konfigurationsparameter steuern das Zeitlimit für diesen blockierenden Zugriff sowie die Anzahl und die Abstände der Wiederholungsversuche.

Konfigurationsparameter Erforderlich Default Beschreibung

subsequentCertSerialNumberReadTimeoutSeconds

nein

10

Timeout in Sekunden, um die nächste freie Seriennummer blockierend aus der DB zu lesen

subsequentCertSerialNumberMaxRetries

nein

3

Maximale Anzahl von Versuchen, um die nächste freie Seriennummer blockierend aus der DB zu lesen

subsequentCertSerialNumberPauseBeforeRetryMs

nein

100

Wartezeit in Millisekunden zwischen Versuchen, die nächste freie Seriennummer blockierend aus der DB zu lesen

Zertifikatsprüfungen und Lint-Profile

Diese Konfigurationsparameter steuern Lint-Profile, optionale X.509-Zertifikatsprüfungen und die Eindeutigkeit von CHR/Subject bei CV-EE-Zertifikaten. Die Einstellungen sind entsprechend den verwendeten Zertifikatstypen und CARA-Modulen auszuwählen.

Die Einstellungen für Lint-Profile sind bei Verwendung des optionalen CertLint-Moduls relevant; die Einstellungen für Certificate Transparency gelten bei gemeinsamer Verwendung von CertLint und CtLog.

Konfigurationsparameter Erforderlich Default Beschreibung

defaultPublicKeyLintProfiles

nein

lint-server-default

Kommaseparierte Liste der Schlüsselprüfprofile, die standardmäßig für neue CAs aktiviert werden. Diese Einstellung wird nur berücksichtigt, wenn das CARA CertLint-Modul installiert ist.

Wenn kein Standard-Schlüsselprüfprofil verwendet werden soll, muss der Wert leer gelassen werden (vgl. [Modulhandbuch_CertLint]).

skipOptionalX509certificateChecks

nein

false

Zulässige Werte: true|false. Wenn der Konfigurationsparameter auf true gesetzt wird, werden bestimmte Überprüfungen nach dem Ausstellen eines X.509-Public-Key-Zertifikats nicht durchgeführt[1]. In Sonderfällen müssen die Zertifikate von Standards abweichen, z. B. weil eine andere Spezifikation maßgeblich ist. In diesen Fällen kann dieser Wert auf true gesetzt werden.

ctLogLintProfiles

nein

zlint:0,certlint:0,x509lint:0

Diese Einstellung ist nur relevant bei Verwendung der CARA-Module "CertLint" und "CtLog".

Der Konfigurationsparameter definiert die minimalen Lint-Prüfungen für alle X.509-Zertifikate mit Poison- oder CtList-Extension (Certificate Transparency). Diese Minimaleinstellungen können von der CA-Lint-Konfiguration nur erweitert, aber nicht eingeschränkt werden.

Format: kommaseparierte Liste von Einträgen, wobei sich jeder Eintrag aus dem Namen des Lint-Profils, einem Doppelpunkt und 0 oder 1 zusammensetzt. Hierbei gilt:

0 := "ignoreWarnings=false"

1 := "ignoreWarnings=true"

Zum Deaktivieren der Minimaleinstellungen kann dieser Konfigurationsparameter auf den leeren String gesetzt werden. In diesem Fall gelten ausschließlich die CA-Lint-Einstellungen.

allowMultipleCvEeCertificatesWithSameSubject

nein

false

Einstellung zur Eindeutigkeit des CHR/Subject bei CV-EE-Zertifikaten; erlaubte Werte: true|false. Falls es notwendig ist, dass eine CV-CA mehrere CV-EE-Zertifikate mit identischem CHR/Subject ausstellen kann, muss dieser Konfigurationsparameter auf true gestellt werden. Dies betrifft dann sämtliche CV-CAs in der betreffenden CARA-Instanz.

Mail-Templates

Diese Konfigurationsparameter regeln, ob Mail-Templates über die CARA-WS-API und die Admin-API angelegt oder bearbeitet werden können. Die Freigabe wird für beide APIs getrennt festgelegt.

Konfigurationsparameter Erforderlich Default Beschreibung

ws.mailTemplate.editing.enabled

nein

true

Zulässige Werte: true|false. Wenn der Konfigurationsparameter auf false gesetzt wird, ist es nicht möglich, Mail-Vorlagen über die CARA-WS-API anzulegen oder zu bearbeiten.

admin.mailTemplate.editing.enabled

nein

true

Zulässige Werte: true|false. Wenn der Konfigurationsparameter auf false gesetzt wird, ist es nicht möglich, Mail-Vorlagen über die Admin-API anzulegen oder zu bearbeiten.

HSM-Anbindung

GenericHSM-Modul

Diese Konfigurationsparameter gelten nur bei Verwendung des optionalen GenericHSM-Moduls und betreffen die PKCS#11-Bibliotheken, den HTTP-Monitorserver sowie die Zeitlimits für Utimaco-CXI-Verbindungen.

Konfigurationsparameter Erforderlich Default Beschreibung

pkcs11Folder

nein

lib/

Gilt für PKCS#11-Verbindungen im CARA GenericHSM-Modul. Gibt das Dateisystem-Verzeichnis an, in dem die PKCS#11-Bibliotheken der verschiedenen HSM-Hersteller, typischerweise als .so oder .dll Dateien, liegen. Das Verzeichnis wird von der Anwendung eingelesen, um zu erkennen, welche Verbindungen mittels PKCS#11 zu HSMs hergestellt werden können. Details siehe in [Modulhandbuch_GenericHSM].

genericHsmMonitorHost

nein

Leerer String

Adresse des HTTP-Monitor-Servers im GenericHSM-Modul. Ein leerer Wert bindet den Server an alle lokalen Netzwerkschnittstellen.

genericHsmMonitorPort

nein

9502

HTTP-Port des Monitor-Servers im GenericHSM-Modul. Der Port wird gemeinsam für alle GenericHSM-Geräte verwendet.

genericHsmUtimacoCxiConnectTimeoutMs

nein

30000

Maximale Wartezeit in Millisekunden für den Aufbau einer Verbindung zu einem Utimaco HSM. Gilt nur für Verbindungen über die CXI-Schnittstelle im GenericHSM-Modul.

genericHsmUtimacoCxiReadTimeoutMs

nein

120000

Maximale Wartezeit in Millisekunden auf eine Antwort des Utimaco HSMs nach dem Senden einer Anfrage. Gilt nur für Verbindungen über die CXI-Schnittstelle im GenericHSM-Modul. Muss zur Generierung von PQC-Schlüsseln ggf. erhöht werden.

Utimaco HSM-Modul

Diese Konfigurationsparameter gelten nur bei Verwendung des optionalen Utimaco-CXI-Moduls und steuern die Verbindungs- und Lesezeitlimits sowie den Auto-Reconnect-Prozess.

Konfigurationsparameter Erforderlich Default Beschreibung

utimacoCxiConnectTimeoutMs

nein

10000

Betrifft CARA Utimaco CXI-Modul

Verbindungszeitlimit

Einheit: Millisekunden

utimacoCxiReadTimeoutMs

nein

30000

Betrifft CARA Utimaco CXI-Modul

Lesezeitlimit; muss zur Erzeugung von RSA-Schlüsseln mit großer Schlüssellänge ggf. erhöht werden

Einheit: Millisekunden

utimacoCxiKeepAliveDogSleepDefaultSeconds

nein

30

Betrifft CARA Utimaco CXI-Modul

Standardmäßige Pause des Auto-Reconnect-Prozesses bis zur jeweils nächsten Ausführung

Einheit: Sekunden

Monitoring und API-Dokumentation

Hier konfigurieren Sie die Bereitstellung der API-Dokumentation, die Actuator-Endpunkte und den Metrikexport. Die folgenden Unterabschnitte unterscheiden zwischen OpenAPI/Swagger UI, der Betriebsüberwachung mit Actuator und Prometheus sowie der Übertragung von Metriken an OpenSearch.

OpenAPI-Dokumentation

CARA stellt die generierte OpenAPI-Spezifikation und die interaktive Swagger UI über eigene URLs bereit. Die Verfügbarkeit beider Bestandteile wird getrennt gesteuert; die Swagger UI benötigt jedoch Zugriff auf die generierte Spezifikation.

Konfigurationsparameter Erforderlich Default Beschreibung

springdoc.api-docs.enabled

nein

true

Zulässige Werte: true|false. Legt fest, ob die generierte OpenAPI-Spezifikation zur Laufzeit bereitgestellt wird. Bei Aktivierung wird die Spezifikation als JSON unter /v3/api-docs und als YAML unter /v3/api-docs.yaml ausgeliefert. Eine Deaktivierung führt zu HTTP 404 für diese Endpunkte und macht folglich die Swagger UI unbrauchbar, da diese die Spezifikation über diesen Pfad bezieht.

springdoc.swagger-ui.enabled

nein

true

Zulässige Werte: true|false. Legt fest, ob die Swagger UI zur Laufzeit verfügbar ist. Bei Aktivierung wird die interaktive API-Dokumentation unter /swagger-ui/index.html bereitgestellt, wobei /swagger-ui.html dorthin weiterleitet. Eine Deaktivierung führt zu HTTP 404 für diese Endpunkte, ohne die OpenAPI-Spezifikation selbst zu beeinträchtigen, die weiterhin über springdoc.api-docs.enabled gesteuert wird.

Actuator und Prometheus

Die Actuator-Endpunkte stellen Betriebsinformationen wie den Zustand der Anwendung und Metriken bereit. Für die Erreichbarkeit über HTTP müssen sowohl die Bereitstellung des jeweiligen Endpunkts als auch dessen Zugriff freigegeben sein. Für Prometheus muss zusätzlich der Metrikexport aktiviert werden.

Konfigurationsparameter Erforderlich Default Beschreibung

management.endpoints.web.exposure.include

nein

health,info

Kommagetrennte Liste der über HTTP bereitzustellenden Actuator-Endpunkte. Auch prometheus kann in die Liste aufgenommen werden. Zusätzlich muss der Zugriff auf den jeweiligen Endpunkt freigegeben sein.

management.endpoints.access.default

nein

none

Zulässige Werte: none|read-only|unrestricted. Legt die Standard-Zugriffsstufe für alle Actuator-Endpunkte fest, sofern für einen einzelnen Endpunkt nicht individuell etwas anderes konfiguriert ist. none deaktiviert alle Endpunkte, read-only erlaubt ausschließlich lesende Zugriffe, unrestricted gewährt vollen Zugriff. Auf none setzen, um standardmäßig alles zu sperren und anschließend einzelne Endpunkte gezielt freizugeben.

management.endpoint.health.access

nein

unrestricted

Zulässige Werte: none|read-only|unrestricted. Legt die Zugriffsstufe für den Health-Endpunkt fest und überschreibt damit management.endpoints.access.default.

management.endpoint.info.access

nein

read-only

Zulässige Werte: none|read-only|unrestricted. Legt die Zugriffsstufe für den Info-Endpunkt fest und überschreibt damit management.endpoints.access.default.

management.endpoint.prometheus.access

nein

none

Zulässige Werte: none|read-only|unrestricted. Legt die Zugriffsstufe für den Prometheus-Endpunkt fest und überschreibt damit management.endpoints.access.default.

management.prometheus.metrics.export.enabled

nein

false

Der Wert true aktiviert den Export von Prometheus-Metriken. Diese sind unter /actuator/prometheus abrufbar, wenn prometheus in management.endpoints.web.exposure.include enthalten ist und management.endpoint.prometheus.access auf read-only oder unrestricted gesetzt ist.

Metrikexport nach OpenSearch

Diese Konfigurationsparameter steuern die Übertragung von Metriken an einen OpenSearch-Server. Neben der Aktivierung des Exports werden die Server-URL, Zugangsdaten und bei Bedarf ein gesonderter Truststore für die TLS-Verbindung angegeben.

Konfigurationsparameter Erforderlich Default Beschreibung

management.elastic.metrics.export.enabled

nein

false

Zulässige Werte: true|false. Wenn auf true gesetzt, werden die Metriken an den konfigurierten OpenSearch-Server gesendet.

management.elastic.metrics.export.host

Bei aktiviertem OpenSearch-Metrikexport

localhost:9200

Gibt die URL des OpenSearch-Servers an. Bei aktiviertem Metrikexport die URL des vorgesehenen OpenSearch-Servers konfigurieren.

management.elastic.metrics.export.user-name

nein

–

Gibt den Benutzer an, der Zugriff auf den OpenSearch-Server hat.

management.elastic.metrics.export.password

nein

–

Gibt das Passwort des Benutzers des OpenSearch-Servers an.

mtg.cara.opensearch.truststore.path

nein

–

Pfad eines gesonderten Truststores für die TLS-Verbindung zum OpenSearch-Server.

mtg.cara.opensearch.truststore.password

Bei eigenem OpenSearch-Truststore

–

Passwort für den Truststore für die TLS-Verbindung zum OpenSearch-Server.

Erforderlich, wenn mtg.cara.opensearch.truststore.path gesetzt ist.

mtg.cara.opensearch.truststore.type

Bei eigenem OpenSearch-Truststore

–

Typ des Truststores für die TLS-Verbindung zum OpenSearch-Server. Gültige Werte sind: JKS, JCEKS, PKCS12

Erforderlich, wenn mtg.cara.opensearch.truststore.path gesetzt ist.

JVM-Systemparameter des CARA-Servers

JVM-Systemparameter beeinflussen den Start des CARA-Servers. Mit den hier beschriebenen Parametern legen Sie die zu ladenden Konfigurationsdateien, zusätzliche Verzeichnisse für Module und Bibliotheken sowie die Algorithmuskombination für PKCS#12-Keystores fest.

Die JVM-Systemparameter werden mit -D<Parameter>=<Wert> im Startbefehl des CARA-Servers vor -jar angegeben. Eine Angabe in application.properties hat für diese JVM-Systemparameter keine Wirkung. Das Beispiel unterhalb der Tabelle zeigt einen Startbefehl mit gesonderten Konfigurationsdateien.

Die folgende Tabelle beschreibt die JVM-Systemparameter für den Start des CARA-Servers. Die Spalte „Erforderlich“ zeigt, ob ein JVM-Systemparameter angegeben werden muss. „Default“ nennt die Standardwerte für das jeweils beschriebene Startverfahren. „–“ in der Spalte „Default“ bedeutet, dass hier kein allgemeiner Standardwert angegeben ist.

JVM-Systemparameter Erforderlich Default Beschreibung

spring.config.location

nein

–

Pfad zur Konfigurationsdatei oder zum Verzeichnis mit application.properties. Beim Start angeben, wenn die Konfigurationsdatei an einem anderen Ort bereitgestellt wird. Verzeichnispfade müssen mit / enden.

Beispiel: -Dspring.config.location=/path/to/config/

loader.path

nein

–

Kommaseparierte Liste zusätzlicher Verzeichnisse für optionale CARA-Module und HSM-Bibliotheken beim Start über den mitgelieferten CARA-Bootstrap. Für HSM-Bibliotheken und optionale Module werden separate Unterverzeichnisse empfohlen, beispielsweise lib und modules. Die Versionsnummern der CARA-Anwendung und der optionalen CARA-Module müssen übereinstimmen.

Beispiel: -Dloader.path=file:lib,file:modules

log4j2.configurationFile

nein

–

Alternativer JVM-Systemparameter zur Angabe der Log4j-2-Konfigurationsdatei. Für die Konfiguration über application.properties ist logging.config zu verwenden.

Beispiel: -Dlog4j2.configurationFile=/some/path/log4j2.xml

log4j.configurationFile

nein

–

Weiterer von Log4j2 unterstützter Name für den JVM-Systemparameter zur Angabe der Log4j-2-Konfigurationsdatei. Für die Konfiguration über application.properties ist logging.config zu verwenden.

Beispiel: -Dlog4j.configurationFile=/some/path/log4j2.xml

org.bouncycastle.pkcs12.default

nein

PKCS12-AES256-AES128 (beim Start über den CARA-Bootstrap)

Legt die Algorithmuskombination fest, die der Bouncy-Castle-Provider beim Erzeugen von PKCS#12-Keystores verwendet.

Der Wert LEGACY stellt das frühere Verhalten (BCPKCS12) wieder her. Andere vom Bouncy-Castle-Provider unterstützte PKCS#12-Algorithmen können ebenfalls angegeben werden.

Beispiel: -Dorg.bouncycastle.pkcs12.default=LEGACY

Beispiel zum Starten des CARA-Servers mit gesonderten Konfigurationsdateien:

java -Dspring.config.location=/path/to/config/ -Dlogging.config=/some/path/log4j2.xml -jar /path/to/cara-ws-server-<version>.jar

Umgebungsvariablen des Admin-Frontends

Das Admin-Frontend wird unabhängig vom CARA-Server über Umgebungsvariablen konfiguriert. Diese Variablen werden dem Prozess des Admin-Frontends übergeben und bestimmen unter anderem den HTTP-Port, die lokale IP-Adresse und den Kontextpfad.

Für die Kommunikation mit dem CARA-Server und die Anmeldung über Keycloak werden außerdem die zugehörigen URLs und die Client-ID festgelegt. Stimmen Sie diese Angaben mit der Serverkonfiguration und dem verwendeten Keycloak-Realm ab. Optionale URLs für die Links zu CLM und KMS in der Anwendungsauswahl werden ebenfalls hier angegeben.

Die folgende Tabelle beschreibt die Umgebungsvariablen des Admin-Frontends. Die Spalte „Erforderlich“ zeigt, ob eine Umgebungsvariable gesetzt werden muss. „Default“ nennt den ohne eigene Angabe verwendeten Wert. „–“ in der Spalte „Default“ bedeutet, dass hier kein allgemeiner Standardwert angegeben ist; ein leerer String ist davon zu unterscheiden.

Umgebungsvariable Erforderlich Default Beschreibung

NITRO_PORT / PORT

nein

3000

HTTP-Port des Admin-Frontends.

Beispiel: 3007

Sind beide Variablen gesetzt, hat NITRO_PORT Vorrang vor PORT.

NITRO_HOST / HOST

nein

Alle lokalen Netzwerkschnittstellen

IP-Adresse, an die der HTTP-Server des Admin-Frontends gebunden wird.

Beispiel: 127.0.0.1

Sind beide Variablen gesetzt, hat NITRO_HOST Vorrang vor HOST.

NUXT_APP_BASE_URL

nein

/cara-admin-ui/

Kontextpfad, unter dem das Admin-Frontend erreichbar sein soll.

NUXT_PUBLIC_CARA_WS_SERVER_BASE_PATH

ja

–

CARA-Server-URL.

Beispiel: example.com/cara-ws-server

NUXT_PUBLIC_ISSUER_URI

ja

–

Basis-URL des Keycloak-Realms.

Beispiel: example.com/auth/realms/mtg-ers

NUXT_PUBLIC_KEYCLOAK_CLIENT_CLIENT_ID

nein

mtg-cara-admin-ui

Client-ID des Keycloak-Clients.

NUXT_PUBLIC_CLM_UI_BASE_PATH

nein

Leerer String

URL des CLM-Frontends für den Link in der Anwendungsauswahl. Bei einem leeren Wert wird CLM als nicht installiert angezeigt.

NUXT_PUBLIC_KMS_UI_BASE_PATH

nein

Leerer String

URL des KMS-Frontends für den Link in der Anwendungsauswahl. Bei einem leeren Wert wird KMS als nicht installiert angezeigt.
1. Gegenstand dieser Prüfung ist, dass gemäß RFC 8813 bei Zertifikaten mit ECC-Schlüssel die KeyUsage-Bits keyEncipherment und dataEncipherment nicht verwendet werden.