express-force-ssl

express-force-ssl
=================
Extremely simple middleware for requiring some or all pages
to be visited over SSL.

Installation
------------
```
$ npm install express-force-ssl
``

Configuration
=============
As of v0.3.0 there are some configuration options
-------------------------------------------------

NEW Settings Option
`javascript
app.set('forceSSLOptions', {
enable301Redirects: true,
trustXFPHeader: false,
httpsPort: 443,
sslRequiredMessage: 'SSL Required.'
});
`


enable301Redirects - Defaults to true - the normal behavior is to 301 redirect GET requests to the https version of a
website. Changing this value to false will cause even GET requests to 403 SSL Required errors.

trustXFPHeader - Defaults to false - this behavior is NEW and will be default NOT TRUST X-Forwarded-Proto which
could allow a client to spoof whether or not they were on HTTPS or not. This can be changed to true if you are
behind a proxy where you trust the X-Forwarded-Proto header.

httpsPort - Previous this value was set with app.set('httpsPort', :portNumber) which is now deprecated. This value
should now be set in the forceSSLOptions setting.

sslRequiredMessage - Defaults to SSL Required. This can be useful if you want to localize your error messages.

Per-Route SSL Settings are now possible
---------------------------------------
Settings in your forceSSLOptions configuration will act as default settings for your app. However, these values can
be overridden by setting res.locals values before the the express-force-ssl middleware is run. For example:

`javascript
app.set('forceSSLOptions', {
enable301Redirects: false
});

app.get('/', forceSSL, function (req, res) {
//this route will 403 if accessed via HTTP
return res.send('HTTPS only.');
});

function allow301 (req, res, next) {
res.locals.forceSSLOptions = {
enable301Redirects: true
};
next();
}

app.get('/allow', allow301, forceSSL, function (req, res) {
//this route will NOT 403 if accessed via HTTP
return res.send('HTTP or HTTPS');
});

`

Examples
========
Force SSL on all pages
----------------------
`javascript
var express = require('express');
var forceSSL = require('express-force-ssl');
var fs = require('fs');
var http = require('http');
var https = require('https');

var ssl_options = {
key: fs.readFileSync('./keys/private.key'),
cert: fs.readFileSync('./keys/cert.crt'),
ca: fs.readFileSync('./keys/intermediate.crt')
};

var app = express();
var server = http.createServer(app);
var secureServer = https.createServer(ssl_options, app);

app.use(express.bodyParser());
app.use(forceSSL);
app.use(app.router);

secureServer.listen(443)
server.listen(80)

`

Only certain pages SSL
----------------------
`javascript
var express = require('express');
var forceSSL = require('express-force-ssl');
var fs = require('fs');
var http = require('http');
var https = require('https');

var ssl_options = {
key: fs.readFileSync('./keys/private.key')
cert: fs.readFileSync('./keys/cert.crt')
ca: fs.readFileSync('./keys/intermediate.crt')
};

var app = express();

var server = http.createServer(app);
var secureServer = https.createServer(ssl_options, app);

app.use(express.bodyParser());
app.use(app.router);

app.get('/', somePublicFunction);
app.get('/user/:name', somePublicFunction);
app.get('/login', forceSSL, someSecureFunction);
app.get('/logout', forceSSL, someSecureFunction);

secureServer.listen(443)
server.listen(80)
`

Custom Server Port Support
--------------------------
If your server isn't listening on 80/443 respectively, you can change this pretty simply.

`javascript

var app = express();
app.set('forceSSLOptions', {
httpsPort: 8443
});

var server = http.createServer(app);
var secureServer = https.createServer(ssl_options, app);

...

secureServer.listen(443)
server.listen(80)

`

Test
----
`
npm test
`

Change Log
==========
v0.3.2 - Updated README to remove typo. Thanks @gswalden

v0.3.1 - Updated README to remove deprecated usage and fix some typos. Thanks @Alfredo-Delgado and @glennr

v0.3.0 - Added additional configuration options, ability to add per route configuration options

v0.2.13 - Bug Fix, thanks @tatepostnikoff

v0.2.12 - Bug Fix

v0.2.11 - Updated README to fix usage example typo and formatting fixes

v0.2.10 - Updated README for npmjs.com markdown changes

v0.2.9 - More modular tests.

v0.2.8 - Now sends 403 SSL Required error when HTTP method is anything but GET.
This will prevent a POST/PUT etc with data that will end up being lost in a redirect.

v0.2.7 - Additional Test cases. Added example server.

v0.2.6 - Added Tests

v0.2.5 - Bug Fix

v0.2.4 - Now also checking X-Forwarded-Proto header to determine SSL connection
Courtesy of @ronco

v0.2.3 - Update README

v0.2.2 - Redirect now gives a 301 permanent redirection HTTP Status Code
Courtesy of @tixz

v0.2.0 - Added support for ports other than 80/443 for non-secure/secure ports.
For example, if you host your non-ssl site on port 8080 and your secure site on 8443, version 0.1.x did not support it.
Now, out of the box your non-ssl site port will be recognized, and to specify a port other than 443 for your ssl port
you just have to add a setting in your express config like so:
Update, this method of setting httpsPort is deprecated as of v 0.3.0

``javascript
app.set('httpsPort', 8443);
```
and the plugin will check for it and use it. Defaults to 443 of course.

v0.1.1 - Bug fix
Courtesy of @timshadel