Funktionalität
Die FSS-UI stellt die Zertifikatsverwaltung und das Regelwerk des FSS zur Verfügung. Der FSS wird genutzt, um B2B-Nachrichten zu signieren & verschlüsseln.
Architektur
Das Feature wurde entkoppelt und benötigt nun keinen Tomcat mehr. Stattdessen gliedert es sich in eine FSS-UI & ein FSS-Backend. Die UI greift auf das Backend zu. Das Backend entspricht dem bekannten FSS und greift auf seine Datenbank zu.
Beide Applikationen sind über Keycloak abgesichert.
Ähnlich wie bei den Tomcats ist ein Parallelbetrieb neue & alte Authentifizierung möglich: mindestens ein FSS-Backend wird über Keycloak abgesichert (ein neues FSS-Backend im Docker, folgend dieser Doku). Bestehende FSS-Backends können parallel zunächst weiterhin ohne Keycloak betrieben werden. Diese werden von bestehenden Tomcats angesprochen, nicht jedoch von der neuen UI. Bitte beachten Sie bei einem Parallelbetrieb auf die ClusterCommunication
Voraussetzungen
Installation
Das Setup der hier beschriebenen Umgebung basiert auf einem docker-compose file. Diese Konfiguration definiert einen Container.
Die docker-compose Umgebung besteht letztlich aus einer Verzeichnisstruktur, die die einzelnen im Folgenden beschriebenen Dateien enthält. Die Verzeichnisstruktur stellt sich wie folgt dar:
| base/
|- fss/
| | - conf/
| | - application.yml
| | - application-secure.yml
|- fss-ui/
| |- keycloak.json
|- docker-compose.yml
|- .env
|- system.json
Diese Dokumentation basiert auf der folgenden docker-compose.yml
:
version: '3.7'
services:
fss:
image: ${NEXUS_ERP}/fss:2021-03-18
hostname: fss
restart: always
environment:
TZ: ${TIME_ZONE}
volumes:
- ./fss/conf:/opt/securityserver/conf
- ./fss/logs:/opt/securityserver/logs
fssui:
image: ${NEXUS_ERP}/fss-ui:2021-02-22
restart: always
ports:
- 1186:8080
environment:
TZ: ${TIME_ZONE}
volumes:
- ./fss-ui/keycloak.json:/usr/share/nginx/html/FSS-UI/assets/config/keycloak.json
- ./fss-ui/system.json:/usr/share/nginx/html/FSS-UI/assets/config/system.json
- ./fss-ui/logs/host.access.log:/var/log/nginx/host.access.log
- ./fss-ui/logs/host.error.log:/var/log/nginx/host.error.log
depends_on:
- fss
Bitte folgen Sie unseren Konventionen für Servicenamen (aus denen sich dann die Hostnamen ergeben).
Achten Sie beim image
darauf, eine aktuelle Version gemäß
unserer Kompatibilitätsübersicht anzugeben.
Die oben aufgeführte docker-compose.yml
beinhaltet verschiedene Variablen “${Variable}”. Diese Variablen sind in der Datei .env
enthalten.
NEXUS_ERP=docker-nob-erp.next-level-apps.com
TIME_ZONE=Europe/Berlin
FSS Backend
./fss/conf/
In diesem Verzeichnis sollten die gleichen Dateien vorhanden sein wie auf der bereits verwendeten FSS-Instanz. Lediglich die beiden Folgenden werden wie angegeben angepasst.
./fss/conf/application.yml
Diese Datei entspricht der der bestehenden FSS-Instanz. Lediglich das Attribut “active” sollte auf “secure” angepasst werden:
# Spring properties
spring:
application:
name: certificate-service
profiles:
active: secure
# HTTP Server
server:
port: 2222
logging:
level:
org.springframework.web: INFO
org.springframework.security: INFO
./fss/conf/application-secure.yml
Diese Datei enthält die Eigenschaften, die für den Zugriff auf den Keycloak relevant sind:
keycloak:
enabled: true
auth-server-url: http://[dockerhost]:8080/auth
realm: [ realm ]
resource: fss
credentials:
secret: your-secret-provided-by-keycloak
cors: true
Es ist auch möglich, die Keycloak-Einstellungen auch in einer keycloak.json zu hinterlegen. WICHTIG: Die Keycloak-Einstellungen sollten entweder in der application-secure.yml Datei oder in der keycloak.json Datei gemacht werden. Nicht in beiden!
Verwendung von Umgebungsvariablen
Die Konfiguration der Datenbankist ebenfalls über Umgebungsvariablen möglich. Ein Mounten der hibernate.cfg.xml ist in diesem Fall nicht notwendig.
Variablenname | Beschreibung | Beispiel |
---|---|---|
DB_DRIVER | Datenbank-Treiber | org.postgresql.Driver |
DB_URL | Datenbank-URL im jdbc-Format | jdbc:postgresql://fss-database:5432/fss?currentSchema=fss |
DB_USERNAME | Datenbank-Benutzername | |
DB_PASSWORD | Datenbank-Passwort | |
DB_DIALECT | Datenbank-Dialect | org.hibernate.dialect.PostgreSQLDialect |
RevisionInfo Backend
Standardmäßig versucht der FSS den RevisionInfoServer über die URL http://revision:8080 zu erreichen. Diese URL kann in
der docker-compose.yml
überschrieben werden:
environment:
- JAVA_OPTS: -Drevision.info.server.url={revision_url}
Alternativ kann die application.yml
Datei angepasst und in den FSS Container gemountet werden:
revision:
info:
server:
url: {revision_url}
Wenn Sie den RevisionService nicht nutzen, muss dieser auch nicht angegeben werden.
optionale Docker-Compose Konfiguration
Wenn Sie einen vom Standard abweichenden Service in Ihrer Reverse-Proxy-Konfiguration konfigurieren möchten, folgen Sie bitten den Hinweisen in der Docker-Compose-Dokumentation
FSS-UI
./fss-ui/keycloak.json
Verwendung von Umgebungsvariablen (ab August 2023)
Wir empfehlen die Verwendung von Umgebungsvariablen in der keycloak.json, sofern keine zusätzlichen Eigenschaften konfiguriert werden sollen.
Die Standard keycloak.json für die FSS-UI sieht aktuell wie folgt aus:
{
"realm": "${KC_REALM}",
"auth-server-url": "${KC_URL}",
"ssl-required": "${KC_SSL_REQUIRED}",
"resource": "${KC_CLIENT}",
"public-client": true,
"confidential-port": 0
}
Die definierten Umgebungsvariablen werden beim Erzeugen des Docker-Containers gesetzt und verwendet, sofern keine keycloak.json-Datei in den Container gemountet wurde.
Bei allen Keycloak-Parametern müssen json-Sonderzeichen escaped werden, da sonst keine valide keycloak.json erzeugt wird.
Variablenname | Beschreibung | Default |
---|---|---|
KC_REALM | Keycloak Realm | |
KC_URL | Keycloak Auth-Server-Url | |
KC_SSL_REQUIRED | Keycloak SSL required | none |
KC_CLIENT | Keycloak Resource | fss-ui |
Als gesamte Datei
Diese Datei konfiguriert die Anbindung der FSS-UI-Instanz an den keycloak. Folgende Konfiguration wurde für diese Dokumentation verwendet:
{
"realm": "B2B",
"auth-server-url": "http://keycloak:8080/auth/",
"ssl-required": "none",
"resource": "fss-ui",
"public-client": true,
"confidential-port": 0
}
Die Datei wird am besten direkt aus der Keycloak Admin-UI exportiert. In Keycloak muss dafür ein passender Client angelegt werden. Dies wird im Keycloak Abschnitt später genauer beschrieben.
./fss-ui/nginx.conf
Das Image bringt bereits eine Default nginx.conf mit. Es ist nicht nötig, diese zu überschreiben.
Sie kann aber über die folgenden Umgebungsvariablen individuell angepasst werden:
ENV PORTAL_UI_URL="http://portal-ui:8080" # URL mit der die FSS-UI auf die B2B-Portal-UI zugreifen kann.
ENV B2B_URL="http://b2b:8080" # URL mit der die FSS-UI auf das B2B Backend zugreifen kann.
ENV NOTIFICATION_URL="http://notification:8080" # URL mit der die FSS-UI auf das Notification Backend zugreifen kann.
ENV REVISION_URL="http://revision:8080" # URL mit der die FSS-UI auf das Revision Backend zugreifen kann.
ENV FSS_URL="http://fss:2222" # URL mit der die FSS-UI auf das FSS Backend zugreifen kann.
ENV SERVICE_PATH=/FSS-UI # URL-Pfad zur FSS-UI. Achtung: Eine Änderung des Defaults muss in allen Konfigurationen der UI berücksichtigt werden (z.B. Keycloak Client und portal-config.json).
./system.json
Verwendung von Umgebungsvariablen
Wir empfehlen die Verwendung von Umgebungsvariablen in der system.json, sofern keine zusätzlichen Eigenschaften konfiguriert werden sollen.
Die Standard system.json für die FSS-UI sieht aktuell wir folgt aus:
{
"systemName": "${SYSTEM_NAME}", # Angezeigter Name in der UI. Default: FSS
"backgroundColor": "${BACKGROUND_COLOR}", # Farbe der UI in hex color code. Default: #008ECC (blau)
"activateUserMessages": ${ACTIVATE_USER_MESSAGES}, # Wird das Feature für Benutzerbenachrichtigungen verwendent. Default: true
"backendUrl": "${SERVICE_PATH}" # URL-Pfad der UI. Default: /FSS-UI.
"noDefaultCertPurpose": true
}
Die definierten Umgebungsvariablen werden beim Start des Containers gesetzt und verwendet, sofern eine eigene system.json nicht bereits keine Datei in den Container gemountet wurde.
Als gesamte Datei
Die Datei system.json
kann als globale Konfiguration genutzt werden. Nach Möglichkeit sollte die gleiche Datei für alle Frontends
verwendet werden.
In ihr können der angezeigte Systemname sowie die angezeigte Hintergrundfarbe festgelegt werden.
Ferner kann durch sie das Feature UserMessages aktiviert werden.
{
"systemName": "FSS Dokusystem",
"backgroundColor": "#008ECC",
"activateUserMessages": true
}
noDefaultCertPurpose
Der Verwendungszweck (Purpose) eines Zertifikats definiert die Anwendungsgebiete des Zertifikats. Diese variieren je nachdem ob das Zertifikat für Mail/AS2-Mako oder für AS4-Mako eingesetzt wird.
AS4-Mako oder Mischbetrieb: Bitte konfigurieren Sie noDefaultCertPurpose=true
. Dies ermöglicht Ihnen, beim Upload eines Zertifikats den Purpose wie gewünscht auszuwählen.
Mail/AS2-Mako: hier ist keine weitere Konfiguration der system.json
nötig. Beim Upload eines Zertifikats werden automatisch die Verwendungszwecke Sign/Encrypt vorbelegt. Diese werden für Mail/AS2 benötigt.
Logging
Das access_log
und das error_log
werden in der nginx.conf
definiert.
Damit das Log nicht mit einem weggeworfenen Container verloren geht, kann man das Log auch von außen in den Container mounten. Hierfür sind die Log-Files in den docker-compose/volumes mit anzugeben. Für diese Lösung müssen die Dateien vorher bereits auf dem Docker-Host angelegt und mit geeigneten Berechtigungen versehen sein.
Aktivieren der SSL-Kommunikation zum FSS
Standard http für FSS-Backend-Dienst
Derzeit ist nutzt der FSS standardmäßig den Port 2222 über HTTP.
Falls Sie den Port ändern möchten, müssen Sie ihn in der Datei application.yml ändern und außerdem eine angepasste nginx.conf Datei in ihren FSS-UI Container hineinmounten
So aktivieren Sie den Dienst SSL (HTTPs) für FSS-Backend
In der Datei application.yml, kann HTTPS wie folgt konfiguriert werden.
server:
port: 8443 # HTTP (Tomcat) port
ssl:
key-store-type: PKCS12
key-store: /opt/securityserver/conf/keystore.p12
key-store-password: foo123
key-alias: localhost
enabled: true
enabled-protocols: TLSv1.2
ciphers: TLS_RSA_WITH_AES_128_CBC_SHA256
Bitte beachten Sie, dass dies nur eine Beispiel-Konfiguration ist. Sie müssen die Keystore-Datei keystore.p12 durch eine eigene (z.B. hineingemountete) Datei ersetzen. Ändern Sie zudem den Typ des Keystores, das Passwort und den Alias, um die Konfiguration Ihrer Umgebung anzupassen.
Aktivieren Sie https für die Kommunikation zwischen Frontend und Backend, indem Sie eine angepasste nginx.conf in den FSS-UI Container hineinmounten.
Aktivieren Sie https die Kommunikation zwischen der B2B und dem FSS, indem Sie die Global Property SECURITY_SERVER_BASE_URL anpassen.
Hinzufügen eines selbstsignierten Zertifikats
Falls Sie ein selbstsigniertes Zertifikat nutzen möchten, müssen Sie dieses oder Ihr CA-Zertifikat einem Truststore hinzufügen. Bitte folgen Sie dafür den Schritten in dieser Beschreibung. Falls Sie keinen eigenen Truststore hinzufügen, wird auf den Standard Java Truststore zurückgegriffen.
Start docker container (UI & Backend)
Mit dem folgenden Kommando können die Container im Docker gestartet werden:
:opt/docker/fss/> docker-compose up -d
Mit folgendem Kommando können die Container im Docker gestoppt werden:
:opt/docker/fss/> docker-compose stop
Keycloak Konfiguration
Keycloak Client Konfiguration
FSS Service
Für den FSS-Service muss ein Keycloak Client angelegt werden.
Die ClientId kann von Ihnen selbst gewählt werden, z.B. fss
.
Das Client Protocol bleibt auf openid-connect gestellt.
Beispiel für eine Redirect-URI: https://my-fss-server
.
Es ist der Standardflow zu nutzen (standardmäßig aktiv). Außerdem müssen Service Accounts Enabled
aktiviert werden und über den
Tab Service Account Roles
die Rolle RevisionManager-Write
zugewiesen werden, damit der FSS den Revision-Service nutzen kann. Service
Accounts können in älteren Keycloak-Versionen nur genutzt werden, wenn der Access Type
nicht auf public
steht.
Der Access Type ist auf confidential
zu stellen.
Als Login-Theme kann das nli Thema gewählt werden.
FSS-UI
Für die FSS-UI muss ein Keycloak Client angelegt werden.
Die ClientId kann von Ihnen selbst gewählt werden, z.B. fss-ui
.
Die RootURL entspricht der externen Adresse des Frontends, z.B. https://my-fss-ui-server/FSS-UI
.
Das Client Protocol bleibt auf openid-connect gestellt.
Es ist der Standardflow zu nutzen (standardmäßig aktiv).
Der Access Type ist public.
Als Login-Theme kann das nli Thema gewählt werden.
Keycloak Rollen & Attribute
Die Konfiguration der benötigten Rollen und Attribute wird hier beschrieben.
UI Komponenten werden nur angezeigt, wenn die entsprechenden Rollen den Usern zugewiesen worden sind.
Mandantenfilterung
Die FSS-UI unterstützt eine Mandantenfilterung. Die Konfiguration wird hier beschrieben. Falls diese konfiguriert ist, werden nur die Zertifikate angezeigt, die zum Mandanten des Users passen.
View Me Edit Me