AS4Connector

The AS4 connector microservice allows you to send and receive payloads via the AS4 messaging protocol. The AS4 connector is compliant with the AS4 minimal client conformance profile defined in the AS4 profile of ebMS 3.0. It allows exchanging any type of payload (e.g., XML, JSON, Binary) as SOAP attachments or SOAP body payloads.

AS4 (Applicability Statement 4) is a Conformance Profile of the OASIS ebMS 3.0 specification, which represents an open standard for the secure and payload-agnostic exchange of Business-to-business documents using Web services.

AS4Connector can be configured in two modes as below:

• Send: To send encrypted/signed message to a receiver.
• Receive: To decrypt and verify the signature of the message received.

Configuration and Testing

Component Configuration

The component can be configured using the Configuration Property Sheet (CPS) as explained in the following sections.

Attributes

Error Handling Configuration

The remedial actions to be taken when a particular error occurs can be configured using this attribute. 

Click the ellipsis button against this property to configure Error Handling properties for different types of Errors.

Refer to the Error Handling section in Common Configurations for detailed information.

Connector Mode

• Send

  The AS4Connector acts as a client and sends an AS4 message to a messaging services handler(MSH).

• Receive

  The AS4Connector acts as a server and receives an AS4 message from a messaging services handler(MSH). If the message is valid the payload is saved and a receipt is sent back to the MSH else an error signal is sent back to the MSH.

  • Service Name

    The service name assigned to the AS4 Server instance. It specifies the service name to which the client has to send the message.
    
    

    

    
    Figure 3: Receive connector mode options

    When deployed, a URL is assigned in the following format:

    CODE

    http://<IPAddress>:1880/bcwsgateway/services/SERVICE_NAME

    

    Service Name property appears only when Connector Mode is selected as "Receive"

Connection Configuration

Click the ellipsis button against this property to edit connection configuration.

• Send URI

  Endpoint Address where the service is hosted in the Target EBMS server.

• Maximum Idle Timeout

  It is the maximum time (in milliseconds) till which a connection exists between the server and client without sending a request.

Conformance Profile

Specifies Conformance Profile to be implemented.

• Light Client

  This is an entry level conformance profile which enables sending and receiving EBMS 3.0 messages.
  

  
  

• Minimal Client

  Provides security features like username token and digital signature while sending and receiving EBMS 3.0 messages.

Conformance Profile - Light Client

P-Mode Parameter Configuration

Click the ellipsis button to configure P Mode parameters.

Read input from file

If enabled, it allows the client to send different types of payload (to the target EBMS server) retrieved from a file that may be referred to using the following properties.

• Attachment Directory 

  It is the directory where the payload file is saved.

• Attachment File

  It is the file containing payload details.

Conformance Profile - Minimal Client

Apart from the properties mentioned in the sections above (Error Handling Configuration, Connector Mode, Service Name, Connection Configuration, P-Mode Parameter Configuration and Read input from file), the below-mentioned are the properties exclusively available for Minimal Client Conformance Profile.

Request Options

UsernameToken WS-Security

If the web service performs UsernameToken identification for the request, then this property should be enabled. Username and password values are added to the message headers.

Order of UsernameToken

Determines the order of the UsernameToken security function. The order of a security function determines when this function will be applied when multiple security functions are being used. Choose from 1 to 5.

User

This property is used as the username for the UsernameToken security function. It is also used as the alias name in the keystore to get user's certificate or private key to perform signing for the Signature security function in case of "Signature User" is null and "Signature WS-Security (Request)" is set to yes. It is also used as the fallback for the encryption security function in case of "Encryption User" is null and "Encryption WS-Security (Request)" is set to yes.

Password Callback class

This is needed by the security functions to get the password and to verify the username/password pair. The password callback class should implement javax.security.auth.callback.CallbackHandler class. This Password Callback class should be the fully qualified name of the class. The jar which contains the password callback class should be added as a resource to the component.

Password callback class is not required if the (12.0) AS4Connector#Password Type option is selected as PasswordNone.

Nonce Security element

Specifies whether to use nonce element in the security header or not. When UsernameToken security function is used, then nonce security element can be employed to prevent message replay attacks. A nonce is a random value that the client creates to include in each UsernameToken that it sends. Although using a nonce is an effective countermeasure against replay attacks, it requires the server to maintain a cache of used nonces, consuming server resources.

Created Security element

Specifies whether to use Created element in the security header or not. This element denotes the time of creation of a nonce. Combining a nonce with a creation timestamp has the advantage of allowing a server to limit the cache of nonces to a "freshness" time period, establishing an upper bound on resource requirements.

Password type

The Password type specifies how the client sends the password value to the server.

