h1. ReverseProxy module for Play!

h2. What is ReverseProxy?

ReverseProxy allows developers to configure web applications to automatically switch between the HTTP and HTTPS protocols per page when used behind a front end Reverse-Proxy server such as Apache, Nginx or Lighttpd. Configuration is done in Controllers using annotations.

h2. Requirements

A Reverse-Proxy server configured
For SSL, a certificate and its key
A Play! app

h2. Configuration

Set the following properties in conf/application.conf

bc. reverse_proxy.http.address=127.0.0.1 reverse_proxy.http.port=80 reverse_proxy.https.port=443

reverse_proxy.enable - For enabling or disabling the switching between the Play-App and the Reverse-Proxy.
reverse_proxy.http.address - The Reverse-Proxy address.
reverse_proxy.http.port - The Reverse-Proxy HTTP listening port.
reverse_proxy.https.port - The Reverse-Proxy HTTPS listening port.

h2. HTTPS support

In order to communicate between Reverse-Proxy server and Play built-in server either by HTTP or HTTPS protocol, Play needs Java keystore or simple cert and key files and since you have to create a Certificate and its Key for the Reverse-Proxy server, you can use the same ones.

To start an HTTPS connector for your application, just declare the https.port configuration property in your application.conf file:

bc. http.port=9000 https.port=9443

http.port - The built-in server HTTP port, it must be configured explicitly
https.port - The built-in server HTTPS port, it must be configured explicitly

h2. Disabling ReverseProxy module

If you wish or have to disable this module by any reason without removing it from the dependencies, just set the following property in you application.conf file:

bc. reverse_proxy.enable=false

In this case, if you have configured http.port and https.port, the process for switching process between HTTP and HTTPS schemes will use those configured ports. If you only have configured http.port, this will be the only port used, and won't be any switching process between HTTP and HTTPS schemes.

h2. Configuration Exception

If the above properties configuration are not correct, the module wil throw an configure exception and will stop the application.

h2. Certificates

You need to put your certificates in the conf directory. Play supports X509 certificates and keystore certificates. The X509 certificates must be named as follow: host.cert for the certificate and host.key for the key. If you are using keystore, then, by default it should be named certificate.jks.

If you are using X509 certificates, then the following parameters can be configured through your application.conf:

bc. # X509 certificates certificate.key.file=conf/host.key certificate.file=conf/host.cert

In case your key file is password protected

certificate.password=secret trustmanager.algorithm=JKS

In case your are using keystore:

bc. keystore.algorithm=JKS keystore.password=secret keystore.file=conf/certificate.jks

Note that the values above are the default ones. If you use these default values, they are not required to be explicitly in application.conf file, however, if your certificate doesn't use the default names, you must add your custom values.

bc. certificate.key.file=conf/localhost.key certificate.file=conf/localhost.cert

You can generate self signed certificates using openssl:

Generate a Private Key

<pre><code>openssl genrsa -des3 -out host.key 1024</code></pre>

Generate a CSR (Certificate Signing Request)

<pre><code>openssl req -new -key host.key -out host.csr</code></pre>

Remove Passphrase from Key

<pre><code>cp host.key host.key.org openssl rsa -in host.key.org -out host.key</code></pre>

Generating a Self-Signed Certificate

<pre><code>openssl x509 -req -days 365 -in host.csr -signkey host.key -out host.crt</code></pre>

Installing the Private Key and Certificate

<pre><code>Depends on the Reverse-Proxy server.</code></pre>

Configuring SSL Enabled Virtual Hosts

<pre><code>Depends on the Reverse-Proxy server.</code></pre>

If you are using the java keystore mechanism, then the following properties can be configured in your application.conf:

bc. # Keystore ssl.KeyManagerFactory.algorithm=SunX509 trustmanager.algorithm=JKS keystore.password=secret keystore.file=certificate.jks

The values above are the default values.

You can generate self signed certificates using Java Keytool:

bc. keytool -genkey -keyalg RSA -alias selfsigned -keystore certificate.jks -storepass secret -validity 360 -keysize 1024

h3. Self Signed Certificates Warning

