Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Working with Bundler
      • Rails Support
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Add-ons
  • All Add-ons
  • wwwhisper
wwwhisper

This add-on is operated by Jan Wrobel

Restrict access to your app without passwords

wwwhisper

Last updated October 09, 2019

Table of Contents

  • Provisioning the add-on
  • Using with Ruby on Rails or other Rack based applications
  • Using with Node.js
  • Removing the add-on
  • Support
  • Final remarks

wwwhisper is an add-on for authorizing access to Node.js, Ruby on Rails and other Ruby Rack based applications on Heroku.

The add-on provides a web interface to specify emails of users that are allowed to access your web application. Each visitor is presented with a login prompt and asked to enter his or her email address. A link with an access token is sent to the entered email. The link is valid for 30 minutes and for a single successful login. If the visitor owns an email address that is allowed to access the application, opening the link grants access and establishes a browser session that is valid for 30 days or until the access is revoked.

Integration with wwwhisper service is provided via Ruby Rack and Node.js Connect middleware. This minimizes integration cost. There is no need to modify your application code and explicitly call the wwwhisper API.

Provisioning the add-on

wwwhisper can be attached to a Heroku application via the CLI.

$ heroku addons:create wwwhisper:solo[or team or plus] [--admin=your_email]

--admin is an optional parameter that specifies who should be allowed to initially access the application. If --admin is not given, or if the add-on is provisioned via Heroku web UI, your Heroku application owner email is used. Later 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 and will contain the URL to communicate with the wwwhisper service. This can be confirmed using the heroku config:get command.

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

Using with Ruby on Rails or other Rack based applications

All Ruby applications need to add the following entry into their Gemfile.

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

And then update application dependencies with bundler.

$ bundle install

Enabling wwwhisper middleware for a Rails application

For a Rails application put 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 take a look at a commit that enabled 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 take a look at a commit that enabled wwwhisper for a Sinatra application.

Rack middleware order

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

RAILS_ENV=production; heroku local:run rake middleware

wwwhisper by default inserts an iframe to HTML responses. The iframe contains an email of a currently logged in user and a logout button. If Rack is configured to compress responses, compression middleware should be put before wwwhisper, otherwise the iframe won’t be inserted.

Push the configuration and test the authorization

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

Visit https://yourapp-name.herokuapp.com/ you should be presented with a login page. Sign-in with your email. Visit https://yourapp-name.herokuapp.com/wwwhisper/admin/ to specify which locations can be accessed by which visitors and which (if any) should be open to everyone.

Local setup

Disable wwwhisper locally

It is usually convenient to disable wwwhisper authorization for a local development environment. If your application uses a separate config file for development (for example config/environments/development.rb in case of Rails) you don’t need to do anything, 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

Use wwwhisper locally

To use the wwwhisper service locally, use the wwwhisper admin to allow logins from a local address. Go to the Site settings menu and add the local address (for example http://localhost:8080) to the list of allowed addresses. Next, copy the WWWHISPER_URL variable from the Heroku config to your local config.

If you use Heroku Local, execute.

$ echo WWWHISPER_URL=`heroku config:get WWWHISPER_URL` >> .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Otherwise, execute.

$ export WWWHISPER_URL=`heroku config:get WWWHISPER_URL`

Using with Node.js

wwwhisper works with Node.js applications that use Express or Connect frameworks. To configure the add-on, 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 iframe into HTML responses use.
app.use(wwwhisper(false));

Make sure wwwhisper middleware is put before any middleware that produces sensitive responses. You can take a look at a commit that enabled wwwhisper for an Express application.

Push the configuration and test the authorization

Follow these steps.

Local setup

Follow these steps.

Removing the add-on

wwwhisper can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:destroy wwwhisper

Support

wwwhisper support and runtime issues should be submitted via one of the Heroku Support channels. Please CC help@wwwhisper.io.

Any non-support related issues or product feedback is welcome at help@wwwhisper.io. Issues and feature requests can be also reported via github.

Final remarks

  • It is recommended to access wwwhisper protected applications over HTTPS.
  • wwwhisper authorizes access to content served by your Heroku application. If you put sensitive content on external servers that do not require authorization (for example public Amazon S3 bucket), wwwhisper won’t be able to restrict access to such content.
  • wwwhisper is open source, see the project repository for a detailed explanation of how it works.

Keep reading

  • All Add-ons

Feedback

Log in to submit feedback.

Ziggeo Yahoo BOSS API

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences