Manage TLS Policies

Learn how to use NGINX Management Suite API Connectivity Manager to secure communications by applying TLS policies.


This documentation applies to NGINX Management Suite API Connectivity Manager 1.1.0 and later.

Overview

In NGINX Management Suite API Connectivity Manager (ACM), you can apply global policies to API Gateway and Developer Portal clusters to ensure your organization’s security requirements are enforced. When you add policies at the environment level, they will apply to all proxies hosted within that environment.

The types of communication you can apply TLS policies to includes:

  • ingress traffic to an API or Dev Portal proxy;
  • communications between an API proxy and a backend API service; and
  • communications between the API Connectivity Manager management plane and the Dev Portal data plane.

Before You Begin

Complete the following prerequisites before proceeding with this guide:

  • ACM is installed, licensed, and running.
  • You have one or more Environments with API Gateway or Dev Portal clusters.

How to Access the User Interface

This guide contains instructions for completing tasks by using the NGINX Management Suite API Connectivity Manager user interface (UI).

To access the UI, navigate to the FQDN for your NGINX Management Suite host and log in. Then, select “API Connectivity Manager” on the Launchpad menu.

How to Access the REST API

You can use tools such as curl or Postman to interact with the NGINX Management Suite API Connectivity Manager REST API. The API URL follows the format https://<NMS_FQDN>/api/acm/<API_VERSION>.

Note:
When making API calls by using curl, Postman, or any other tool, you need to provide your authentication information with each call. Refer to the API Overview for more information about authentication options.

Secure Ingress Traffic

Take the steps in this section to secure the traffic coming into your API Proxies.

Add a TLS Listener

  1. In the ACM user interface, go to Workspaces > Environments > <your environment>, where “your environment” is the Environment that contains the Dev Portal Cluster.
  2. Select Edit Advanced Config from the Actions menu for the desired Dev Portal Cluster.
  3. On the Listeners tab, select Add Listener.
  4. Provide the desired Protocol and Port (for example, 443) and select the TLS checkbox.

