Configuring

The sedex Web Service Proxy is configured via the sedex Client’s main configuration file (see Properties for details): <sedex_home>/conf/sedex-client-configuration.properties.

This section describes the sedex Web Service Proxy-specific configuration parameters.

Activating and deactivating sedex Web Service Proxy¶

If the sedex Web Service Proxy functionality is not required, it can be deactivated with the following configuration setting:

wsproxy.start=false

Disabling anonymous access¶

There are two basic types of Web services with regard to access control:

Unrestricted Web services allowing anonymous access

These Web services are open for everybody with network access to the sedex Web Service Proxy. A business application can call the Web service via sedex Web Service Proxy without a username and password. Such a caller is anonymous to the sedex Web Service Proxy.
Restricted Web services requiring an authenticated and authorized user

These Web services are restricted to a group of known and authorized users. A business application may only call the Web service when providing a valid username and password combination. Such a caller is authenticated by the sedex Web Service Proxy. Once authenticated, a user can be authorized, i.e. it can be checked whether he has the right to use the service or not.

The Web service definitions provided by sedex determine which Web service may be called anonymously and which not. List of provided Web services explains how to check which Web services are restricted and which are unrestricted.

If security policies require anonymous access to Web services to be completely disabled, use the following setting:

wsproxy.users.allowAnonymous=false

Note: If anonymous access is switched off, all access from business applications to Web services must be done via the HTTPS protocol and with a username and password.

Local network end points¶

The sedex Web Service Proxy offers two separate network end points to which business applications can send their Web service requests:

End point for unsecured access using HTTP

Web service requests and responses are transmitted using the HTTP protocol. The communication between the business application and the sedex Web Service Proxy is open/unsecured. Up to version 5.3 the sedex Web Service Proxy offered only this end point.
End point for secured access using HTTPS

Web service requests and responses are transmitted using the HTTPS protocol. The communication between the business application and the sedex Web Service Proxy is cryptographically secured using SSL/TLS. As of version 6.0, the sedex Web Service Proxy also offers this end point. This end point should be preferred.

Note: The Web service definitions provided by sedex determine which Web service may be called via HTTP and which not. List of provided Web services explains how to check which Web services are available via HTTP and which are only available via HTTPS.

Note: Even when the business application accesses the sedex Web Service Proxy via unencrypted HTTP, the connection between the sedex Web Service Proxy and the effective Web service is always secured and encrypted via HTTPS.

The properties configuration the HTTP and HTTPS end points are described below.

Unsecured HTTP port¶

This setting specifies the network port for unsecured access to the sedex Web Service Proxy:

wsproxy.http.port=8080

Disable unsecured HTTP port¶

If it is desired for security reasons to completely deactivate the unsecured HTTP port, this can be achieved with the following setting:

wsproxy.http.disabled=true

Secured HTTPS port¶

This setting specifies the network port for secured access to the sedex Web Service Proxy using SSL/TLS:

wsproxy.https.port=8443

SSL/TLS certificate¶

As of version 6.0, the sedex Web Service Proxy offers the possibility of a secure communication between the business application and the sedex Web Service Proxy using HTTPS protocol. The HTTPS protocol is based on SSL/TLS standard for the cryptographic protection of the communication channel. This requires a special SSL/TLS certificate to be installed and configured in the sedex Web Service Proxy.

Basically two types of SSL/TLS certificates can be used:

Self-signed certificate generated by the sedex Client
Existing certificate provided by the operator (may be an official SSL/TLS certificate)

Using the self-signed certificate generated by the sedex Client¶

If the sedex Client does not find an SSL/TLS certificate for the sedex Web Service Proxy at startup, it automatically generates and configures a self-signed certificate.

Notes regarding the self-signed certificate:

The self-signed certificate is not signed by a public and generally trusted certificate authority (CA), but these certificates are easy to create and are free. A disadvantage of self-signed certificates is that they are not automatically trusted and must always be manually added to the trust store of the business application calling the sedex Web Service Proxy.
The self-signed certificate is valid for 5 years. You can find the expiration date on the sedex Client’s monitoring page (see Monitoring).
To recreate the certificate, simply delete the path to the certificate from the property in the configuration file: wsproxy.https.key-store-file=
The generated certificate is valid for all host names that the sedex Client could automatically detect. The sedex Web Service Proxy writes these host names into the log file during the creation of the self-signed certificate. Alternately, you can open and examine the certificate.
To create a self-signed certificate with an additional host name of your choice do the following:
1. Add the parameter wsproxy.https.hostname=your-host-name
2. Delete the value of the parameter wsproxy.https.key-store-file=
3. Automatically recreate the certificate by restarting the sedex Client
The key store file generated for the self-signed certificate is in P12 format and is stored under the following path: <sedex_home>/conf/certificates
Additionally, a CER file containing the public certificate is created. You can pass this file on to the developers or operators of the business application so that they can include the self-signed certificate in their trust store.

Using an existing certificate provided by the operator¶

If you already have a valid SSL/TLS certificate, the sedex Web Service Proxy can be configured to use it for its HTTPS end point. In order to use your own certificate, it must be in one of the following formats:

PKCS#12 (p12 file)
Java Key Store (jks file)

Note: The key store provided must contain both the private key and the certificate under the same alias name.

Tip: The freely available Java based tool “KeyStore Explorer” (keystore-explorer.org) allows the comfortable editing of key store files. Among other things, you can create a key store from private keys and certificates in separate files, which can then be used by sedex Web Service Proxy.

Once you have your own SSL/TLS certificate in a supported format, you can install and configure it in the sedex Client as follows:

Copy your key store file (e.g. my-ssl-keystore.p12) into the sedex Client configuration folder for certificates:

<sedex_home>/conf/certificates/my-ssl-keystore.p12
Configure your key store file in the sedex Client’s main configuration file:
- Path to the key store file
  
  Note: It’s possible to use the term ${sedex.home} to define a path relative to the sedex Client home folder.
  
  wsproxy.https.key-store-file=${sedex.home}/conf/certificates/my-ssl-keystore.p12
- Password with which the key store file is secured
  
  wsproxy.https.key-store-password=myKeystorePassword
- Optional: Password with which the key itself is secured
  
  If the passwords for the key and key store are identical, the key password does not have to be configured, which is normally the case.
  
  When using different passwords, manually add the following key:
  
  wsproxy.https.key-password=myKeyPassword
- Optional: Alias name of the key to use
  
  If there is only one key in the key store, the alias does not have to be configured. This is normally the case.
  
  If your keystore contains multiple keys, you can determine the key by specifying its alias. Manually add the following key:
  
  'wsproxy.https.key-alias=myAlias`
Restart the sedex Client and check the log file of sedex Web Service Proxy for errors.