AS4 Inbound Endpoint

Der AS4 Inbound Endpoint empfängt AS4-Nachrichten der Marktpartner per HTTP(S). Nach dem Eingang wird die Nachricht über den Message-Broker an den Crypto Operations Service zur Entschlüsselung und Signaturprüfung weitergeleitet. Der Crypto Operations Service antwortet mit der Empfangsbestätigung (Receipt) für den Sender. Das Receipt wird anschließend zur Speicherung an den AS4 Message Service versandt.

Die API des AS4-Inbound-Endpoint muss durch die Marktpartner erreichbar sein.

Features

Hardware Anforderungen

Eine Service-Instanz erfordert mindestens 512 MB RAM.

Wir empfehlen 0,1 CPU-Kerne je Instanz.

Logs werden auf die Festplatte geschrieben, entsprechend muss genügend Speicherplatz vorhanden sein.

Abhängigkeiten

Der Service greift auf einen Message-Broker zu, um Nachrichten zu empfangen und zu versenden.

Der Service nutzt die REST API des Security Server FSS. Der FSS muss im Hintergrund auf ein HSM zugreifen können.

Einfache Konfiguration der as4-inbound-endpoint.properties

Die Kommunikation zwischen den verschiedenen AS4 Services erfolgt über einen Message-Broker.

rabbitmq.host=localhost
rabbitmq.port=5672
rabbitmq.username=guest
rabbitmq.password=guest

AMQP Routing Konfiguration

Im Standard-Routing ist keine weitere Konfiguration nötig. Die folgende Tabelle gibt eine Übersicht über alle vom Service genutzten Exchanges und ihre Gegenstellen. Die Default-Queue ergibt sich aus <exchange>.default.

Verbindungs-Timeout zum Crypto Operations (in Sekunden):

connectionTimeout=300

Consumer-Gruppen anpassen

Für den Receipt-Consumer kann die Gruppe und der Binding-Routing-Key geändert werden. Bei deaktiviertem Routing muss bindingRoutingKey zwingend auf default gesetzt werden. Über max-concurrency lässt sich die maximale Anzahl gleichzeitiger Verarbeitungsthreads einstellen (Default: 50).

receiptConsumerGroup=default
receiptConsumerMaxConcurrency=50
spring.cloud.stream.rabbit.bindings.consumeReceipt-in-0.consumer.bindingRoutingKey=default

Producer-Routing nach Header

Für Producer-Exchanges lässt sich das Routing über <exchangeProperty>HeaderName und <exchangeProperty>HeaderValues aktivieren. Nachrichten mit Werten, die nicht in HeaderValues aufgelistet sind, laufen weiterhin über die Default-Route. Die Gegenstelle muss entsprechend eingerichtet werden.

Mögliche HeaderName-Werte:

• tenant: ILN Nummer des Senders
• partner: ILN Nummer des Empfängers
• sector: GAS, ELECTRICITY

Beispiel für inboundCryptoMessageExchangeName:

inboundCryptoMessageExchangeName=as4.decrypt.verify
inboundCryptoMessageHeaderName=partner
inboundCryptoMessageHeaderValues=9907647000008,9903111000003

Automatischer Zertifikats-Download

Wenn ein unbekannter Partner eine Nachricht sendet und dessen Zertifikat nicht im FSS vorhanden ist, kann automatisch ein Download-Befehl an den Certificate-Manager gesendet werden (siehe AMQP Routing Konfiguration).

Keycloak REST-Client

Wenn der FSS oder andere Services per Keycloak abgesichert sind, kann der AS4 Inbound Endpoint OAuth2-Tokens für ausgehende REST-Aufrufe anfordern. Default: false.

keycloak.rest-client=false
keycloak.auth-server-url=http://keycloak:9000/auth
keycloak.realm=as4
keycloak.resource=as4-backend
keycloak.credentials.secret=
keycloak.scope=
# Nur bei Mandantentrennung im FSS notwendig:
keycloak.username=
keycloak.password=

API

Die API bietet den AS4 Endpunkt an.

Darüber hinaus bietet die API Server-Health Informationen an.

Ein KontextPath Präfix kann über folgende Property konfiguriert werden: server.servlet.contextPath.

