FSS-UI

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

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

Diese Datei konfiguriert die Anbindung der FSS-UI-Instanz an den keycloak. Folgende Konfiguration wurde für diese Dokumentation verwendet:

{
  "realm": "[realm]",
  "auth-server-url": "http://[dockerhost]:8080/auth",
  "ssl-required": "none",
  "resource": "fss-ui",
  "public-client": true,
  "confidential-port": 0
}

Die Datei sollte direkt aus der Keycloak Admin-UI exportiert werden.

./fss-ui/nginx.conf

Das Image bringt bereits eine Default nginx.conf mit. Es ist nicht nötig, diese zu überschreiben.

./system.json

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
}

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 die Umgebungsvariable FSS_SERVICE=fss:newPort in der Datei docker-compose.yml/.env definieren

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 die Umgebungsvariablen FSS_SERVICE und FSS_PROTOCOL aktualisieren.

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/b2b/> docker-compose up -d

Mit folgendem Kommando können die Container im Docker gestoppt werden:

:opt/docker/b2b/> docker-compose stop

Keycloak Konfiguration

Keycloak Client Konfiguration

FSS Service

Für den FSS-Service muss ein Keycloak Client angelegt werden.

Öffnen des Formulars zum Erstellen eines neuen Clients

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 werden, damit der FSS den Revision-Service nutzen kann.

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.

Öffnen des Formulars zum Erstellen eines neuen Clients

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