PingIDM 8.0.0

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.0.16 checks that the incoming host header matches the server certificate’s subject and will return 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.0.16 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:

{
  "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.

Enable HTTP Strict-Transport-Security

In IDM 8.0, jetty.xml is no longer supported.

When serving SSL requests, Jetty 12.0.16 checks that the incoming host header matches the server certificate’s subject and will return 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.0.16 support.

HTTP Strict-Transport-Security (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:

{
  "enabled": {
    "$bool": "&{openidm.https.enabled|true}"
  },
  "port": {
    "$int": "&{openidm.port.https|8443}"
  },
  "secure": true,
  "sslCertAlias": "&{openidm.https.keystore.cer.alias|openidm-localhost}"
}

Learn more about HSTS .

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:

{
    "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.

Deploy securely behind a load balancer

In IDM 8.0, jetty.xml is no longer supported.

When serving SSL requests, Jetty 12.0.16 checks that the incoming host header matches the server certificate’s subject and will return 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.0.16 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:

{
  "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:

{
 "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). The filter is disabled by default. To enable it, set the following property in resolver/boot.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:

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:

openidm.csrfFilter.pathWhitelistCSV=/openidm/example,/openidm/my-project