Dieser Service empfängt die AS4 Nachrichten der Marktpartner. Nach dem Eingang wird die Nachricht über den Message-Broker an den Crypto Operations weitergeleitet. Der Crypto Operations antwortet mit der Empfangsbestätigung für den Sender. Und anschließend wird die Bestätigung zu Speicherung an den AS4 Message Service versandt.
Die API des AS4-Inbound-Endpoint muss durch die Marktpartner aufrufbar sein.
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 verschiedene AS4 Services erfolgt über einen Message-Broker.
rabbitmq.host=localhost
rabbitmq.port=5672
rabbitmq.username=guest
rabbitmq.password=guest
AMQP Routing Konfiguration
Falls Sie das Standard Routing nutzen, muss das Routing nicht weiter konfiguriert werden. Wenn Sie Ihr Routing anpassen möchten, lesen Sie die folgende Dokumentation.
Weiterleiten der AS4 Nachricht an den Crypto Operations
Die vom Marktpartner eingegangen AS4 Nachricht wird über die Queue as4.decrypt.verify.default an den Crypto Operations weiter gegeben.
inboundCryptoMessageExchangeName=as4.decrypt.verify
Erhalt der Empfangsbestätigung
Der Crypto Operations antwortet mit einer signierten Bestätigung über die Queue as4.send.receipt.default.
receiptConsumerExchangeName=as4.send.receipt
Persistierung der Empfangsbestätigung
Nach Versendung der Empfangsbestätigung an den Marktpartner wird diese über die Queue as4.receipt.default an den AS4 Message Service zum Speichern abgelegt.
receiptExchangeName=as4.receipt
Nachrichten, die nicht verifiziert werden können, für die keine Bestätigung vom AS4 Receipt Service empfangen wurde, oder andere Probleme auftreten, werden direkt zum AS4-Message-Service über die Queue as4.messages.default geleitet. Es wird ein dazugehöriges, “leeres” Receipt mit entsprechendem Report in die Queue as4.receipt.default gelegt. Die Objekte werden im As4-Message-Service konsumiert und persistiert, sodass sie im MessageMonitor einsehbar sind. Es gibt keine Benachrichtigung/Receipt dazu, daher sollte der Sachbearbeiter oder Administrator regelmäßig dort nachschauen.
businessMessageExchangeName=as4.messages
Der Parameter Connection Timout wird in Sekunden angegeben und gibt die Wartezeit des Threads an, der auf die Antwort des Crypto Operations wartet. Mit dem zweiten Parameter lässt sich die Kommunikation mit dem Crypto Operations für Entwicklungszwecke temporär ausschalten.
connectionTimeout=300
skipCrypt=false
Routing Konfiguration der as4-inbound-endpoint.properties
Für die Aktivierung des Routings müssen der headerName und die headerValues gesetzt werden. Den headerName kann man sich als Filterkategorie vorstellen, während die headerValues den zu filternden Werten entsprechen. Nachrichten mit Werten, die nicht explizit als headerValues aufgelistet sind, laufen weiterhin über die default Route.
Als headerName werden folgende Parameter angeboten:
- tenant: ILN Nummer des Senders
- partner: ILN Nummer des Empfängers.
- sector: GAS, ELECTRICITY
Es können mehrere Werte kommasepariert angegeben werden.
inboundCryptoMessageExchangeName=as4.decrypt.verify
inboundCryptoMessageHeaderName=partner
inboundCryptoMessageHeaderValues=
receiptExchangeName=as4.receipt
receiptHeaderName=partner
receiptHeaderValues=
businessMessageExchangeName=as4.messages
businessMessageHeaderName=partner
businessMessageHeaderValues=
Wird der Producer für das Routing konfiguriert muss natürlich auch die Gegenstelle dafür eingerichtet werden. Dem Consumer wird über die Gruppe der Wert (Value) aus der HeaderValues Liste zugewiesen nach welchem gefiltert werden soll. Bitte den Default Wert nur ändern, wenn Routing verwendet werden soll. Aktuell muss der BindingRoutingKey jedoch immer angegeben werden. Dieser ist, wenn kein Routing verwendet wird ‘default’.
receiptConsumerExchangeName=as4.send.receipt
receiptConsumerGroup=default
spring.cloud.stream.rabbit.bindings.consumeReceipt-in-0.consumer.bindingRoutingKey=default
Max Concurrency - Parallelität
Es ist möglich für den Consumer die Eigenschaft max-concurrency zu setzen. Diese definiert die maximale Anzahl von gleichzeitigen Verarbeitungsthreads, die für einen Consumer gestartet werden können. Der Default liegt bei 50.
receiptConsumerMaxConcurrency=50
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 kann erst erfolgreich sein, nachdem der Zertifikats-Ladeprozess abgeschlossen ist. Falls die Property startupSslCheck=true gesetzt ist, schlägt der Health-Check fehl, wenn nicht alle Zertifikate geladen werden konnten.
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 (default false)
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
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
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
Allgemeine Hinweise zur Konfiguration finden Sie hier.
View Me Edit Me