--- title: Secure network connections description: This topic explains how to secure incoming connections and ports. As a general precaution in production environments, avoid communication over insecure HTTP. component: pingidm version: 8.1 page_id: pingidm:security-guide:chap-connections canonical_url: https://docs.pingidentity.com/pingidm/8.1/security-guide/chap-connections.html keywords: ["Security", "TLS/SSL", "Network", "Connections", "Ports", "CA-Signed Certificates", "Proxy Server", "Load Balancer"] section_ids: security-ssl: Use TLS/SSL security-https: Restrict REST access to the HTTPS port security-urls: Protect sensitive REST interface URLs strict-transport-security: Enable HTTP Strict-Transport-Security mixed-client-auth: Enable mixed client authentication sni-host-check: Disable SNI host check max-payload-size: Restrict the HTTP payload size clustering-load-balancer: Deploy securely behind a load balancer configuring-proxy: Connect to IDM through a proxy server csrf-filter: Protect against Cross-Site Request Forgery --- # Secure network connections This topic explains how to secure incoming connections and ports. As a general precaution in production environments, avoid communication over insecure HTTP. ## Use TLS/SSL Use TLS/SSL to access IDM, ideally with mutual authentication so that only trusted systems can invoke each other. TLS/SSL protects data on the network. Mutual authentication with strong certificates, imported into the truststore and keystore of each application, provides a level of confidence for trusting application access. ## Restrict REST access to the HTTPS port | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | In IDM 8.0, `jetty.xml` is no longer supported.When serving SSL requests, Jetty 12 checks that the incoming host header matches the server certificate's subject and returns a `400 Bad Request` error on a mismatch. If you're upgrading to IDM 8.0, you must ensure your IDM server certificate subject matches the host name used by your deployment.Learn more in [Jetty 12 support](../release-notes/whats-new.html#jetty_12_support). | In a production environment, you should restrict REST access to a secure port: Delete the following embedded Jetty web server configuration in your project's `conf/webserver.listener-http.json` file that includes the `openidm.port.http` property: ```json { "enabled": { "$bool": "&{openidm.http.enabled|true}" }, "port": { "$int": "&{openidm.port.http|8080}" } } ``` Use a certificate to secure REST access over HTTPS. You can use self-signed certificates in a test environment. In production, all certificates should be signed by a certificate authority (CA). The examples in this guide assume a CA-signed certificate named `ca-cert.pem`. ## Protect sensitive REST interface URLs Anything attached to the router is accessible with the default policy, including the repository. If you do not need such access, deny it in the authorization policy to reduce the attack surface. In addition, you can deny direct HTTP access to system objects in production, particularly access to `action`. As a rule of thumb, do not expose anything that is not used in production. For an example that shows how to protect sensitive URLs, refer to [Configure Access Control in access.json](../auth-guide/authorization-and-roles.html#access-json). ## Enable HTTP Strict-Transport-Security | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | In IDM 8.0, `jetty.xml` is no longer supported.When serving SSL requests, Jetty 12 checks that the incoming host header matches the server certificate's subject and returns a `400 Bad Request` error on a mismatch. If you're upgrading to IDM 8.0, you must ensure your IDM server certificate subject matches the host name used by your deployment.Learn more in [Jetty 12 support](../release-notes/whats-new.html#jetty_12_support). | [HTTP Strict-Transport-Security (HSTS)](https://www.tunetheweb.com/security/http-security-headers/hsts/) is a web security policy that forces browsers to make secure HTTPS connections to specified web applications. HSTS can protect websites against passive eavesdropper and active man-in-the-middle attacks. Enabled by default, IDM provides an HSTS configuration for the following configuration files: * `webserver.listener-https.json` * `webserver.listener-mutualAuth.json` To enable HSTS for additional `webserver.listener-*.json` configurations: 1. Set `secure` to `true`. 2. Set `sslCertAlias` to the certificate alias you want the server to present. The following example shows this configuration in `conf/webserver.listener-https.json`: ```json { "enabled": { "$bool": "&{openidm.https.enabled|true}" }, "port": { "$int": "&{openidm.port.https|8443}" }, "secure": true, "sslCertAlias": "&{openidm.https.keystore.cer.alias|openidm-localhost}" } ``` ## Enable mixed client authentication You can configure IDM to request a client certificate during the TLS handshake without requiring it. This allows a single port to support mixed traffic, accepting connections from clients that present a valid certificate (mTLS) as well as those that don't (standard TLS). To enable this configuration, set `wantClientAuth` to `true` and `mutualAuth` to `false` in the appropriate `conf/webserver.listener-*.json` file. The following example configures this behavior for the HTTPS listener: ```json { "enabled": { "$bool": "&{openidm.https.enabled|true}" }, "port": { "$int": "&{openidm.port.https|8443}" }, "secure": true, "mutualAuth": false, "wantClientAuth": true, "sslCertAlias": "&{openidm.https.keystore.cer.alias|openidm-localhost}" } ``` ## Disable SNI host check By default, IDM uses Jetty Server Name Indication (SNI) to check the requested hostname against the certificate. This feature is implemented with Jetty's `SecureRequestCustomizer`. Although not recommended for security reasons, disabling this check might be necessary in certain proxy configurations, such as SSL pass-through. To disable SNI host checking, add the `"sniHostCheckEnabled": false` property to your project's applicable `conf/webserver.listener-*.json` files. Example `sniHostCheckEnabled` ```json { "enabled": { "$bool": "&{openidm.https.enabled|true}" }, "port": { "$int": "&{openidm.port.https|8443}" }, "secure": true, "sslCertAlias": "&{openidm.https.keystore.cer.alias|openidm-localhost}", "sniHostCheckEnabled": false } ``` Learn more in the [Jetty 12 documentation](https://javadoc.jetty.org/jetty-12/org/eclipse/jetty/server/SecureRequestCustomizer.html#setSniHostCheck%28boolean%29). ## Restrict the HTTP payload size Restricting the size of HTTP payloads can protect the server against large payload HTTP DDoS attacks. IDM includes a servlet filter that limits the size of an incoming HTTP request payload, and returns a `413 Request Entity Too Large` response when the maximum payload size is exceeded. By default, the maximum payload size is 5MB. You can configure the maximum size in your project's `conf/servletfilter-payload.json` file. That file has the following structure by default: ```json { "classPathURLs" : [ ], "systemProperties" : { }, "requestAttributes" : { }, "scriptExtensions" : { }, "initParams" : { "maxRequestSizeInMegabytes" : 5 }, "urlPatterns" : [ "/*" ], "filterClass" : "org.forgerock.openidm.jetty.LargePayloadServletFilter" } ``` Change the value of the `maxRequestSizeInMegabytes` property to set a different maximum HTTP payload size. The remaining properties in this file are described in [Additional servlet filters](../install-guide/register-servlet-filters.html). ## Deploy securely behind a load balancer | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | In IDM 8.0, `jetty.xml` is no longer supported.When serving SSL requests, Jetty 12 checks that the incoming host header matches the server certificate's subject and returns a `400 Bad Request` error on a mismatch. If you're upgrading to IDM 8.0, you must ensure your IDM server certificate subject matches the host name used by your deployment.Learn more in [Jetty 12 support](../release-notes/whats-new.html#jetty_12_support). | If you're deploying IDM behind a system such as a load balancer, firewall, or a reverse proxy, you must set the `"proxyLoadBalancerConnection"` field to `true` in your `conf/webserver.listener-*.json` configurations: ```json { "enabled": { "$bool": "&{openidm.http.enabled|true}" }, "port": { "$int": "&{openidm.port.http|8080}" }, "proxyLoadBalancerConnection": true } ``` ## Connect to IDM through a proxy server If you're connecting to IDM through a proxy server, you must set the `"proxyLoadBalancerConnection"` field to `true` in your `conf/webserver.listener-*.json` configurations: ```json { "enabled": { "$bool": "&{openidm.http.enabled|true}" }, "port": { "$int": "&{openidm.port.http|8080}" }, "proxyLoadBalancerConnection": true } ``` ## Protect against Cross-Site Request Forgery IDM provides a filter to protect against [Cross-Site Request Forgery (CSRF)](https://owasp.org/www-community/attacks/csrf). The filter is disabled by default. To enable it, set the following property in `resolver/boot.properties`: ```properties openidm.csrfFilter.enabled=true ``` The filter requires the client to send a CSRF cookie (`X-CSRF-Token`) on every request. By default, this cookie is the JWT session cookie (`session-jwt`), obtained on authentication. If your client uses a different cookie for authentication, set the name of that cookie in the following property in `resolver/boot.properties`: ```properties openidm.csrfFilter.authCookieName=session-jwt ``` If there are HTTP request paths that the CSRF filter should always allow, set these paths as comma-separated values of the `openidm.csrfFilter.pathWhitelistCSV` property in `resolver/boot.properties`. For example: ```properties openidm.csrfFilter.pathWhitelistCSV=/openidm/example,/openidm/my-project ```