Skip to content

Latest commit

 

History

History
66 lines (40 loc) · 4.17 KB

ConfiguringHttps.md

File metadata and controls

66 lines (40 loc) · 4.17 KB
Raw

Configuring HTTPS

Play can be configured to serve HTTPS. To enable this, simply tell Play which port to listen to using the https.port system property. For example:

./bin/your-app -Dhttps.port=9443

Providing configuration

HTTPS configuration can either be supplied using system properties or in application.conf. For more details see the [[configuration|Configuration]] and [[production configuration|ProductionConfiguration]] pages.

SSL Certificates

SSL Certificates from a keystore

By default, Play will generate itself a self-signed certificate, however typically this will not be suitable for serving a website. Play uses Java key stores to configure SSL certificates and keys.

Please be aware that binding an HTTPS port with a self-signed certificate in Java 17 and Java 21 may lead to issues. For more details on this matter, refer to [["Generation of Self-Signed Certificates Fails in Java 17 and Java 21"|Migration29#Generation-of-Self-Signed-Certificates-Fails-in-Java-17-and-Java-21]] in the Play 2.9 Migration Guide.

Signing authorities often provide instructions on how to create a Java keystore (typically with reference to Tomcat configuration). The official Oracle documentation on how to generate keystores using the JDK keytool utility can be found here. There is also an example in the Generating X.509 Certificates section.

Having created your keystore, the following configuration properties can be used to configure Play to use it:

  • play.server.https.keyStore.path - The path to the keystore containing the private key and certificate, if not provided generates a keystore for you
  • play.server.https.keyStore.type - The key store type, defaults to JKS
  • play.server.https.keyStore.password - The password, defaults to a blank password
  • play.server.https.keyStore.algorithm - The key store algorithm, defaults to the platforms default algorithm

SSL Certificates from a custom SSL Engine

Another alternative to configure the SSL certificates is to provide a custom SSLEngine. This is also useful in cases where a customized SSLEngine is required, such as in the case of client authentication. In Java, an implementation must be provided for play.server.SSLEngineProvider and in Scala, an implementation must be provided for play.server.api.SSLEngineProvider. For example:

Scala : @scalaexample

Java : @javaexample

Having created an implementation for play.server.SSLEngineProvider or play.server.api.SSLEngineProvider, the following system property configures Play to use it:

  • play.server.https.engineProvider - The path to the class implementing play.server.SSLEngineProvider or play.server.api.SSLEngineProvider:

Example:

./bin/your-app -Dhttps.port=9443 -Dplay.server.https.engineProvider=mypackage.CustomSSLEngineProvider

Turning HTTP off

To disable binding on the HTTP port, set the http.port system property to be disabled, eg:

./bin/your-app -Dhttp.port=disabled -Dhttps.port=9443 -Dplay.server.https.keyStore.path=/path/to/keystore -Dplay.server.https.keyStore.password=changeme

Production usage of HTTPS

If you intend to use Play for TLS termination layer, please note the following settings:

  • SSLParameters.setUseCipherSuiteorder() - Reorders cipher suite order to the server's preference.
  • -Djdk.tls.ephemeralDHKeySize=2048 - Increases the key size in a DH key exchange.
  • -Djdk.tls.rejectClientInitiatedRenegotiation=true - Rejects client renegotiation.