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

• Docker einsatzbereit
• Keycloak installiert
• Remote FSS-Datenbank installiert

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.

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.

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

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.