Funktionalität
Die Portal-UI bietet eine grafische Oberfläche, aus der heraus ein einfacher Absprung in alle anderen UI’s möglich ist.
Das Ergebnis nach der Anmeldung:
Architektur
Die Portal-UI greift auf alle UIs zu und alle UIs greifen auf die Portal-UI zu.
Die Portal-UI benötigt keinen Zugriff zum Tomcat, zu Backends oder zur Datenbank.
Die Portal-UI wird über Keycloak abgesichert.
Voraussetzungen
- Docker einsatzbereit
- Keycloak installiert
- es macht Sinn, vorher alle anderen UIs installiert zu haben
Installation
Docker-Compose
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/
|- b2b-portal-ui/
| |- keycloak.json
| |- portal-config.json
|- docker-compose.yml
|- .env
|- system.json
Diese Dokumentation basiert auf der folgenden docker-compose.yml
:
version: '3.7'
services:
portal-ui:
image: ${NEXUS}/portal-ui:2020-11-12
restart: always
ports:
- 1192:8080
environment:
- TZ: ${TIME_ZONE}
volumes:
- ./b2b-portal-ui/keycloak.json:/usr/share/nginx/html/B2B-Portal-UI/assets/config/keycloak.json
- ./b2b-portal-ui/system.json:/usr/share/nginx/html/B2B-Portal-UI/assets/config/system.json
- ./b2b-portal-ui/portal-config.json:/usr/share/nginx/html/B2B-Portal-UI/assets/config/portal-config.json
- ./b2b-portal-ui/logs/host.access.log:/var/log/nginx/host.access.log
- ./b2b-portal-ui/logs/host.error.log:/var/log/nginx/host.error.log
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=docker-nob-erf.next-level-apps.com
TIME_ZONE=Europe/Berlin
./b2b-portal-ui/portal-config.json
Damit es möglich wird aus der Portal-UI heraus in alle anderen verfügbaren UI’s abzuspringen, müssen die Zugänge in der portal-config.json konfiguriert werden. Ein vollständige portal-config.json-Konfiguration kann wie folgt aussehen:
{
"portalConfig": [
{
"uiUrl": "http://[dockerhost]:8082/B2B-UI",
"uiRequiredRole": "B2B-Dashboard",
"uiName": "portalConfig.uiName.b2b",
"picturePath": "/B2B-Portal-UI/assets/config/images/p-b2b.jpg",
"iconName": "/B2B-Portal-UI/assets/config/icons/B2b.svg",
"description": "portalConfig.description.b2b"
},
{
"uiUrl": "http://[dockerhost]:1186/FSS-UI/",
"uiRequiredRole": "FSS-CertificateManager-Read",
"uiName": "portalConfig.uiName.fss",
"picturePath": "/B2B-Portal-UI/assets/config/images/p-security.jpg",
"iconName": "/B2B-Portal-UI/assets/config/icons/SecurityServer.svg",
"description": "portalConfig.description.fss"
},
{
"uiUrl": "http://[dockerhost]:1190/User-Messages-UI/",
"uiRequiredRole": "B2B-UserMessages-Write",
"uiName": "portalConfig.uiName.userMessages",
"picturePath": "/B2B-Portal-UI/assets/config/images/p-systemmessage.jpg",
"iconName": "/B2B-Portal-UI/assets/config/icons/systemmessage.svg",
"description": "portalConfig.description.userMessages"
},
{
"uiUrl": "http://[dockerhost]:1188/B2B-RevisionInfo-UI/",
"uiRequiredRole": "RevisionManager-Read",
"uiName": "portalConfig.uiName.revisionManager",
"picturePath": "/B2B-Portal-UI/assets/config/images/p-reversion-manager.jpg",
"iconName": "/B2B-Portal-UI/assets/config/icons/reversionmanager.svg",
"description": "portalConfig.description.revisionManager"
},
{
"uiUrl": "http://[dockerhost]:1184/B2B-Admin-UI/",
"uiRequiredRole": "B2BAdmin-Dashboard",
"uiName": "portalConfig.uiName.admin",
"picturePath": "/B2B-Portal-UI/assets/config/images/p-admin.jpg",
"iconName": "/B2B-Portal-UI/assets/config/icons/administration.svg",
"description": "portalConfig.description.admin"
},
{
"uiUrl": "http://[dockerhost]:8094/B2B-Index-Management-UI/",
"uiRequiredRole": "B2B-IndexManagement",
"uiName": "portalConfig.uiName.indexManagement",
"picturePath": "/B2B-Portal-UI/assets/config/images/p-indexmanagement.jpg",
"iconName": "/B2B-Portal-UI/assets/config/icons/index-management.svg",
"description": "portalConfig.description.indexManagement"
},
{
"uiUrl": "http://[dockerhost]:1192/B2B-Portal-UI/",
"uiRequiredRole": "B2BPortal-UI",
"uiName": "portalConfig.uiName.portal",
"picturePath": "/B2B-Portal-UI/assets/config/b2b-ui.jpg",
"iconName": "dashboard",
"description": "portalConfig.description.portal"
}
]
}
- Unter “uiUrl” werden die jeweiligen URL’s hinterlegt, unter denen die neuen Oberflächen erreichbar sind. Beispiel für B2B-UI: http://[dockerhost]:8082/B2B-UI.
- Unter “uiRequiredRole” ist die jeweilige Rolle einzutragen, die benötigt wird, um auf die jeweilige UI-Anwendung zugreifen zu können. Diese Rolle muss in Keycloack vorhanden sowie dem jeweiligen Benutzer zugeordnet sein.
- Unter “uiName” wird ein vordefinierter Wert angegeben, der nicht geändert werden sollte. Wenn Sie diesen Wert ändern möchten, müssen Sie den UI-Quellcode für (EN.json und DE.json) aktualisieren.
- Unter “picturePath” und “iconName” werden die Pfade für die Bilder der Portal-UI Kacheln definiert. Auch diese Werte sollten aus dem Beispiel übernommen und nicht geändert werden. In unserem Beispiel wurde der Portal-Ui Microservice im Ordner /B2B-Portal-UI installiert.
- Unter “description” werden die jeweiligen tooltips geladen. Auch diese Konfiguration sollte aus dem Beispiel übernommen werden.
Technisch ist es auch möglich, fremde Seiten in der Portal-UI über die portal-config.json
zu ergänzen. Für die Icons können dann Base-64-URIs genutzt werden.
Zugriff zur portal-config.json
Nicht nur die Portal-UI, sondern auch alle anderen UIs benötigen Zugriff zur portal-config.json
. Während die Portal-UI direkt auf die Datei zugreift, fragen die anderen UIs zur Laufzeit den Inhalt bei der Portal-UI an. Dies erfolgt über ihre nginx Konfiguration (welche per Docker-Image automatisch mitgeliefert wird).
Falls es nicht gewünscht ist, dass eine andere UI direkt auf die Portal-UI zugreift, kann alternativ die portal-config.json
auch direkt in das Verzeichnis der jeweiligen UI kopiert / gemountet und von dort ausgelesen werden. Hierzu muss die nginx.conf
angepasst werden. Am Beispiel der B2B-UI suchen Sie die folgende Zeile:
location /B2B-UI/portalConfig/ {
proxy_pass http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
}
Und ersetzen Sie sie entsprechend wie folgt:
location /B2B-UI/portalConfig {
alias /usr/share/nginx/html/B2B-UI/assets/config/portal-config.json;
}
./b2b-portal-ui/keycloak.json
Diese Datei konfiguriert die Verbindung der Portal-UI-Instanz mit dem Keycloak. Die folgende Konfiguration wurde für diese Dokumentation verwendet:
{
"realm": "[realm]",
"auth-server-url": "http://[dockerhost]:8080/auth",
"ssl-required": "none",
"resource": "portal-ui",
"public-client": true,
"confidential-port": 0
}
Die Datei sollte direkt aus der Keycloak Admin-UI exportiert werden. In Keycloak muss dafür ein passender Client angelegt werden. Dies wird später genauer beschrieben.
./b2b-portal-ui/nginx.conf
Das Image bringt bereits eine Default nginx.conf mit. Es ist nicht nötig, diese zu überschreiben. Die folgende Anleitung ist somit optional.
Um die Portal-UI nutzten zu können, muss zudem die nginx.conf angepasst werden. Fügen Sie dazu die folgende Konfiguration zur nginx.conf hinzu:
worker_processes 1;
pid /tmp/nginx.pid;
events {
worker_connections 1024;
}
http {
include mime.types;
default_type application/octet-stream;
#access_log logs/access.log timing;
sendfile on;
#tcp_nopush on;
keepalive_timeout 65;
#gzip on;
server {
listen 8080;
server_name localhost;
absolute_redirect off;
location /B2B-Portal-UI {
alias html/B2B-Portal-UI/;
try_files $uri$args $uri$args/ /B2B-Portal-UI/index.html;
}
location /B2B-Portal-UI/api/b2b-user-messages/system-messages {
proxy_pass http://notification:8080/system-messages;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_cache_bypass $http_upgrade;
}
}
}
In diesem Beispiel wurde auch der Zugang zum optionalen Features SystemMessages konfiguriert.
./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": "B2B 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.
Start des Docker-Containers
Mit dem folgenden Kommando kann der benötigte Container im Docker gestartet werden:
:opt/docker/b2b/> docker-compose up -d
Mit folgendem Kommando kann der benötigte Container im Docker gestoppt werden:
:opt/docker/b2b/> docker-compose stop
Keycloak Konfiguration
Keycloak Client Konfiguration
Für die Portal-UI muss ein Keycloak Client angelegt werden.
Die ClientId kann von Ihnen selbst gewählt werden, z.B. portal-ui
.
Die RootURL entspricht der externen Adresse des Frontends.
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.
Keycloak Mapper
Die Konfiguration des Keycloak-Mappers für den Client portal-ui
ähnelt dem Client b2b-function-ui
und fss-ui
hier.
Konfiguration der Umsysteme
Die folgende Konfiguration ist bereits in den Images enthalten. Nutzen Sie unsere Images und folgen Sie unseren Servicenamenkonventionen, ist nichts weiter zu tun.
Bei jeder UI, die mit der Portal-UI zusammenarbeiten soll, muss die jeweilige nginx.conf
angepasst werden: es muss jeweils ein Eintrag für die Portal-UI ergänzt werden. Nachfolgend werden die sechs Anpassungen für die B2B-UI, B2B-Admin-UI, B2B-RevisionInfo-UI, B2B-Index-Management-UI, User-Messages-UI & FSS-UI aufgezeigt.
location /B2B-UI/portalConfig/ {
proxy_pass http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
}
location /B2B-Admin-UI/portalConfig/ {
proxy_pass http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
}
location /B2B-RevisionInfo-UI/portalConfig/ {
proxy_pass http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
}
location /B2B-Index-Management-UI/portalConfig/ {
proxy_pass http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
}
location /User-Messages-UI/portalConfig/ {
proxy_pass http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
}
location /FSS-UI/portalConfig/ {
proxy_pass http://portal-ui:8080/B2B-Portal-UI/assets/config/portal-config.json;
}