AS4 Inbound Endpoint Dokumentation

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.

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.

receiptConsumerExchangeName=as4.send.receipt
receiptConsumerGroup=default

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.

Der Port lässt sich über folgende Property konfigurieren: server.port=8080.

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.

Multi-Tenancy

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

Ausfallsicherheit

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.

Redundancy

Die Quittung wird über die Queue an die Service-Instanz übergeben. Aktuell kann die Service-Instanz nicht präzise angesteuert werden. Deshalb wird für jede Instanz eine eigene Queue eingerichtet. Die Exchange as4.send.receipt verteilt per Fanout Routing Kopien der Quittung an alle Queues. Nur die Instanz mit der zugehörigen offenen AS4-Verbindung verschickt die Quittung, alle anderen Instanzen verwerfen die Quittung.

Redundancy

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

mTLS

Um eine sichere mTLS-Verbindung zum as4-inbound-endpoint sicherzustellen, ist vor der Aktivierung von mTLS eine gewisse Konfiguration erforderlich. Wichtig zu beachten ist, dass das mTLS für mehrere Mandanten geeignet ist. Die SSL-Konfiguration wird basierend auf allen verfügbaren Mandanten geladen.

  • Mandanten müssen in der tenant-address table der AS4 database konfiguriert werden
  • In der Eigenschaftendatei muss die address-service url angegeben werden und der address-service muss ausgeführt werden
  • Bereits zur Bootzeit des Service muss der FSS sowie das HSM vollständig erreichbar sein. Weiterhin müssen zur Bootzeit bereits alle benötigten Zertifikate & Schlüssel verfügbar sein. Die FSS-URL muss in der Eigenschaftendatei angegeben werden.
#=== SSL Properties ===#
sslEnabled=false
sslPort=8443
ssl.partner.client=shared-client

Der Standardwert für sslEnabled ist false. Wenn die Eigenschaft nicht konfiguriert ist, wird sie daher standardmäßig auf false gesetzt. Wenn die Eigenschaften sslPort und ssl.partner.client nicht festgelegt sind, wird standardmäßig 8433 bzw. shared-client verwendet.

Die mTLS-Funktionalität kann mit der Eigenschaft sslEnabled ein-/ausgeschaltet werden (entweder durch standardmäßige Einstellung auf true oder false). Die Mandanten, für die SSL konfiguriert ist, stammen aus der Mandantenadresstabelle. Dort muss der Tenant konfiguriert werden. Darüber hinaus sollten wir für die verfügbaren Mandanten ein TLS-Zertifikat (und den entsprechenden Schlüssel im HSM) im FSS haben. Unter dem angegebenen gemeinsamen Client sollten auch Ausstellerzertifikate des Partners vorhanden sein.

Note: FSS, HSM und address-service müssen ausgeführt und vom as4-inbound-endpoint ausgeführt und aufrufbar sein

Legen Sie die folgenden Eigenschaften für die URLs der Dienste fest:

fss.server.api.url=http://localhost:2222/fss/api/v1
addressServiceUrl=http://localhost:8089/aep-as4-address-service

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.

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

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.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