• PasswordText: Password is sent in raw text format within the security header of the soap request.
• PasswordDigest: Password is sent in digest format within the security header of the soap request.
• PasswordNone: No password will be sent in the security header. This option is useful when the user wants to specify the username without any password.

Signature WS-Security

If this security function is selected the digest of the message is created and encrypted before sending. The property "User" must be specified to get the private key/certificate of the respective user from the keystore for signing.

Signature User

This name is used as the alias name in the keystore to get user's certificate and private key to perform signing. If this parameter is not set, then the signature function falls back to the "User" parameter to get the certificate. Password for the user to get certificates from the keystore should be provided in the Password Callback class.

Order of Signature

Specifies the order of the Signature security function. The order of a security function determines when this function will be applied when multiple security functions are being used.

Signature Properties filename

The name of the crypto property file to use for SOAP Signature.

Please refer to the Encryption Properties filename (Request) section in the WebServiceConsumer4.0 documentation fordescription.

Signature Algorithm

The parameter specifies signature algorithm to be used. If an algorithm is not specified then the algorithm "http://www.w3.org/2000/09/xmldsig#rsa-sha1" will be used by default.

Canonicalization Method

The parameter specifies the canonicalization method to be used in the process of signing the request. If no method is specified then the method "http://www.w3.org/2001/10/xml-exc-c14n#" will be used by default.

Signature Parts

The parameter specifies which parts of the request shall be signed. Please see the description of "Encryption Parts" for the syntax.

Signature Key Identifier

Select the key identifier type to use. Please see the description of "Encryption Key Identifier" for the descriptions of key identifiers.

Response

Ignore Order

If this is set, Order of Security actions will be ignored for the incoming response.

UsernameToken WS-Security

Determines whether the response from the server contains Username token headers or not.

Order of UsernameToken

Determines the order of the Username Token security function. The order of a security function determines when this function will be applied when multiple security functions are being used.

Password Callback class

This is needed by the security functions to get the password and to verify the username/password pair. The password callback class should implement javax.security.auth.callback.CallbackHandler class. This Password Callback class should be the fully qualified name of the class. The jar which contains the password callback class must be added as a resource to the component.

Is Password Required

This property must be disabled if the Username security token is used without a password.

No need to provide Password callback Class if this property is disabled.

Signature WS-Security

Specifies whether the soap response or some parts of the soap response are signed or not.

Order of Signature

Specifies the order of the Signature security function. The order of a security function determines when this function will be applied when multiple security functions are being used.

Signature Properties filename

The name of the crypto property file to use for SOAP Signature.

Please refer to the Encryption Properties filename (Request) section in the WebServiceConsumer4.0 documentation for description.

Expert Properties

Enable the Expert Properties view to configure these properties.

Expert properties are meant for advanced users. Use with caution!

Pre Processing XSL Configuration

Pre Processing XSL configuration can be used to transform request message before processing it. Click the ellipses button against the property to configure the properties.

Refer to the Pre/Post Processing XSL Configuration section under the Common Configurations page for details regarding Pre Processing XSL configuration and Post Processing XSL configuration (below).

Post Processing XSL Configuration 

Post Processing XSL configuration can be used to transform the response message before sending it to the output port.

Process Message Based on Property

The property helps components to skip certain messages from processing.

Refer to the Process Message Based On a Property section under the Common Configurations page.

Validate Input

If enabled, the microservice validates the input received.

If the Input validation is disabled, it does not validate the input and thereby increases the performance. However, it may cause undesired results if the input XML is not valid.

Cleanup resources (excluding connection) after each document

This closes all the resources except for the connection after every request. If the less processing time is more important than the less memory usage, then it is recommended to disable this property and vice versa.

For more details, refer to the respective section under in the Common Configurations page.

Target Namespace

Target Namespace for the request and response XML messages.

For more details, refer to the respective section under in the Common Configurations page.

Functional Demonstration

Scenario 1

Demonstrate sending and receiving AS4 messages (image file as payload) in Light Client Conformance profile.

Configure the AS4Connector in RECEIVE mode and provide proper service name and P-Mode parameter details.

Configure another AS4Connector in SEND mode and provide the proper URL in send URI. Connect Feeder and Display microservices to send input and receive output respectively.

Input

The following input is sent from the feeder.

Output

The following is the receipt which is sent to the client is shown in the display.

Scenario 2

Demonstrate sending and receiving AS4 messages (image file as payload) in Minimal Client Conformance profile.

Configure an AS4Connector microservice in RECEIVE mode and another one in SEND mode as mentioned in Scenario 1.

Enable UsernameToken (Response) in both AS4Connectors.

Input

Send the same input as in Scenario 1 using Feeder.

Output

If the authentication is valid, the security tags related to UsernameToken such as Username, Password, NonceElement, Created Element can be seen in the Display window.