This add-on is operated by Jan Wrobel
Plug and play access control for your app.
Last updated September 18, 2023
Table of Contents
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’s email address 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, which remains valid for 30 days or until the access is revoked.
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:solo[or team or plus] [--admin=your_email]
--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.
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
https://your-app-id.herokuapp.com/, where you will encounter a
login prompt. Sign-in using your email address. Visit wwwhisper
admin dashboard at
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
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.
This will destroy all access control settings and cannot be undone!
$ 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.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
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
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
If you use Heroku Local to start a local server, execute the following command in the application directory:
$ echo WWWHISPER_DISABLE=1 >> .env
$ 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
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
Submit wwwhisper support and runtime issues through one of the Heroku Support channels. Please CC firstname.lastname@example.org.
For non-support-related issues or feedback, reach out to email@example.com. You can also report issues and feature requests on GitHub.
- 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.