1 Overview
- 1.1 Requires Feature Flag Enablement on your Org
- 1.2 Policy Execution Order
2 Prerequisites
3 Settings
4 Certificate Type Examples
5 Supported Scenarios
6 First-time Configuration Workflow
7 Troubleshooting
8 Certificate Chain Examples

Overview

Use this policy with APIM Proxies to ensure that inbound endpoints are verified by TLS certificates during API processing. When a client calls an API with this policy, the server and client exchange TLS certificates. With the Inbound TLS policy, SnapLogic is the server.

This policy differs from most other policies in that the initial configuration determines the workflow, rather than the Settings dialog.

Requires Feature Flag Enablement on your Org

Contact your CSM to enable this feature. The following feature flag must be enabled for this policy on your Org:
“com.snaplogic.utils.APIMClientCertificateValidator.ALLOWED_SNAPLEX_FOR_MTLS": "[<list of runtime path id or use all for enabling for all ground plexes>]”

Examples
For 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\"]",

Policy Execution Order

The client provides their certificate during TLS/SSL authentication.
The policy checks for the certificates in the HTTP request. If present, the policy verifies that the certificate is present in the SnapLogic truststore and is not expired.
The Inbound TLS policy then allows the request to be processed.

All expression enabled fields take expressions from the SnapLogic Expression Language and the API Policy Manager functions.

Prerequisites

This policy only supports Groundplexes (self-managed Snaplexes).
Root admin on the host machine for the Groundplex node are required.
You must configure your own truststore.
Once the truststore is set, a restart of the Groundplex node (JCC) is required.
Truststores have to be set in each Groundplex node (JCC) by the user.

Settings

Parameter Name	Description	Default Value	Example

Parameter Name

Description

Default Value

Example

Label

Required. The name for the API policy.

Inbound TLS

Inbound TLS

When this policy should be applied

An expression enabled field that determines the condition to be fulfilled for the API policy to execute.

For example, if the value in this field is request.method == "POST", the API policy is executed only if the request method is a POST.

N/A

request.method == "POST"

Status

Specifies whether the API policy is enabled or disabled.

Enabled

Disabled

Certificate Type Examples

The following table provides examples of the certificate types:

	Certificate Type	Signed By	Is the Certificate a CA?	Does the certificate live in truststore?

	Certificate Type	Signed By	Is the Certificate a CA?	Does the certificate live in truststore?
1	Leaf	Intermediate certificate	No	No
2	Intermediate	Root certificate	Yes	No
3	Root	Self-signed certificate	Yes	Yes

Supported Scenarios

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

Input	Accepted	Reason

Input	Accepted	Reason
Leaf	No	Not in the truststore - we cannot build a chain from only the leaf.
Intermediate	No	Is a CA and not in the truststore
Root	Yes	In the truststore
Leaf-intermediate chain	Yes	The end user certificate is not a CA and we 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 is not in the truststore.
Leaf-intermediate-root chain	Yes	Valid chain with root in the truststore

First-time Configuration Workflow

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

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 pass file called jcc-servertrust.pass with a unique password:
For example, if you want to use 'changeit' as the password, then:
echo -n ‘changeit’ > jcc-servertrust.pass
Create an empty JCEKS truststore named jcc-servertrust.jks by running the following commands:
1. 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
2. Delete the dummy certificate entry in this truststore by running the following command:
  /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 by running the following command:
  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 in the key/truststore. This is defined by the policy owner, and the policy uses this alias to refer to a particular certificate. Do not use jetty as alias because it conflicts with the server keys used in the Snaplex.
2. Add the PCKS file in the truststore by running the following command:
Move the truststore and pass file to /etc/snaplogic by running the following command:
Restart the Groundplex JCC node by running the following command:

Troubleshooting

If you can not verify a valid connection, check for the following:

The certificate or certificate chain is present
The certificate chain is valid - each certificate in the chain has to be signed by the next certificate in the chain.
For example, if you provide a chain of three certificates certa->certb->certc then certa should be signed by certb and certb should be signed by certc.
None of the certificates in the chain is expired
Check the /etc/snaplogic folder on a Linux machine or /etc on a Windows machine for the key files.
Use the following naming convention for your truststore.
For example:
- If the key file in the /etc folder is named jcc-serverkeys.jks, then use the following names:
  - Truststore: jcc-servertrust.jks
  - Pass file: jcc-servertrust.pass
- If the key file key file in the /etc folder is named serverkeys.jks, then use the following names:
  - Truststore: servertrust.jks
  - Pass file: servertrust.pass
Be sure to restart the JCC node after configuration.

Certificate Chain Examples

You can have n number of intermediate certificates.

For example:

Root signs intermediate 1
Intermediate 1 signs intermediate 2
Intermediate 2 signs intermediate 3

This continues until…

Intermediate n signs leaf

As long as the end user certificate is not a CA, the policy accepts the request. If an API caller provide a CA as an end user certificate, then the certificate should be present in the truststore.