Configure Groundplex truststores

To use the Inbound TLS rule, your CSM must enable a feature flag and an admin with root permissions must install truststores on the Groundplex nodes.

Note: Requires feature flag enablement per environment

Contact your CSM to enable this feature. The following feature flag must be enabled for this rule per environment:


"com.snaplogic.utils.APIMClientCertificateValidator.ALLOWED_SNAPLEX_FOR_MTLS": "[<list of runtime path id or use all for enabling for all ground plexes>]"

For example, one Snaplex:


"com.snaplogic.utils.APIMClientCertificateValidator.ALLOWED_SNAPLEX_FOR_MTLS": "["{org_name}/rt/{snaplex_location}/{snaplex_environment}"]"

For all Snaplexes:


"com.snaplogic.utils.APIMClientCertificateValidator.ALLOWED_SNAPLEX_FOR_MTLS": "["all"]"

First-time configuration workflow on Linux or Windows hosts

Prerequisite: The feature flag for the rule is enabled for your Org.

Note: The following procedure is written for a Linux machine. For Linux-based Groundplexes, use /etc/snaplogic as the target folder for the truststore and .pass file. For Windows-based Groundplexes, use /etc as the target folder for the truststore and .pass file.

Create a truststore password file called jcc-servertrust.pass with a unique password:
```
echo -n ‘changeit’ > jcc-servertrust.pass
```

Create an empty JCEKS truststore named jcc-servertrust.jks:

Create a truststore with a dummy certificate entry:

/opt/snaplogic/pkgs/jdk-11.0.17+8-jre/bin/keytool -genkey -keyalg RSA -alias dummy -keystore jcc-servertrust.jks -storetype JCEKS -storepass $(sudo cat ./jcc-servertrust.pass) -keypass changeit

Delete the dummy certificate entry:

/opt/snaplogic/pkgs/jdk-11.0.17+8-jre/bin/keytool -delete -alias dummy -storepass $(sudo cat ./jcc-servertrust.pass) -keystore jcc-servertrust.jks

Add certificates to the truststore:
1. Create a PKCS file from the root certificate and key:
```
sudo openssl pkcs12 -inkey <certificate-key> -in <certificate-pem> -export -out sl-ca-chain.p12 -name <certificate-alias>
```
  Where:
  - <certificate-key> is the private key of the certificate
  - <certificate-pem> is the public key of the certificate
  - <certificate-alias> is the alias of the certificate. Do not use jetty as alias because it conflicts with the server keys used in the Snaplex.
2. Add the PKCS file in the truststore:
```
sudo /opt/snaplogic/pkgs/jdk-11.0.17+8-jre/bin/keytool -importkeystore -srckeystore sl-ca-chain.p12 -srcstoretype PKCS12 -srcstorepass $(sudo cat ./jcc-servertrust.pass) -destkeystore ./jcc-servertrust.jks -deststoretype JCEKS -deststorepass $(sudo cat ./jcc-servertrust.pass)
```
Move the truststore and pass file to /etc/snaplogic on each node:
```
sudo mv jcc-servertrust.* /etc/snaplogic
```
Restart each Groundplex JCC node:
```
sudo /opt/snaplogic/bin/jcc.sh restart
```

For an example, refer to Inbound TLS Configuration.

Supported certificate chains

The following table provides the scenarios and outcomes for each type of certificate and certificate chain:


Input	Accepted	Reason
Leaf	No	Not in the truststore - the system can't build a chain from only a leaf.
Intermediate	No	This is a certificate authority (CA), not a truststore.
Root	Yes	A valid truststore.
Leaf-intermediate chain	Yes	The end user certificate isn't a CA and the system can build a chain from it since the intermediate is signed by `root`.
Intermediate-root chain	No	Intermediate is a CA and is presented as an end user certificate and isn't in the truststore.
Leaf-intermediate-root chain	Yes	Valid chain with root in the truststore.

For example certificate chains, refer to Inbound TLS Certificate chain examples..

Troubleshooting

Check that a valid certificate or certificate chain is present in the request.
For a valid certificate chain, each certificate in the chain should be signed by the next.
None of the certificates in the chain is expired.
Check /etc/snaplogic (Linux) or /etc (Windows) for the key files.
Use the following naming convention for your truststore:
- If the key file is jcc-serverkeys.jks, use jcc-servertrust.jks and jcc-servertrust.pass.
- If the key file is serverkeys.jks, use servertrust.jks and servertrust.pass.
Restart the JCC node after configuration.