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.

REVIEWERS: The following discusses a "feature flag" but looks more like a property. Why are we documenting what the CSM needs to do, do we expect the customer to tell the CSM which value to use? Why can't we just tell them to provide the CSM the value that the CSM needs to apply to the feature flag?

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.