In case you don't know, when you use a Self Signed Certificate, the Web Browsers always warns about it. If you plan to use your app in a Production Environment, then you should buy a certificate from a Certificate Authority like VeriSign, Thawte, Geotrust, GoDaddy, Comodo.

h2. Usage

Add this module to your dependecy.yml file

h3. Controllers

There are two annotation for forcing the communication with a Reverse-Proxy server:

@SwitchScheme is strictly for Actions and has two optional values: ** type = SchemeType.HTTP (default value) or SchemeType.HTTPS, for using either HTTP or HTTPS protocol. ** keepUrl = true or false (default value), for storing the ReferredUrl into a cookie. ** <pre><code> public class ControllerA extends Controller { @SwitchScheme public static void actionTwo() { // This action will use HTTP (default type) } @SwitchScheme(type = SchemeType.HTTP) public static void actionTwo() { // This action will use HTTP (explicit type) } @SwitchScheme(type = SchemeType.HTTPS) public static void actionThree() { // This action will use HTTPS (explicit type) } } </code></pre>
@GlobalSwitchScheme is strictly for Controllers and has one optional value: ** type = SchemeType.HTTP (default value) or SchemeType.HTTPS, for using either HTTP or HTTPS protocol. ** <pre><code> @GlobalSwitchScheme public class ControllerA extends Controller { public static void actionOne() { // This action will use HTTP (global default type) } @SwitchScheme public static void actionTwo() { // This action will use HTTP (default type) } @SwitchScheme(type = SchemeType.HTTP) public static void actionThree() { // This action will use HTTP (explicit type) } @SwitchScheme(type = SchemeType.HTTPS) public static void actionFour() { // This action will use HTTPS (explicit type) } // Any other action from this controller will use HTTP (global default type) } --- @GlobalSwitchScheme(type = SchemeType.HTTP) public class ControllerB extends Controller { public static void actionOne() { // This action will use HTTP (global explicit type) } @SwitchScheme public static void actionTwo() { // This action will use HTTP (default type) } @SwitchScheme(type = SchemeType.HTTP) public static void actionThree() { // This action will use HTTP (explicit type) } @SwitchScheme(type = SchemeType.HTTPS) public static void actionFour() { // This action will use HTTPS (explicit type) } // Any other action from this controller will use HTTP (explicit type) } --- @GlobalSwitchScheme(type = SchemeType.HTTPS) public class ControllerB extends Controller { // All actions from this controller will use HTTPS (explicit global type) } </code></pre>

With GlobalSwitchScheme all Methods from a Controller will use the specified or default SchemeType value, unless some of its methods are annotated with SwitchScheme, in which case, those method will override the global SchemeType value.

You shall annotate a method that requires authentication/authorization as:

bc. @SwitchScheme(type = SchemeType.HTTP, keepUrl = true) public satic void restrictedMethod(){ ... }

In this way, a cookie is created for storing the REFERRED_URL and your app shall redirect to a authentication view (e.g., login); when the app validates a user is authentic, the app shall redirect to the restrictedMethod route (URI Pattern).

h3. @Interceptor

If you are going to use interceptors it is suggested to decouple the controller part from the interceptor part and annotate the Interceptor Class with @Interceptor, so that when the plugin enhances the controllers, skips the interceptors

See SecureController and SecureInterceptor for clarification, both of them included in this module.

h3. Invoking Actions

An Action from another Action may be INVOKED in one of the following ways:

By regular Java call, i.e., Controller.action()
By reverse routing, i.e., UrlUtility.redirectByReverseRouting("Controller.action") -> Invoke GET /action Controller.action
By render, i.e., render("@action") -> renders views/Controller/action.html

bc. public class ControllerA extends Controller { public static void actionOne() { ControllerA.actionTwo(); } public static void actionTwo(){ // Do logic... // Invoked from actionOne render() } }

public class ControllerA extends Controller { public static void actionOne() { ControllerA.actionTwo(); } - // Let's supposed this action uses HTTPS public static void actionTwo(){ // Do logic... // Invoked from actionOne render() } }

Remember an Action must be public static void

h4. Invoking an Action from another Action of the same Controller by Render

Reverseproxy

Install / Use

README