"listeners": [
    {
        "transportProtocol": "HTTP",
        "port": 443,
        "tlsEnabled": true,
        "ipv6": false
    }

Add the TLS Inbound Policy

  1. Select the Global Policies tab.

  2. Select Add Policy from the Actions menu for the TLS Inbound policy.

  3. On the TLS Inbound policy page, provide the requested information.

    • Protocols: The TLS and SSL protocols that will be used for securing communication.
    • Cipher: The set of algorithms or a set of instructions/steps that helps to establish the secure connection.
    • Session Timeout: Specifies the time during which a client may reuse the session parameters.
    • Session Cache: Sets whether a session can be re-used. When off, a full negotiation is performed for every connection.
    • Session Type: Determines the cache type for re-using sessions.
    • Session Size: Sets the shared cache size.
  4. Upload a Server Certificate, Certificate Key, and CA Certificate.

    • Select the upload icon in the Server Certificate field and browse for the desired certificate on your file system.
    • Select the upload icon in the Certificate Key field and browse for the desired key file on your file system.
    • Select the upload icon in the CA Certificates field and browse for the desired Root CA certificate on your file system.
  5. (Optional) Select the Verify Client Certificate toggle and complete the configurations as appropriate.

  6. Select Add to save and add the policy.

  7. Select Save and Submit.

"policies": {
    "tls-inbound": [
        {
            "data": {
                "serverCerts": [
                    {
                        "key": {{tlsKey}},
                        "cert": {{tlsCert}}
                    }
                ],
                "trustedRootCACerts":{{caCert}}
            }
        }
    ]
}

Verify HTTPS Connection

Once the Environment configuration has been submitted and applied, the Job Status for the Environment will change to Success. You can then navigate to the Dev Portal user interface to verify that your connection is secured using HTTPS.

Secure Communications between an API Proxy and a Backend Service

Take the steps in this section to secure the communications between your Proxies and the associated API backend services. When mTLS is enabled, the API Gateway identifies itself to the backend service using an SSL client certificate.

Add the TLS Backend Policy

  1. In the ACM user interface, go to Workspaces > Environments > <your environment>, where “your environment” is the Environment that contains the API Gateway Cluster to be updated.

  2. Select Edit Advanced Config from the Actions menu for the desired API Gateway Cluster.

  3. Select the Global Policies tab, then select Add Policy from the Actions menu for the TLS Backend policy.

  4. On the TLS Backend policy page, provide the requested information.

    • Protocols: The TLS and SSL protocols that will be used for securing communication to the proxied server.
    • Cipher: The set of algorithms or a set of instructions/steps that helps to establish the secure connection to the proxied server.
    • Verify Certificate Chain Depth: Sets the verification depth in the client certificates chain.
  5. Upload a Client Certificate, Certificate Key, and CA Certificate.

    • Select the upload icon in the Client Certificate field and browse for the desired certificate on your file system.
    • Select the upload icon in the Certificate Key field and browse for the desired key file on your file system.
    • (Optional) Provide the Client ID and select the upload icon to upload a Trusted Root CA, then browse for the desired Root CA certificate on your file system.
  6. Select Add to save and add the policy.

  7. Select Save and Submit.

"policies": {
    "tls-backend": [
        { "action": {
            "cipher": "HIGH:!aNULL:!MD5",
            "protocols": [
                "TLSv1.2"
            ]
        },
            "data": {
                "trustedRootCACerts":"{{caCert}}",
                "clientCerts": [
                    {
                        "cert": "{{clientCert}}",
                        "key": "{{clientKey}}"
                        
                    }
                ]
            }
        }
    ]
}

Once the Environment configuration has been submitted and applied, the Job Status for the Environment will change to Success.

Secure Communications Between ACM and Dev Portal Hosts

Take the steps in this section to secure communications between the ACM management plane and Dev Portal hosts.

Add TLS Policies to the External Developer Portal Cluster

  1. In the ACM user interface, go to Workspaces > Environments > <your environment>, where “your environment” is the Environment that contains the Dev Portal Cluster.
  2. Add the TLS Inbound and TLS Backend policies to your Developer Portal Cluster.
  3. Save and submit your changes.

{
    "name": "{{environmentName}}",
    "functions": [
        "DEVPORTAL"
    ],
    "proxies": [
        {
            "proxyClusterName": "{{portalInstanceGName}}",
            "hostnames": [
                "{{portalEnvironmentHostname}}"
            ],
            "runtime": "PORTAL-PROXY",
            "policies": {
                "tls-inbound": [
                    {
                        "action": {
                            "cipher": "ECDH+AESGCM:ECDH+AES256:ECDH+AES128:DH+3DES:!ADH:!AECDH:!MD5",
                            "protocols": [
                                "TLSv1.2"
                            ],
                            "sessionCache": {
                                "enable": "on",
                                "size": "10M",
                                "type": "shared"
                            },
                            "sessionTimeout": "5m"
                        },
                        "data": {
                            "trustedRootCACerts": {
                                    "clientId": "clientId1",
                                    "cert": "{{}}"
                            },
                            "serverCerts": [
                                {
                                    "key": {{tlsServerKey}},
                                    "cert": {{tlsServerCert}}
                                }
                            ]
                        },
                        "metadata": {
                            "appliedOn": "inbound",
                            "context": "global",
                            "labels": [
                                "default"
                            ]
                        }
                    }
                ],
                "tls-backend": [
                    {
                        "action": {
                            "cipher": "HIGH:!aNULL:!MD5",
                            "sessionReuse": false,
                            "proxyServerName": false,
                            "protocols": [
                                "TLSv1.2"
                            ]
                        },
                        "data": {
                            "trustedRootCACerts":"{{caCert}}",
                            "clientCerts": [
                                {
                                    "key": {{tlsClientKey}},
                                    "cert": {{tlsClientCert}}
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}

Add TLS Policies to the Internal Developer Portal Cluster

  1. For the Developer Portal Internal Cluster, select Edit Advanced Config from the Actions menu.

  2. Add TLS Listener(s).

  3. Add the TLS Inbound policy.

    • Complete the fields as desired.
    • Upload the Server Certificate and Certificate Key for the Internal Dev Portal Proxy.
    • On the same TLS Inbound policy page, select the Verify Client Certificate option.
    • Provide the Certificate Authority (CA) certificates and a Client ID.
    • Select Add.
  4. Add the TLS Backend policy.

    • Complete the fields as desired.
    • Upload the Client Certificate and Certificate Key for the Internal Dev Portal Proxy.
    • Select Add.
  5. Save and submit your changes.

{
    "name": "{{environmentName}}",
    "functions": [
        "DEVPORTAL"
    ],
    "proxies": [
        {
            "proxyClusterName": "{{portalInstanceGName}}",
            "hostnames": [
                "acm.{{portalEnvironmentHostname}}"
            ],
            "runtime": "PORTAL-PROXY",
            "listeners": [
                {
                    "transportProtocol": "HTTP",
                    "port": 443,
                    "tlsEnabled": true,
                    "ipv6": false
                }
            ],
            "policies": {
                "tls-inbound": [
                    {
                        "action": {
                            "cipher": "ECDH+AESGCM:ECDH+AES256:ECDH+AES128:DH+3DES:!ADH:!AECDH:!MD5",
                            "protocols": [
                                "TLSv1.2"
                            ],
                            "sessionCache": {
                                "enable": "on",
                                "size": "10M",
                                "type": "shared"
                            },
                            "sessionTimeout": "5m",
                            "enableMTLS": {
                               "certVerify": true,
                               "certChainVerifyDepth": 2
                            }
                        },
                        "data": {
                            "serverCerts": [
                                {
                                    "key": {{tlsServerKey}},
                                    "cert": {{tlsServerCert}}
                                }
                            ],
                            "clientCerts": [
                               {
                                  "clientId": "client-1",
                                  "cert": {{caCert}},
                               }
                            ]
                        },
                        "metadata": {
                            "appliedOn": "inbound",
                            "context": "global",
                            "labels": [
                                "default"
                            ]
                        }
                    }
                ],
                "tls-backend": [
                    {
                        "action": {
                            "cipher": "HIGH:!aNULL:!MD5",
                            "sessionReuse": false,
                            "proxyServerName": false,
                            "protocols": [
                                "TLSv1.2"
                            ]
                        },
                        "data": {
                            "clientCerts": [
                                {
                                    "key": {{tlsClientKey}},
                                    "cert": {{tlsClientCert}}
                                }
                            ]
                        }
                    }
                ]
            }
        }
    ]
}

Once the Environment configuration has been submitted and applied, the Job Status for the Environment will change to Success.

Update Developer Portal Backend Configuration

Take the steps below to update the settings for the Developer Portal backend server.

  1. Edit the Dev Portal configuration file located at /etc/nginx-devportal/devportal.conf
  2. Add the location of the server and client certificates and certificate keys, as shown in the example below.
DP_CERT_FILE="/path/to/devportal-server.crt"
DP_KEY_FILE="/path/to/devportal-server.key"
DP_CLIENT_CERT_FILE="/path/to/devportal-client.crt"
DP_CLIENT_KEY_FILE="/path/to/devportal-client.key"
DP_CA_FILE="/path/to/ca.pem"
DP_INSECURE_MODE=false
  1. Adjust the permissions of each of the certificate and key files provided to ensure they are readable by the Dev Portal backend service.
  2. Restart the developer portal backend service:
sudo systemctl restart nginx-devportal

Update the nms-http Config File

Take the steps below to ensure ACM can verify the client certificates provided by the Dev Portal’s backend service.

  1. Edit the NGINX Management Suite configuration file located at /etc/nginx/conf.d/nms-http.conf.
  2. Add the location of the CA PEM file to the ssl_client_certificate directive, as shown in the example below:
ssl_certificate         /etc/nms/certs/manager-server.pem;
ssl_certificate_key     /etc/nms/certs/manager-server.key;
ssl_client_certificate  /etc/nms/certs/ca.pem;
  1. Reload the NGINX configuration:
sudo nginx -s reload