AS4 Frontend Customizing

Das AS4 System verfügt über kein eigenes Frontend, sondern nutzt das Frontend der B2B. Sie können das AS4 System an eine bestehende B2B anschließen. Falls Sie die B2B nicht für die Marktkommunikation einsetzen, empfehlen wir die Einrichtung der B2B Frontends sowie Backends, um die B2B allein als AS4 Frontend einzusetzen. Die B2B ist dann zwischen das AS4 System und Ihre Marktkommunikationsanwendung zu schalten.

Die folgende Dokumentation beschreibt die Anbindung des AS4-Systems an das B2B-Frontend.

Portal UI

Um die RabbitMQ Kachel in der Portal UI sichtbar zu machen, müssen die folgenden Konfigurationen in der portal-config.json ergänzt werden.

image

Die “uiUrl”und die “uiRequiredRole” müssen entsprechend angepasst werden.

Admin UI

Die Konfigurationseinstellungen sind nur setzbar, sobald der as4Style in der system.json der B2B-Admin-UI auf “true” gesetzt wurde, idealerweise konfiguriert über die Umgebungsvariable AS4_STYLE=true. Der Default für diese Einstellung ist “false”. Ohne diese Einstellung ist es zwar möglich den AS4 Konfigurationstab in den Kommunikationsbeziehungen zu sehen, die Einstellungen sind aber nicht nutzbar. Im Konfigurationstab haben die Anwender die Möglichkeit eine AS4 Adresse zu speichern und diese auch wieder zu deaktivieren (https://b2bbp.next-level-help.org/as4_hu_frontend.html#admin-ui).

Die Admin-UI kann auch standalone für AS4 ohne die B2B verwendet werden. Hierfür muss die Eigenschaft isB2bConfigured in der system.json der B2B-Admin-UI auf “false” gesetzt werden. Der Default für diese Einstellung ist true. Wird die UI standalone verwendet, so ist es nicht möglich die AS2 Konfiguration zu sehen.

Wird eine über Umgebungsvariablen konfigurierte system.json der Admin-UI verwendet so ist nichts weiter zu tun.

Wird die system.json von Hand angelegt und als Config-File in den Container gemountet, so muss diese um die Eigenschaften

  • as4AddressServiceUrl für den AS4 Address Service mit dem Wert ““/B2B-Admin-UI/api/as4-address/””
  • as4Style mit dem Wert “true” erweitert werden.

Beispiel der system.json der B2B-Admin-UI

{
  "systemName": "B2B Local",
  "backgroundColor": "#008ECC",
  "as4Style": true,
  "as4AddressServiceUrl": "/B2B-Admin-UI/api/as4-address/",
  "isB2bConfigured": true
}

Das Image bringt bereits eine Default nginx.conf mit. Es ist nicht nötig, diese zu überschreiben. Sie kann aber über die Umgebungsvariablen individuell angepasst werden.

Über das Frontend kann der Pathswitch verschickt werden. Nach Ende des Übergangszeitraums ist der Pathswitch nicht mehr vorgesehen. Um zu verhindern, dass weiterhin Pathswitches verschickt werden, kann folgende Umgebungsvariable konfiguriert werden: NO_PATHSWITCH=true.

B2B UI

Marktpartnerverwaltung

Eine neue Ansicht wurde in der Marktpartnerverwaltung ergänzt. Um diese Ansicht freizuschalten muss das Attribut as4Style in der system.json der B2B-UI auf “true” gesetzt werden, idealerweise konfiguriert über die Umgebungsvariable AS4_STYLE=true. Der Default für diese Einstellung ist “false”. Durch diese Property werden die AS4-Daten aus dem AS4-Address-Service geladen. Falls Sie stattdessen wünschen, die AS4-Daten aus der B2B zu laden, ist stattdessen der Modus As4B2bStyle zu nutzen. Dieser wird im nächsten Abschnitt beschrieben. Im Default ist diese Einstellung auf “false” gesetzt, sodass es nicht möglich ist AS4 Informationen hinzuzufügen, zu löschen oder sichtbar zu machen (https://b2bbp.next-level-help.org/as4_hu_frontend.html#marktpartnerverwaltung)

Die Marktpartnerverwaltung kann auch ohne B2B verwendet werden. Hierfür muss die Eigenschaft isB2bConfigured in der system.json der B2B-UI auf “false” gesetzt werden. Der Default ist true. Wird die Marktpartnerverwaltung standalone verwendet, so ist es nicht möglich Mailadressen zu konfigurieren.

Wird eine über Umgebungsvariablen konfigurierte system.json der B2B-UI verwendet so ist nichts weiter zu tun.

Wird die system.json von Hand angelegt und als Config-File in den Container gemountet, so muss die system.json um die Eigenschaften

  • as4AddressServiceUrl für den AS4 Address Service mit dem Wert ““/B2B-UI/api/as4-address/””
  • b2bMessageServiceUrl für den AS4 Message Service der B2B-UI auf ““/B2B-UI/api/as4-message/””
  • as4Style mit dem Wert “true” erweitert werden.

Beispiel der system.json der B2B-UI

{
  "systemName": "B2B Local",
  "backgroundColor": "#008ECC",
  "as4Style": true,
  "b2bMessageServiceUrl": "/B2B-UI/api/as4-message/",
  "as4AddressServiceUrl": "/B2B-UI/api/as4-address/",
  "isB2bConfigured": true,
  "as4AddressWriteHidden": true
}

Falls Sie den Certificate-Manager einsetzen, wird die AS4-Adresse auf Basis der Partnerzertifikate automatisch gepflegt. Eine manuelle Eingabe der Partneradressen über das Frontend ist dann nicht nötig. Entsprechend wird ein Schreibzugriff auf das Address-Feld nicht benötigt. In diesem Szenario empfehlen wir deshalb das Address-Editierfeld komplett zu entfernen. Dies können Sie tun, indem Sie folgende Property in der system.json konfigurieren: "as4AddressWriteHidden": true (default false), bzw. über folgende Umgebungsvariable: AS4_ADDRESS_WRITE_HIDDEN.

Das Image bringt bereits eine Default nginx.conf mit. Es ist nicht nötig, diese zu überschreiben. Sie kann aber über die Umgebungsvariablen individuell angepasst werden.

Marktpartnerverwaltung ohne Anbindung an den AS4-Address-Service

Der AS4 User kann AS4-Beziehungen in der Marktpartnerverwaltung anlegen, auch ohne den AS4-Adress-Service an die B2B anzubinden.

Um dieses Feature zu nutzen, werden mindestens der B2B-Message-Service und der AS4-Adress-Service ab KW 46 2024 benötigt.

Konfiguration:

  • Für lesenden Zugriff muss die Keycloak-Rolle AS4-PARTNER-READ für den Benutzer gesetzt werden und für den schreibenden Zugriff die Rolle AS4-PARTNER-WRITE
  • Das Attribut as4Style muss auf “true” gesetzt werden. Dies kann entwedet über dei Umgebungsvariable AS4_STYLE=true konfiguriert oder in der system.json der B2B-UI auf “true” gesetzt werden.
  • Die AS4-Address API muss zudem auf den b2b-message-service konfiguriert werden. Hierzu können folgende Umgebungsvariablen konfiguriert werden:
# AS4_ADDRESS_URL=http://as4-address-service:8080
AS4_ADDRESS_URL=http://b2b-message-service:8080
# AS4_ADDRESS_CONTEXT_PATH=aep-as4-address-service
AS4_ADDRESS_CONTEXT_PATH=aep-b2b-message-service

Eine Löschung ist erst mit den nächsten Releases der folgenden Services möglich: B2B-Message-Service, AS4-Adress-Service und B2B-U (Stand: 05.02.2025). Wichtig: Alle drei Services müssen aktualisiert werden.

Mandantentrennung

Um die Mandantentrennung zu aktivieren, muss zum einen der B2B-Message-Service per Keycloak abgesichert werden. Dazu muss das Springprofil “keycloak-enriched” verwendet werden. Zum anderen müssen die entsprechenden Mandanten in Keycloak unter dem tenant-Attribut des jeweiligen Users hinzugefügt werden. Hier ist zu beachten, dass nicht die B2B-Lösung, die auf der Extension TENANTS basiert, verwendet werden kann.

As4B2bStyle

Alternativ kann auch der As4B2bStyle verwendet werden, um AS4-Marktpartner-Relation in der Marktpartnerverwaltung ohne den AS4 Address Service anzeigen zu lassen. Allerdings ist es hiermit nicht möglich, neue Relationen hinzuzufügen oder bestehende zu löschen. Um diese Ansicht zu aktivieren, setzen Sie das Attribut AS4_B2B_STYLE in der Datei docker-compose.yml unter der Umgebung auf “true”. Diese Einstellung ist standardmäßig auf “false” gesetzt. Sobald dieses Feature aktiviert ist, können Benutzer nun die neuen Spalten in der Tabelle (Gültigkeit, Protokoll) sehen, die AS4-Erweiterungsbeziehungsdaten anzeigen und vieles mehr. Benutzer können entweder AS4_STYLE auf true ODER AS4_B2B_STYLE auf true gleichzeitig setzen. Das Setzen beider Attribute auf true führt zu einer falschen Konfiguration und einer fehlerhaften Ansicht im UI.

docker-compose.yml-Datei

 b2b-ui:
    image: devnortheuropemgmtacr.azurecr.io/b2b/b2b-ui:${VERSION_B2B_UI}
    restart: always
    environment:
      TZ: ${TIME_ZONE}
      BACKGROUND_COLOR: "#008000"
      SYSTEM_NAME: "Green Energy"
      AS4_STYLE: false
      AS4_B2B_STYLE: true

Relation Confirmation

Beziehungen können über das Frontend manuell bestätigt werden. Die hierfür vorgesehene Checkbox beim Anlegen einer Beziehung ist per Default nicht angehakt, da statt der manuellen Bestätigung der Pathswitch genutzt werden sollte.

Nach Ende des Übergangszeitraums wird der Pathswitch nicht mehr gefordert. Bei Bedarf kann somit der Default der Checkbox angepasst werden, sodass die Checkbox für die manuelle Bestätigung standardmäßig aktiviert ist. Hierfür ist folgende Umgebungsvariable zu konfigurieren: AS4_RELATION_DEFAULT_CONFIRMED= true.

Tenant Separation

Sobald diese Ansicht aktiviert ist, können Benutzer die AS4-Erweiterungsbeziehungsdaten abrufen. Diese AS4-Erweiterungsbeziehungs-API ist durch die Rolle B2B-AS4-PARTNER-READ geschützt. Stellen Sie sicher, dass diese Rolle dem Benutzer hinzugefügt wird, um diesen API-Aufruf zu unterstützen.

Die AS4-Erweiterungsbeziehungsdaten werden basierend auf Konfigurationen an drei Stellen angezeigt:

  1. AS4_RELATIONS-Erweiterung in der Administrationsoberfläche: Legen Sie die Liste der Mandanten, Partner, Protokolle und Werte fest.
  2. TENANTS-Erweiterung in der Administrationsoberfläche: Legen Sie die erlaubten Mandanten fest, die angezeigt werden sollen.
  3. Konfiguration der Benutzerattribute in Keycloak: Legen Sie die Attributbeziehung zwischen den TENANTS- und AS4_RELATION-Erweiterungen fest.

1. AS4_RELATIONS extension

Um die AS4-Erweiterungsbeziehungen festzulegen, gehen Sie zur Administrations-Benutzeroberfläche, klicken Sie auf Erweiterungen und bearbeiten Sie die Einstellungen für AS4_RELATION. Beispiel: {tenant}.{partner}.{type}={value}

9903111000003.9903111000004.AS4=true
9903111000003.9903111000004.delivered=2023-04-26T05:58:30.996Z[UTC]
9903111000005.9903111000006.AS4=true
9903111000006.9903111000006.delivered=2023-04-27T05:58:30.996Z[UTC]

Diese Extension wird im Standard automatisch vom AS4-System befüllt und sollte nicht manuell bearbeitet werden.

2. TENANTS extension

Um die TENANTS-Erweiterung einzurichten, navigieren Sie zur Administrations-Oberfläche, klicken Sie auf Erweiterungen und bearbeiten Sie die TENANTS-Erweiterung. (Erstellen Sie eine neue Erweiterung, wenn TENANTS nicht existiert).
Beispiel: {Attribute}={value}
Das Attribut ist die Variable, die in Keycloak > Benutzer > Attribute > Wert eingestellt ist. Der Wert kann entweder ‘all’, ‘tenantID’ oder leer sein. Unterstützt mehrere Mandanten, zum Beispiel SUPPLIER=9903111000003,9903111000004,9903111000005.

3. User attributes in Keycloak

Um sicherzustellen, dass sowohl die AS4_RELATIONS- als auch die TENANTS-Erweiterungen funktionieren, müssen Sie eine Beziehung zwischen diesen beiden Erweiterungen herstellen. Navigieren Sie in Keycloak zu Benutzern, wählen Sie den Benutzer aus, den Sie ändern möchten, und klicken Sie auf Attribute. Fügen Sie den Schlüssel ‘tenants’ mit dem Wert ‘SUPPLIER’ hinzu (der den Attributen entsprechen sollte, die in der TENANTS-Erweiterung festgelegt sind).
Jetzt werden die AS4-Erweiterungsbeziehungsdaten nur für den im TENANTS-Erweiterung erlaubten Mandanten angezeigt.

Keycloak

Über Keycloak können verschiedene AS4-Rollen gesetzt werden, um in der Marktpartnerverwaltung und in den Kommunikationsbeziehungen entsprechende Rechte vergeben zu können. Alles weiter dazu in der Rollendokumentation.

Ohne Docker

Wird kein Docker verwendet, so muss sowohl die nginx.conf der B2B-Admin-UI als auch der B2B-UI ergänzt werden, damit sie auf den AS4 Adress Service und AS4 Message Service zugreifen können. Dabei muss der Host und Port entsprechend an das System angepasst werden.

B2B Admin UI

...
        location ~ /B2B-Admin-UI/api/as4-address/(.*) {
                resolver 127.0.0.11 valid=30s;
                set $as4_address_host as4-address-service:8080;
                proxy_pass   http://$as4_address_host/aep-as4-address-service/as4-address/$1$is_args$args;
                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;
        }

B2B UI

Die AS4-Address API wird zwingend benötigt. Die Nutzung der AS4-Message API ist veraltet und wird in der aktuellen Version nicht benötigt. Konfiguration zur Anbindung beider APIs findet sich in folgendem nginx.conf Auszug.

...
        location ~ /B2B-UI/api/as4-address/(.*) {
                 resolver 127.0.0.11 valid=30s;
                 set $as4_address_host as4-address-service:8080;
                 proxy_pass   http://$as4_address_host/aep-as4-address-service/as4-address/$1$is_args$args;
                 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;
         }

         location ~ /B2B-UI/api/as4-message/(.*) {
                 resolver 127.0.0.11 valid=30s;
                 set $as4_message_host as4-message-service:8080;
                 proxy_pass   http://$as4_message_host/aep-as4-message-service/as4-message/$1$is_args$args;
                 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;
         }

B2B UI ohne AS4-Address-Service-Anbindung

location ~ /B2B-UI/api/as4-address/(.*) {
                 resolver 127.0.0.11 valid=30s;
                 #set $as4_address_host as4-address-service:8080;
                 #proxy_pass   http://$as4_address_host/aep-as4-address-service/as4-address/$1$is_args$args;
                 proxy_pass   http://b2b-message-service:8080/aep-b2b-message-service/as4-address/$1$is_args$args;
                 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;
         }
View Me   Edit Me