Inbound TLS
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 |
---|---|---|---|
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? | |
---|---|---|---|---|
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 |
---|---|---|
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 |
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: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 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:
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.
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 certificatescerta->certb->certc
thencerta
should be signed bycertb
andcertb
should be signed bycertc
.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 namedjcc-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 namedserverkeys.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.
Have feedback? Email documentation@snaplogic.com | Ask a question in the SnapLogic Community
© 2017-2024 SnapLogic, Inc.