Skip to content

Basic Configuration of the sedex Webservice Proxy

In the following, you will find how you can configure sedex Webservice Proxy and which parameters are available for this purpose. If you are only using asynchronous sedex messaging, this page is not relevant for you.

Configuring sedex Webservice Proxy

For the general configuration parameters, the sedex Webservice Proxy is configured like the sedex Client. See Configuration of the sedex Client for details.

In this section, the configuration parameters specific to the WS-Proxy are described.

Enabling and disabling sedex Webservice Proxy

The following configuration shows an activated WS-Proxy (default value):

   wsproxy.start=true

The following configuration shows a deactivated WS-Proxy:

   wsproxy.start=false

Checking if sedex Webservice Proxy is active

On the monitoring page of a running sedex Client, you can check whether the WS-Proxy is active. If at least some of the “wsp” elements are listed as shown below, the sedex Webservice Proxy is active. If there are no entries starting with the prefix “wsp-“, then the WS-Proxy is not active.

    [...]
    wsp-https-port=8443
    wsp-https-tls-certificate-subject=CN=sedex-wsproxy, O=sedex (www.sedex.ch)
    wsp-https-tls-certificate-issuer=CN=sedex-wsproxy, O=sedex (www.sedex.ch)
    wsp-https-tls-certificate-create-date=2019-12-04T12:43:54
    wsp-https-tls-certificate-expiry-date=2024-12-02T12:43:54
    wsp-https-tls-certificate-alternative-names=wsproxy,localhost
    wsp-https-tls-certificate-is-valid=true
    wsp-http-disabled=false
    wsp-http-port=8080
    wsp-uptime=00:05:55
    wsp-users-allow-anonymous=true
    wsp-version=WsProxy 6.0.0
    wsp-webservice=/wsproxy/services/CheckSedexWebService  [protocols:http,https] 
                    [users:anonymous,authorized]
    wsp-webservice=/wsproxy/services/PartnerServices  [protocols:https]
                    [users:authorized]
    wsp-webservice=/wsproxy/services/sedexExternalAuthorisationService 
                    [protocols:http,https] [users:anonymous,authorized]
    wsp-webservice=/wsproxy/services/ZRWebserv/getNNSS  [protocols:https]
                    [users:authorized]
    wsp-webservice-definitions-updated-at=2019-12-04T13:15:43
    wsp-webservice-definitions-expires-at=2019-12-05T13:15:43
    wsp-webservice-definitions-update-status=OK
    wsp-webservice-definitions-update-info=Updated successfully
    wsp-webservice-definitions-valid=true
    wsp-webservice-last-call=controller-uptime=00:06:00 
    [...]

Disabling Anonymous Access

Regarding access control there are two basic types of Web services:

  1. Unrestricted Web services - allowing anonymous access

    These are Web services that are open for everybody with network access to the WS-Proxy. This means that a business application can call the Web service via WS-Proxy without indicating a username and password. One says that such a caller is anonymous to the WS-Proxy.

  2. Restricted Web services - requiring an authenticated and authorized user

    These are Web services that are restricted to a group of known and authorized users. This means that a business application can only call the Web service together with a valid username and password combination. One says that such a caller is authenticated by the WS-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.

If it is desired for security reasons to completely deactivate anonymous access to Web services, this can be achieved with the following configuration parameter:

    wsproxy.users.allowAnonymous=false

Note: about switching anonymous access off

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

Local Network Endpoints Configuration

The sedex WS-Proxy offers two separate network endpoints where business applications can send their Web service requests to:

  1. Endpoint for access using HTTP (unsecured)

    Webservice requests and responses are transmitted using the HTTP protocol. This means that the communication between the business application and the WS-Proxy is open/unsecured. Up to version 5.3 the sedex WS-Proxy only offered this endpoint.

  2. Endpoint for access using HTTPS (secured)

    Webservice requests and responses are transmitted using the HTTPS protocol. This means that the communication between the business application and the WS-Proxy is cryptographically secured using SSL/TLS. As of version 6.0, the sedex WS-Proxy also offers this endpoint. This endpoint should be preferred.

