This add-on is operated by Jan Wrobel

Plug and play access control for your app.

Last updated June 26, 2025

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 preceded 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 verify 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.

Heroku Common Runtime and Cedar Private Spaces

Cedar apps use classic Heroku buildpacks. To enable the classic wwwhisper buildpack, run:

$ heroku buildpacks:add auth/wwwhisper

No changes are needed to your application code and Procfile, 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

Heroku new generation Fir Private Spaces

Apps running in Fir Private spaces use new Cloud Native Buildpack (CNB) format. Such buildpacks are enabled via a project.toml configuration file.

Add the following section to your application’s project.toml file to enable the buildpack:

[[io.buildpacks.group]]
id = "wwwhisper/wwwhisper-cnb"

Next, modify your Procfile to start wwwhisper authorization proxy in front of your web app process. Enclose your existing application launch command in single quotes “ and add wwwhisper-auth command in front of it. For example, a Procfile that starts Python fastapi server looks like this:

web: wwwhisper-auth 'fastapi run --port $PORT --host ::'

Note that Procfile modification is needed only in the Fir Private Spaces; Cedar stack apps should use their original, unmodified Procfile.

See sample project.toml and Procfile for a reference.

Commit the changes:

$ git add project.toml Procfile
$ git commit -m "Enable wwwhisper buildpack"
$ git push heroku main # or master

Verifying setup

Visit https://your-app-id.herokuapp.com/, where you should 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.

Note that these alternatives are not recommended for apps running in Heroku Private Spaces. The wwwhisper-buildpack caches sessions and access control rules, enabling fast request authorization regardless of the geographic location of a Private Space. Ruby and Node.js middleware solutions do not utilize such caching.

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 main

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

The add-on 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.