This add-on is operated by Jan Wrobel

Plug and play access control for your app.

Last updated September 26, 2024

wwwhisper is a language and framework-independent add-on for authorizing access to web applications on Heroku.

The add-on provides a web interface for specifying the email addresses of users allowed to access your web application. Each visitor is presented with a login prompt and asked to enter their email address: If the visitor is permitted to access the application, a link containing an access token is sent to the entered email. The link remains valid for 30 minutes, opening the link grants access and establishes a browser session. If, at any time, you revoke access from the user, the existing user sessions are invalidated, the user is logged out and no longer able to access the application.

Integration with the wwwhisper service is provided via a buildpack which can be added or removed without any changes to the application code.

Provisioning the add-on

You can attach wwwhisper to a Heroku application using the CLI with the following command:

$ heroku addons:create wwwhisper:team-3 [-- --admin=your_email]

team-3 specifies the plan to enable. Other plan options are team-10, team-20, plus-50, plus-100, plus-200, and enterprise-750.

The --admin parameter is optional and specifies the initial user who can access the application. If --admin is omitted or if the add-on is provisioned through the Heroku web dashboard, your Heroku application owner’s email is used. Subsequently, you can use the wwwhisper admin site to grant access to others. Note that since Heroku CLI v9, the --admin parameter needs to be proceeded by the -- separator.

Once the add-on has been added, a WWWHISPER_URL setting will be available in the app configuration, containing the wwwhisper service URL. You can confirm this using the heroku config:get command:

$ heroku config:get WWWHISPER_URL
https://user:password@domain

Enabling the wwwhisper buildpack

The wwwhisper buildpack is responsible for authenticating and authorizing requests. Authorized requests are forwarded to your application, while unauthorized ones are rejected with 401 or 403 HTTP errors. To enable the buildpack, run:

$ heroku buildpacks:add auth/wwwhisper

No changes are needed in your application code, but you must push a new version of your application to compile the buildpack:

# Such empty commit is needed only if your Git repository does not have
# any local, not yet deployed changes:
$ git commit --allow-empty -m "Enable wwwhisper buildpack."

# Replace 'heroku' with the name of your Heroku remote, and 'main' with
# the name of the branch to deploy to Heroku:
$ git push heroku main

Visit https://your-app-id.herokuapp.com/, where you will encounter a login prompt. Sign-in using your email address. Visit wwwhisper admin dashboard at https://your-app-id.herokuapp.com/wwwhisper/admin/ to specify which locations can be accessed by which visitors and which (if any) should be open to everyone:

Using Heroku Single Sign-On (SSO) to log in

You can also log in to your app with a single click directly from the Heroku Dashboard. Simply click the wwwhisper link located in the Installed add-ons section of the dashboard:

Disabling the wwwhisper overlay

By default, wwwhisper adds an overlay in the lower right corner of HTML responses. The overlay displays the email of the currently logged-in user and a logout button. To disable the overlay, execute:

$ heroku config:set WWWHISPER_NO_OVERLAY=1

Removing the add-on

wwwhisper can be removed via the CLI.

$ heroku buildpacks:remove auth/wwwhisper
$ heroku addons:destroy wwwhisper
$ git commit --allow-empty -m "Disable wwwhisper buildpack."
# Replace 'heroku' with the name of your Heroku remote and 'main' with
# the name of the branch to deploy to Heroku:
$ git push heroku main

Buildpack alternatives for Ruby or Node.js applications

The wwwhisper buildpack is the simplest and recommended way to use the wwwhisper add-on. As an alternative, integration with the wwwhisper service is possible through Ruby Rack and Node.js Connect middleware. The following sections provide details on this alternative setup, which you can skip if you opt for the buildpack.

Using with Ruby on Rails or other Rack based applications

For Ruby applications that do not use the wwwhisper buildpack, add the following entry to your Gemfile:

gem 'rack-wwwhisper', '~> 1.0'

Then, update your application dependencies with bundler:

$ bundle install

Enabling wwwhisper middleware for a Rails application

For a Rails application, place the following line at the end of config/environments/production.rb.

config.middleware.insert 0, Rack::WWWhisper

The line makes wwwhisper the first middleware in the Rack middleware chain. You can refer to this commit as an example of enabling wwwhisper for a Rails-based Typo blog.

Enabling wwwhisper middleware for other Rack based application

For other Rack based applications, add the following two lines to the config.ru.

require 'rack/wwwhisper'
use Rack::WWWhisper

You can refer to this commit as an example of enabling wwwhisper for a Sinatra application.

Rack middleware order

The order of Rack middleware matters. Authorization should be done early, before any middleware that generates sensitive responses is invoked. Rails allows to check middleware order with a command.

RAILS_ENV=production; heroku local:run rake middleware

Push the configuration and test the authorization

$ git commit -m "Enable wwwhisper authorization" -a
$ git push heroku master

Local setup

For a local development environment, it is usually convenient to disable wwwhisper authorization. If your application uses a separate config file for development (e.g., config/environments/development.rb in the case of Rails) you do not need to take any action, otherwise, you need to set WWWHISPER_DISABLE=1 environment variable.

If you use Heroku Local to start a local server, execute the following command in the application directory:

$ echo WWWHISPER_DISABLE=1 >> .env

Otherwise, execute:

$ export WWWHISPER_DISABLE=1

Using with Node.js

wwwhisper provides middleware for Node.js applications that use Express or Connect frameworks. To configure the middleware, add the following line into the dependencies section of the package.json:

"connect-wwwhisper": "*",

Next, add the following lines to the application main source file.

var wwwhisper = require('connect-wwwhisper');
// app holds a reference to Express or Connect framework, it
// may be named differently in your source file.
app.use(wwwhisper());

// Alternatively, if you don't want wwwhisper to insert
// a logout overlay into HTML responses, use the following:
app.use(wwwhisper(false));

Make sure that the wwwhisper middleware is placed before any middleware that produces sensitive responses. You can refer to this commit as an example of enabling wwwhisper for an Express application.

Push the configuration and test the authorization

Follow these steps.

Local setup

Follow these steps.

Support

Submit wwwhisper support and runtime issues through one of the Heroku Support channels or directly to help@wwwhisper.io.

For non-support-related issues, feature requests or feedback, reach out to help@wwwhisper.io.

Final remarks

• It is recommended to access wwwhisper protected applications over HTTPS.
• wwwhisper authorizes access to content served by your Heroku application. If you host sensitive content on external servers that do not require authorization (e.g., a public Amazon S3 bucket), wwwhisper will not be able to restrict access to such content.