Information: Determine protocol to access WS-Proxy

The Web service definitions provided by sedex determine which Web service may be called over HTTP and which not. Check the monitoring page of the sedex Client to see which Web services are available over HTTP and which are only available over HTTPS.

Note: Connection between WS-Proxy and Web service is allway secured

Even when the business applications accesses the WS-Proxy via unencrypted HTTP, the connection between the WS-Proxy and the effective Web service over the Internet is always secured and encrypted via HTTPS.

The properties allowing the configuration of the HTTP and HTTPS endpoints are described below.

Unsecured HTTP port

The unsecured HTTP port number inside of the container is 8080. You can publish/map this port to the desired port number on the outside using your container platform.

Note: You can omit this port publication/mapping if the WS-Proxy will not be used or will only be used via HTTPS.

  --publish YOUR_WS_PROXY_HTTP_PORT:8080

Secured HTTPS port

The secured HTTPS port number inside of the container is 8443. You can publish/map this port to the desired port number on the outside using your container platform.

  --publish YOUR_WS_PROXY_HTTPS_PORT:8443

SSL/TLS Certificate Configuration

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

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

  1. Generated by the sedex Client (self-signed certificate)

    If the client is started and no SSL/TLS certificate is configured, the client automatically generates a new self-signed certificate.

  2. Existing certificate provided by the operator (may be an official SSL/TLS certificate)

    The operator of a sedex Client can obtain and use an official SSL/TLS certificate from a certificate provider and configure this in the sedex Client.

Note: About self-signed certificates

A self-signed certificate is a certificate that is not signed by a public and generally trusted certificate authority (CA). These certificates are easy to make and are free. A disadvantage of self-signed certificates is that they are not automatically trusted. This means that such certificates must always be added manually to the trust store of a user – here the business application calling the WS-Proxy.

Using the self-signed certificate generated by the sedex Client

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

Notes regarding the self-signed certificate:

  • The self-signed certificate is valid for 5 years. You can find the expiration date on the monitoring page of the sedex Client.

  • If you want to recreate the certificate, simply delete the path to the certificate from the property in the configuration file:

       wsproxy.https.key-store-filename=

  • The generated certificate is valid for all host names that the sedex Client could automatically detect. The WS-Proxy writes these host names to 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 steps:

    1. Add the parameter

      wsproxy.https.hostname=your-host-name

    2. Delete the value of the parameter

      wsproxy.https.key-store-filename=

    3. Let the the certificate be recreated by restarting the sedex Client

  • The generated certificate is valid for all host names that the sedex Client could automatically detect.

  • The keystore file generated for the self-signed certificate is in P12 format and is stored under the following path:

        sedex-data/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 WS-Proxy can be configured to use it for its HTTPS endpoint. 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: alias of the key and certificate

The keystore provided must contain both the private key and the certificate under the same alias name.

Tip: "KeyStore Explorer" tool

The freely available Java-based tool KeyStore Explorer allows the comfortable editing of keystore files. Among other things, you can create a keystore from private keys and certificates in separate files, which can then be used by WS-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:

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

    sedex-data/conf/certificates/my-ssl-keystore.p12

  2. Configure your keystore file in the sedex Client’s main configuration file:

    • Path to the keystore file

      wsproxy.https.key-store-filename=my-ssl-keystore.p12

    • Password with which the keystore file is secured

      wsproxy.https.key-store-password=myKeystorePassword

    • Alias name of the key to use

      A keystore file may contain one or many private keys. To select the correct key, its alias name must be specified. If you don't know the alias name, you can examine the content of the keystore with a suitable tool (e.g. with the KeyStore Explorer mentioned above).

      wsproxy.https.key-alias=my-key-alias

    • Password for accessing the key to use

      Within a keystore, a separate password can be set again for each key. If no separate password has been set for the key, enter the password for the keystore again here.

      wsproxy.https.key-password=myPrivatePasswordForTheKey

  3. Restart the sedex Client and check the log file of WS-Proxy for errors.