HTTPS for Platform Service

The following configuration are required at the Platform Service for accepting a HTTPS connection.

TLS configuration

Server-side configuration for GWS Platform Service

To enable HTTPS at the server-side,

1. Configure the following TLS-specific settings.

Name	Mandatory	Default Value	Description
GWS_SERVER_TLS_REQUIRED	No	false	Determines if TLS is required. Change to true if a certificate is also provided. Note: Once TLS is enabled, Platform Service accepts only HTTPS requests.
GWS_SERVER_TLS_PROVIDER	No	rustls	Specifies the TLS provider. Possible values: rustls, native.
GWS_SERVER_TLS_HANDSHAKE_TIMEOUT	Yes (if TLS is enabled)	10000 (ms)	Specifies the timeout (in milliseconds) for TLS handshake. Default is 10000 ms (10 seconds).
GWS_SERVER_TLS_CERT_PATH	Yes (if TLS is enabled)	-	Specifies the path to the TLS certificate.
GWS_SERVER_TLS_KEY_PATH	Yes (if TLS is enabled)	-	Specifies the path to the TLS key.
GWS_AUTH_TOKEN_IDLE_TIME	No	-	Specifies the idle time (in seconds) before an auth token is considered inactive. If absent, all tokens remain active until expiration.
GWS_SERVER_TLS_CERT_PASSWORD	No	""	Specifies the password for the TLS certificate, if applicable.

2. After you enable TLS for the Platform Service, ensure to update the health check URL in the get_version() function within /usr/bin/gws-service-platform to use HTTPS. For example, RESPONSE=$(curl -XGET -skLS https://${GWS_HOST}:${GWS_PORT}${GWS_HEALTH_CHECK_URL} 2>&1)

3. Update monitoring services, such as Grafana, to send requests to the Platform Service using the HTTPS endpoint after enabling TLS.

Client-Side Configuration for GWS 8.6

1. Platform Service URL Configuration

To establish an HTTPS connection with the Platform Service, configure the Platform Service URL in the application.yaml file as shown below:

serverSettings: 
  platformSettings: 
    platformServiceUrl: https://<ip>:<port>

2. CA Certificate Configuration

Make sure that the configured CA (Certification Authority) certificates are added to the Java KeyStore (JKS) file:

serverSettings: 
  caCertificate: /opt/ca_cert.jks   # Path to the CA certificate keystore file
  jksPassword: pa$$word             # Password for the keystore

3. Alternative: Use a Separate Trust Store for TLS

If you want to specify a separate trust store instead of adding CA certificates to the default JKS file, configure the following parameters in your application.yaml file:

serverSettings:
  webClientSettings:
    useTls: true
    trustStorePath: /path/to/truststore.jks
    trustStorePassword: <truststore-password>

Parameter Name	Description
useTls	Enables TLS for the web client communication with the Platform Service. Set to true to enable TLS.
trustStorePath	Specifies the path to the truststore file (JKS) containing trusted CA certificates used to validate the server’s certificate.
trustStorePassword	Specifies the password to unlock the truststore file.

Mutual TLS configuration

In addition to the above TLS configuration, the following settings are required to enable mutual TLS (mTLS) between GWS application and Platform Service:

Server-side configuration for GWS Platform Service

Name	Mandatory	Default Value	Description
GWS_SERVER_TLS_MUTUAL_REQUIRED	No	false	When set to true, the server requests the client to provide its certificate. Possible values: true or false.
GWS_SERVER_TLS_MUTUAL_VALIDATION	No	-	Comma-separated list of properties to be validated. Possible values: expiration, subject, host, client.
GWS_SERVER_TLS_TRUSTED_SUBJECTS	No	-	Comma-separated list of trusted subjects. An empty list (or absence of value) results in all subjects being trusted.
GWS_SERVER_TLS_TRUSTED_HOSTS	No	-	Comma-separated list of trusted hosts. An empty list (or absence of value) results in all hosts being trusted.

Important Notes for mTLS:

1. Once mutual TLS is enabled, the Platform Service requires clients to present a valid certificate.

2. Update the get_version() function in /usr/bin/gws-service-platform to use client certificate and key for the health check. For example:

RESPONSE=$(curl -XGET -skLS \
    --cert /path/to/client_cert.pem \
    --key /path/to/client_key.key \
    https://${GWS_HOST}:${GWS_PORT}${GWS_HEALTH_CHECK_URL} 2>&1)

3. Update monitoring services (e.g., Grafana) to use the HTTPS endpoint and include the client certificate and key when sending requests to the Platform Service.

Client-side (GWS 8.6) configuration

To enable mutual TLS (mTLS) for secure HTTPS communication with the Platform Service, add the following settings under the serverSettings section of your application.yaml file:

serverSettings:
  webClientSettings:   
    keyStorePath: /path/to/client-keystore.jks
    keyStorePassword: <keystore-password>
    keyManagerPassword: <keymanager-password>

Parameter name	Description
keyStorePath	Specifies the path to the keystore file that contains the client certificate and private key, used for mutual TLS (mTLS) communication with the Platform Service.
keyStorePassword	Specifies the password to unlock the keystore file.
keyManagerPassword	Specifies the password to access the key material (private key) within the keystore.

Note: Ensure that the keystore contains a valid client certificate that is trusted by the Platform Service.