Für produktive Systeme wird ein Loadbalancer benötigt, um die Anfragen auf mehrere Instanzen zu verteilen.

AS4-Adresse

Der AS4-Inbound-Endpoint empfängt die AS4-Nachricht auf der AS4-Adresse. Aus dem Service ergibt sich folgende Anforderung an die Adresse:

Die AS4-Adresse muss auf /as4 enden.

Multi-Mandantenfähigkeit

Falls das AS4-System für mehrere Mandanten betrieben wird, kann der AS4 Inbound Endpoint für jeden Mandanten mindestens eine eigene Instanz haben. So kann für jeden Mandanten eine eigene AS4-Adresse konfiguriert werden.

Bei einer solchen Konfiguration muss für jeden Mandanten eine eigene Queue eingerichtet werden. Über die Exchange as4.send.receipt muss entsprechend dem Mandanten in die jeweilige Queue geroutet werden. Die jeweilige Instanz des AS4-Inbound-Endpoint muss die Queue passend zum Mandanten konsumieren.

Der AS4-Inbound-Endpoint arbeitet außerdem als AMQP Producer. Hier müssen keine weiteren Anpassungen vorgenommen werden.

Ausfallsicherheit & Lastverteilung

Wie üblich für Microservices können mehrere Instanzen des AS4 Inbound Endpoint parallel betrieben werden, um die Last zu verteilen und Ausfallsicherheit zu gewährleisten.

In einem solchen Szenario muss ein Loadbalancer vorgeschaltet werden, um die Last zu verteilen.

Damit die Quittung an die richtige Service-Instanz übergeben wird, muss das Spring Profil scaling aktiviert werden. Dies hat zur Folge, dass für jede Instanz eine eigene Queue as4.send.receipt.<UUID> erstellt und an den Exchange as4.send.receipt mit dem Routingkey <UUID> gebunden wird. Dieser UUID wird beim Start der Instanz des Inbound Endpoints erzeugt und über die Services AS4 Crypto Operations und AS4 Receipt Service weitergereicht, damit der AS4 Crypto Operations anhand dieser <UUID> die Nachricht an die richtige Instanz des AS4 Inbound Endpoints routen kann. Hierbei ist es zwingend erforderlich, auch im AS4 Crypto Operations das Spring Profile auf scaling zu setzen, wie der Dokumentation der AS4 Crypto Operations zu entnehmen.

Dazu muss die folgende Konfiguration im AS4 Inbound Endpoint gesetzt werden:

spring.profiles.active=scaling

Wird eine Instanz gestoppt, so wird auch die dazugehörige Queue gelöscht.

mTLS

Der AS4-Inbound-Endpoint stellt AS4-Endpunkte bereit. Diese können per mTLS abgesichert werden.

Um mTLS zu aktivieren, konfigurieren Sie die folgenden Eigenschaften:

#=== SSL Properties ===#
sslEnabled=true
sslPort=8443

addressServiceUrl=http://localhost:8089/aep-as4-address-service
#ssl.tenant.id=9907647000008,9903111000003

fss.server.api.url=http://localhost:2222/fss/api/v1
ssl.partner.client=shared-client

Die TLS-Funktionalität kann über die Eigenschaft sslEnabled ein-/ausgeschaltet werden (entweder durch Setzen auf true oder false). Der Standardwert für sslEnabled ist false. Die Property server.ssl.enabled wird nicht unterstützt und darf nicht gesetzt werden.

Falls ssl aktiviert wird, läuft AS4 SSL über den Port 8443. Dieser Port kann mit folgender Property umkonfiguriert werden: sslPort.

Falls ssl deaktiviert ist, läuft AS4 über den Port 8080.

Der Service unterstützt parallel mehrere Mandanten. Wenn wir die Liste der Mandanten aus dem AS4-Address-Service automatisch abrufen möchten, müssen die Mandanten im AS4-Address-Service konfiguriert werden. Für diese Verbindung müssen wir die Eigenschaft addressServiceUrl in der Konfigurationsdatei definieren. (Alternativ kann die Liste der Mandanten, für die wir TLS konfigurieren möchten, wie gezeigt explizit in der Eigenschaft ssl.tenant.id mithilfe durch Kommas getrennter Werte angegeben werden.)

