Phase 1, Event-driven Input Agent "HTTP"

An external HTTP client sends a request to the Lobster Integration Server. The data is passed to a matching profile that uses an event-driven Input Agent of type "HTTP" in phase 1. The response to the HTTP client is either a fixed value or is generated from the target structure data of the profile.

Phase 1, Any time-driven Input Agent, "Trigger/External Call"

An external HTTP client sends a request to the Lobster Integration Server. That starts a matching profile with a time-driven Input Agent and option "Trigger/External Call". This Input Agent collects its input data via its configured data source (e.g. a database), i.e. the data does not come from the HTTP request itself.

The profile can only retrieve request parameters as variable values from the client request. Those variable values can then, for example, be used in the mapping of the profile or to parameterise the Input Agent, e.g. in the "WHERE" clause of a database select.

Phase 1, Time-driven Input Agent "HTTP"

A profile uses a time-driven Input Agent of type "HTTP" in phase 1. It sends a request to an external HTTP server. The response of the server is received by the profile as input data.

Phase 3, Functions

A profile uses one of the following functions in phase 3. The function sends a request to an external HTTP server. The response from the server can be processed in the target structure.

• http()

• http json-lookup()

Phase 6, Response "HTTP"

A profile sends a request to an external HTTP server in a Response of type "HTTP" in phase 6. The response of the server can be forwarded to a subsequent profile and processed there.

Searching for keystore file

Lobster Integration looks for a file in directory ./etc/certs that has the name of the host in the URL of the server address. So for the URL "https://www.java.com", for example, Lobster Integration would look for a file named "www.java.com".

If such a file is found, the contents of the file are read in and interpreted as a Java keystore. The keystore must contain the keys (including the private key) and all certificates of the certificate chain. The keystore may only contain one key pair and the key password must match the keystore password. This password must be defined with parameter keystorePassword in configuration file ./etc/startup.xml.

The password can be specified in plain text or better obfuscated. The keystore can either be created and edited using the program "keytool" or - much more comfortable - with "Portecle".

No matching keystore file found

If no matching keystore file is found, the following mechanism takes effect.

If the system variable VAR_AUTH_CERT_ID is defined and a non-empty value has been assigned to it, then the value of this variable is interpreted as the ID (serial number) of a local certificate in the Partner Administration. If a certificate with this ID is found, it will be passed to the HTTPS server. The client then uses this certificate as client certificate for authentication if the server requires it.

No file with certificate found and variable not defined

If no file with a certificate is found and the variable is not defined, no certificate is passed to the HTTPS server. There will be no error message.

The procedure described is always executed when Lobster Integration appears in the role as HTTPS client. That is, for profiles with time-driven Input Agent "HTTP" and for profiles with at least one Response of type "HTTP".

The ID (serial number) of your local certificate can be obtained from the list of your local certificates in the Partner Administration. Simply view a certificate and copy the ID with Ctrl+C. This ID can then be entered in the GUI or you can alternatively select a local certificate from a list and the ID will be entered automatically.

Preliminary remarks

Normally, HTTP authentication works as described under https://tools.ietf.org/html/rfc2617. In case of a Basic Authentication, the procedure is as follows.

• The client sends a request without login and password.

• The server recognises that the requested URL requires a login and therefore returns HTTP status 401 to the client.

• When the server expects Basic Authentication, it sends a response header. WWW-Authenticate: Basic realm="RealmName"

• The client decides if he knows a username and password for this URL from a recent request.

• If the client does not have login data, it usually asks the user to enter those in the login dialogue.

• The client resends the request with the HTTP header. Authorization: Basic d2lraTpwZWRpYQ==

• The value d2lraTpwZWRpYQ== is just an example Base64 encoding of the value wiki:pedia (i.e. the username "wiki" and password "pedia"). For details on the Base64 encoding, see the documentation for the Admin Console of the Integration Server.

• The server checks the login information. If he accepts them, he grants access.

• If it does not accept the login, the server either sends status 401 again or status 403.

• Status 403 means that the client has sent an authorisation header but the user is not authorised or that the requested operation is prohibited for all users.

The access thus consists of two requests, the first of which is done without a login and only the second is done with login data (after the server replies with status 401). This is very inefficient for a POST request because several kilobytes of data are possibly uploaded without benefit on the first request.

The technical process of the preemptive authentication

In this case, the client simply sends the HTTP header "Authorization" on the first request. Especially when data is uploaded to a web service via POST, this saves half of the upload volume and time. An HTTP/HTTPS server that allows Basic Authentication will usually accept the preemptive variant as well. For other authentication methods, e.g. NTLM, the first request is not dispensable, because the server sends a key/hash/code in its first response, which the client then has to use in some way to create the second request.

If the server supports preemptive authentication only

If the server requires that the client already sends the Authorization HTTP header on the first request, communication will not be established unless the client is configured accordingly. The client will then send the first request without login, but the server does not respond with status 401, but immediately with 403. However, since the client does not receive a challenge through status 401, it will not send an Authorization HTTP header with the next request either. A successful communication will not be established that way.

Servers that only allow preemptive authentication are certainly the absolute exception. However, if such an error occurs (status 403) when accessing an HTTP server, one must consider the possibility that a preemptive login is expected. But that's not the only possible cause for a response status 403. See https://en.wikipedia.org/wiki/HTTP_403.

Does Lobster Integration support preemptive authentication?

This question is especially relevant when Lobster Integration acts as a client. HTTP headers in an "HTTP" Response or time-driven Input Agents "HTTP" are inserted as follows. The BASE64 value "d2lraTpwZWRpYQ==" must first be generated out of <username>:<password> (so here from "wiki:pedia", see preliminary remarks above). Then it is inserted in dialogue "Adjust HTTP headers". Entering username and password in the usual fields of Responses or Input Agents will then be irrelevant because it will never be used.

Example:

(1) HTTP-Header: "Authorization".

(2) Value: "d2lraTpwZWRpYQ==".