Skip to content
Swiss federal authorities

Configuration of the sedex Web Service Proxy🔗

The sedex Web Service Proxy is configured via the sedex-Client’s main configuration file:

  • OS-based installations: <sedex_home>/conf/sedex-client-configuration.properties
  • Container-based installations: <sedex-data>/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:

  1. Unrestricted Web services allowing anonymous access

    These Web services are accessible to anyone with network access to the sedex Web Service Proxy. Business applications can invoke these services through the sedex Web Service Proxy without requiring a username or password, allowing for anonymous access.

  2. Restricted Web services requiring an authenticated and authorized user

    These Web services are restricted to a specific group of authorized users. Business applications can only invoke the Web service by providing a valid username and password. The sedex Web Service Proxy authenticates such callers. Once authenticated, the user's authorization is verified to ensure they have the right to access the service.

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 mandate the complete disabling of anonymous access to Web services, use the following setting:

wsproxy.users.allowAnonymous=false

Note: When anonymous access is disabled, all business application access to Web services must be conducted via the HTTPS protocol and require a valid 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:

  1. End point for unsecured access using HTTP*

    Web service requests and responses are transmitted using the HTTP protocol, resulting in open and unsecured communication between the business application and the sedex Web Service Proxy. Up to version 5.3, the sedex Web Service Proxy only supported this endpoint.

  2. End point for secured access using HTTPS

    Web service requests and responses are transmitted using the HTTPS protocol, ensuring cryptographically secured communication between the business application and the sedex Web Service Proxy using SSL/TLS. As of version 6.0, the sedex Web Service Proxy supports this endpoint, which 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 for configuring the HTTP and HTTPS endpoints are detailed below.

Unsecured HTTP port🔗

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

wsproxy.http.port=8080

Disable unsecured HTTP port🔗

To completely deactivate the unsecured HTTP port for security reasons, use the following setting:

wsproxy.http.disabled=true

Secured HTTPS port🔗

This setting defines 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:

  1. Self-signed certificate generated by the sedex-Client
  2. Existing certificate provided by the operator (potentially 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:

  1. 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

  2. Configure your key store file in the sedex-Client’s main configuration file:

    • Key store file

      wsproxy.https.key-store-file=${sedex.home}/conf/certificates/my-ssl-keystore.p12

      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-filename=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

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