HTTP POST Sender

Description

This channel provides the functionality to send an HTTP POST request to any given receiver with an enclosed message in the body content

Purpose of object

The HTTP Post Sender is used to transmit a POST HTTP request with content in the body of the request.

Configuration

The dialog to configure the HTTP POST Sender looks like:

Configuration of the HTTP Post Sender channel

Step by Step

• Endpoint: Here you may select Static endpoint or Endpoint as parameter. If Endpoint as parameter is selected, the channel has a parameter ctrl_endpoint. The caller has to provide the actual URL as the value of this parameter. In this case, the URL defined in the Service-URL is not used; if a Proxy server is defined in the Service-URL, this proxy is used even if Dynamic endpoint is selected.

• Service-URL: Here an Environment Entry of type Uniform resource locator is selected. It contains the URL to call if Static endpoint is selected. If in the Environment entry a Proxy server is defined, it is used even if Endpoint as parameter is selected.

• Connect-Timeout: Sets a specified timeout value to be used when opening the HTTP connection. If the timeout expires before the connection can be established, an error is raised. A timeout of zero is interpreted as an infinite timeout.

• Read-Timeout: Sets the read timeout. A non-zero value specifies the timeout when reading the HTTP response. If the timeout expires before data is available to read, an error is raised. A timeout of zero is interpreted as an infinite timeout.

Security

• Authentication: Here you may select an authentication type. You can select one of the following:
  • No authorization required
  • Username/Password
  • Use preemptive authorization (Username/Password)
  • Use certificate authorization
  • Use OAuth2.0 authentication

If you selected Use certificate authorization, the selected user credential must have a PKCS#12 Key Pair. See Credentials for more information about user credentials and key pairs. See also the best practice story "Web Service Security in SOAP web service calls" for more information about how to import a Key Pair.

OAuth can be used for authentication. First, a Json Web Token (JWT) is requested from an identity provider and appended directly to the actual request.

To use this feature, you must make the following configurations:

OAuthClient

Currently, two different grant types are supported. Additional request parameters cannot be added to OAuth authentication at this time.

• Grant Type:

  • Password-Grant: Is a way to exchange a user's credentials for an access token.

    • The following information is required and added to the token request: Client-Identifier, Client-Secret, Username, Password, Identity Provider.
    • The Identity Provider is a URL to a token endpoint.
    • The Client-Identifier and the Client-Secret are base64-encoded and added to the request header and body as authentication.
    • The Username and the Password are added to the body. Currently, the same user credentials are used, which are also used for username/password authentication.

  • Client Credentials: Is used when applications request an access token to access their own resources, not on behalf of a user.

    • Client Credentials (Header): Send client-ID & client-Secret in the Request-Header.
    • Client Credentials (Body): Send client-ID & client-Secret in the Request-Body.
    • The following information is required and added to the token request: Client-Identifier, Client-Secret, Identity Provider.
    • The Identity Provider is a URL to a token endpoint.
    • The Client-Identifier and the Client-Secret are base64-encoded and added to the request header or body.

• User-Credentials: User with the same username and password as on the identity-provider. User type has to be a "Technical login".

• Identity-Provider: Is a URL to a token endpoint of the identity-provider (authorization server).

• Client credential: Is used to select user credentials with Client-Identifier and Client-Secret that are relevant.

  • Client-Identifier: Is the identifier of the user at the identity provider. It is located at the Identity Provider and is set up in Credentials Username/Password as "Account name".
  • Client-Secret: A secret generated by the identity provider. It is also located at the Identity Provider and is set up in Credentials Username/Password as "Password".

• Certificate Check: SSL-Settings or Identity-Provider access. This can be used if the Identity-Provider has an SSL-Connection and the Certificate is a self-signed X509-Certificate. For setting configuration use the certificate authentication as a reference.

• User-Credentials: A user credential of type Technical login. If you work with No authorization required, you need no selection here.

The certificate Check Panel allows a user to configure the client-side HTTPS connection details.

• User-Credentials (type=Technical login): The public/private keypair in pkcs#12 format which should be used for authorization.
• Trusted server (optional, type=Trusted server): This option allows checking the server's public key certificate which is presented by the server when the client makes a request.
• Trusted signer (optional, type=Trusted server): Checks whether the server's certificate has been signed by the given certificate and thus can be trusted.
• Check certificate chain (optional): Check if the certificate chain is correctly signed (certificate n is signed by certificate n + 1).
• Check validity (optional): If set, then check if the certificate is expired.
• Check signers against trust store: If set, then check that one certificate in the certificate chain (typically the last one) is contained in the trust store.
• Cipher Suites (optional): Enforcing specific Cipher Suites to be used in TLS. The cipher suites are added as comma-separated values in the text box (e.g. "TLS_ECDH_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_DHE_RSA_WITH_AES_256_CBC_SHA").

Request settings

• Chunked mode: In case of large messages, the transfer encoding chunked will reduce memory consumption because Orchestra need not serialize the message completely in the memory before sending it over the HTTP connection.
• Request: The message type of the request content.
• Serializer: Here the user can select a Serializer used from Orchestra to serialize the content of the POST call. Typically, here the XML-Serializer or the binary serializer is used.
• HTTP-Header: Here you may set additional HTTP headers. The channel will then have additional parameters to transfer the values of these header parameters.

Response settings

• Response: The message type of the response or, if no response is sent, you may select No response message.
• De-Serializer: Here the user can select a Deserializer to parse the content of the response sent from the server.
• Error processing: Here the user can select a deserializer to parse the content of the error response sent from the server in case of an HTTP 500 response code.
  Caveat: Due to historical reasons, the error content is read only in case of an HTTP 500. Other error codes sent from the server cause an error which can be handled using an error intermediate event in the process model. So, an Error code 500 must be handled differently, meaning that the caller must check if the result message contains success data or error data!

Parameters

Parameter name	Direction	Description
ctrl_endpoint	Ingoing	This parameter is visible if you selected Endpoint as parameter. It is used to overwrite the target URL.
ctrl_credential	Ingoing	This parameter is visible if you selected Use dynamic credentials. It is used to overwrite the used credential.
DYNAMIC_SERVICE_URL	Ingoing	Optional parameter to overwrite the Service-URL environment entry. See EnvironmentEntryBuilder for details.
MSG	Ingoing	Request message.
MSG	Outgoing	Response message.

See also

For special cases of HTTP invocations use the channel HTTP Sender (Parameter), for general use HTTP Caller.

To accept HTTP invocations you can use the channels HTTP GET Receiver, HTTP POST Receiver (General) and HTTP POST Receiver (Parameter).