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

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.

  1. 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
  2. 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
  3. 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:

  4. Move the truststore and pass file to /etc/snaplogic by running the following command:

  5. 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.