Hinweis: Konfigurieren Sie entweder die Eigenschaft addressServiceUrl oder ssl.tenant.id – konfigurieren Sie nicht beide Eigenschaften gleichzeitig.

Hinweis: Falls die addressServiceUrl genutzt wird, gilt: Der AS4-Address-Service muss ausgeführt und vom AS4-Inbound-Endpoint aus aufrufbar sein. Alle benötigten Mandanten müssen zur Bootzeit des AS4-Inbound-Endpoints verfügbar sein. Falls sich Mandanten zur Laufzeit ändern, müssen Sie den AS4-Inbound-Endpoint neu starten.

Für jeden Mandanten muss ein Marktpartner-TLS-Zertifikat/-Schlüssel im FSS/HSM vorhanden sein. Für jeden Marktpartner müssen alle Zertifikate der Aussteller-Zertifikatskette im FSS shared-client verfügbar sein. Die FSS-URL wird über die Property fss.server.api.url konfiguriert. Der shared-client wird über die Property ssl.partner.client angegeben. Wenn die Eigenschaft von ssl.partner.client nicht festgelegt ist, lautet der Standardwert shared-client.

Hinweis: Der FSS muss ausgeführt und vom AS4-Inbound-Endpoint aus aufrufbar sein. Alle benötigten Zertifikate müssen zur Bootzeit des AS4-Inbound-Endpoints verfügbar sein. Falls sich Zertifikate zur Laufzeit ändern, müssen Sie den AS4-Inbound-Endpoint neu starten.

Der Health-Check des Service ist erst nach Abschluss des Zertifikatsladeprozesses erfolgreich. Ist die Property startupSslCheck=true gesetzt, schlägt der Health-Check fehl, wenn Zertifikate aus technischen Gründen nicht geladen werden konnten. Revoked Zertifikate beeinflussen den Health-Check hingegen nicht.

Validierung der Partner und System Adressen-Relation

Der Inbound-Endpoint bietet die Möglichkeit zur Überprüfung der Adress-Relation zwischen Partner und System. Dafür wird die aktuell konfigurierte Partnerbeziehung aus dem Address-Service über REST geladen. Dieses Feature muss explizit per Konfiguration aktiviert werden. Falls das Feature aktiviert ist, gilt:

• Die Beziehung muss für eingehende AS4-Marktübertragungsnachrichten confirmed sein, sonst wird keine Quittung zurückgeliefert.
• Für andere AS4-Nachrichten (z.B. BDEW-Test- und Pathswitch-Nachrichten) reicht es, wenn die Beziehung existiert. Sie muss noch nicht confirmed sein. Falls keine Beziehung existiert, wird keine Quittung zurück geliefert.

Folgende Konfiguration ist hierbei möglich:

# Address Service Config
partnerTenantRelationValidation=true
addressServiceUrl=http://as4-address-service:8080/aep-as4-address-service

Das Feature kann mit der Eigenschaft partnerTenantRelationValidation ein- oder ausgeschaltet werden. Um den Address-Service per REST ansprechen zu können, muss die Eigenschaft addressServiceUrl konfiguriert sein.

Logging der AS4 Anfragen

Durch die Konfiguration des Loggings des Spring CommonsRequestLoggingFilters auf DEBUG Level in der application.properties, können die AS4 Anfragen geloggt werden.

logging.level.org.springframework.web.filter.CommonsRequestLoggingFilter=DEBUG
logging.level.org.bouncycastle=DEBUG

Der Standard ist derzeit wie folgt konfiguriert:

logging.level.org.bouncycastle=WARN

Achtung: Diese Einstellung sollte auf Produktivsystemen nur temporär zu Analysezwecken eingestellt werden. Hinweis: Das Framework loggt die Request-Body der Anfragen leider nicht.

Actuator

Der Actuator wird verwendet, um den Servicestatus über die Rest-API zu überprüfen. Unten finden Sie den Haupt-API-Link

http://localhost:8080/actuator

Der management port ist 8080, unterstützt wird http.

