Documentation

You are viewing the documentation for the 3.0.3 release. The latest stable release series is 3.0.x.

§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 and production configuration 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" 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:

§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
import javax.inject.Inject
import javax.net.ssl._

import play.core.ApplicationProvider
import play.server.api._

class CustomSSLEngineProvider @Inject() (appProvider: ApplicationProvider) extends SSLEngineProvider {
  override def createSSLEngine(): SSLEngine = {
    // change it to your custom implementation
    sslContext().createSSLEngine
  }

  override def sslContext(): SSLContext = {
    // change it to your custom implementation
    SSLContext.getDefault
  }
}
Java
import java.security.NoSuchAlgorithmException;
import javax.inject.Inject;
import javax.net.ssl.*;
import play.server.ApplicationProvider;
import play.server.SSLEngineProvider;

public class CustomSSLEngineProvider implements SSLEngineProvider {

  private final ApplicationProvider applicationProvider;

  @Inject
  public CustomSSLEngineProvider(ApplicationProvider applicationProvider) {
    this.applicationProvider = applicationProvider;
  }

  @Override
  public SSLEngine createSSLEngine() {
    return sslContext().createSSLEngine();
  }

  @Override
  public SSLContext sslContext() {
    try {
      // Change it to your custom implementation, possibly using ApplicationProvider.
      return SSLContext.getDefault();
    } catch (NoSuchAlgorithmException e) {
      throw new RuntimeException(e);
    }
  }
}

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

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:

Next: Deploying to a cloud service