Die Properties management.server.ssl.enabled & management.server.port werden nicht unterstützt und dürfen nicht gesetzt werden.

Widerrufstatus von Zertifikaten cachen

Um den Widerrufstatus von Zertifikaten zu cachen und nicht für jede Nachricht erneut abzurufen, muss folgender Wert in der application.properties gesetzt werden:

revocation.status.cache.enabled=true

Dann wird der Widerrufstatus der Marktpartnerzertifikate maximal einmal pro Stunde geprüft. Falls Probleme beim Abrufen des Widerrufstatus auftreten, wird der gecachte Status für maximal 6 Stunden verwendet. Diese Zeiträume können mit folgenden Konfigurationseinstellungen angepasst werden:

revocation.status.cache.max.usage=T6H
revocation.status.cache.refresh.after=T1H

Syntax: 1H für eine Stunde, 30M für 30 Minuten, 1D für einen Tag, oder Kombinationen wie 1d4H or 1H30M

Zwischenspeicherung des Ergebnisses der Partnerzertifikatsvertrauensprüfung

Folgende Eigenschaften können eingestellt werden. Nachfolgend sind die Standardwerte aufgeführt.

ssl.trust-info.cache.enabled=true
ssl.trust-info.cache.refresh.after=T1H

Prüfung von nicht gespeicherten Partnerzertifikaten während des TLS-Handshakes

Während des TLS-Handshakes kann die Vertrauensprüfung des Partnerzertifikats nun auch durchgeführt werden, wenn das Zertifikat nicht im FSS gespeichert ist. Diese Prüfung findet im FSS statt. Wenn das Zertifikat im FSS gespeichert ist, werden diese Informationen für die Prüfung herangezogen. Wenn das Zertifikat nicht gespeichert ist, werden die Informationen aus dem Zertifikat verwendet und die Sperrliste von der Sub-CA heruntergeladen. Folgenden Prüfungen werden durchgeführt, um zu prüfen, ob das Zertifikat vertrauenswürdig ist:

• Zertifikatskette ist im FSS vorhanden und vertrauenswürdig
• Wenn das Zertifikat vorhanden ist: Aktiv oder inaktiv
• Validity/time slice
• Sperrlistenstatus
• Purpose ist TLS

Um diese Funktion zu aktivieren (FSS-URL ist ebenfalls konfiguriert):

ssl.trust-info=true

Wichtig ist zu beachten, dass für dieses Feature mindestens die FSS Version 2025-02-27-01 verwendet werden muss.

Anhang: Gesamtkonfiguration

Folgende Konfiguration reicht in einem Standard-System aus: application.properties:

#=== RabbitMQ Configuration ===#
rabbitmq.host=rabbitmq3
rabbitmq.port=5672
rabbitmq.username=guest
rabbitmq.password=${RABBITMQ_PASSWORD}

## Configured Timeout for response in sec
connectionTimeout=300

#=== FSS ===#
fss.server.api.url=http://fss:2222/fss/api/v1
## Page size for fss requests
fss.page.size.value=100

#=== SSL Properties ===#
sslEnabled=false
sslPort=8443
#ssl.tenant.id=9907647000008, 9903111000003
ssl.partner.client=shared-client

#Address Service Config
partnerTenantRelationValidation=false
addressServiceUrl=http://as4-address-service:8080/aep-as4-address-service

#=== Certificate Download Command ===#
certificateDownloadCommandExchange=certificate.download.command

#=== Certificate download Properties ===#

Sie können optional die Anzahl paralleler Threads zum Herunterladen von Zertifikaten über die folgende Eigenschaft konfigurieren:

executor.parallel-threads=20

Sie können optional die Anzahl der Wiederholungsversuche und das Intervall zwischen den Wiederholungsversuchen zum Herunterladen von Zertifikaten mithilfe der folgenden Eigenschaft konfigurieren:

retry.max-attempts=3
retry.pause.milliseconds=500

Um die Anzahl der Mandanten in einem Stapel zum Herunterladen des Zertifikats zu konfigurieren, können Sie folgende Eigenschaft verwenden:

tenant.batch.size=300

Allgemeine Hinweise zur Konfiguration finden Sie hier.