npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

passport-webmaker

v1.1.1

Published

Webmaker authentication strategy for passport.js

Downloads

1

Readme

:rocket: passport-webmaker

Passport strategy for authenticating with Webmaker using the OAuth 2.0 API.

This module lets you authenticate using Webmaker in your Node.js applications. By plugging into Passport, Webmaker authentication can be easily and unobtrusively integrated into any application or framework that supports Connect-style middleware, including Express.

Install

$ npm install passport-webmaker

Usage

Create an Application

Before using passport-webmaker, you must register your application and generate appropriate credentials.

If you want to register your application with Mozilla's production/staging instances of id.webmaker.org then send an email to devops@mozillafoundation.org with the information detailed and outlined here. Note that registration requests can be denied at any time, for any reason and that these requests are typically not granted to applications outside the relevant scope of Mozilla's products and services.

Alternatively, if you are running your own instance of id.webmaker.org you can generate these tokens yourself, although this process is currently not documented and outside the scope of this project. Upon registration by either method your application will be issued a clientID and clientSecret which will need to be provided to the strategy as explained below. You will also need to configure a redirect URI that matches the route in your application.

Configure Strategy

The Webmaker authentication strategy authenticates users using a Webmaker account and OAuth 2.0 tokens. The client ID and secret obtained when creating an application are supplied as options when creating the strategy. The strategy also requires a verify callback, which receives the access token and optional refresh token, as well as profile which contains the authenticated user's Webmaker profile. The verify callback must call done providing a user to complete authentication.

passport.use(new WebmakerStrategy({
    clientID: WEBMAKER_CLIENT_ID,
    clientSecret: WEBMAKER_CLIENT_SECRET,
    state: true
  },
  function(accessToken, refreshToken, profile, done) {
    User.findOrCreate({ id: profile.id }, function (err, user) {
      return done(err, user);
    });
  }
 ));

Authenticate Requests

Use passport.authenticate(), specifying the 'webmaker' strategy, to authenticate requests.

For example, as route middleware in an Express application:

app.get('/auth/webmaker', passport.authenticate('webmaker'));

app.get('/auth/webmaker/callback',
    passport.authenticate('webmaker', { failureRedirect: '/login', successfulRedirect: '/'}));

FAQ

These are some answers to the most frequently asked questions, if you have additional questions feel free to submit an issue ticket and tag whomever is the current project maintainer as well.

How do you ask for additional permissions/information?

You can request additional permissions by appending parameters to the scopes option in passport.authenticate().

app.get('/auth/webmaker',
  passport.authenticate('webmaker', { scopes: ['user', 'email'] }));

Note: Your parameter must be called scopes (plural) and not scope (singular), otherwise this will throw an error.

What is the structure of the user information returned?

We follow the standard convention for normalizing profiles as detailed by passport.js.

{
  "provider":"webmaker",
  "id":1022,
  "displayName":"ryan",
  "locale":"en-US",
  "emails":[
    {
      "value":"hello@myemail.com"
    }
  ],
  "photos":[
    {
      "value":"https://example.com/ryan/webmaker-avatar-200x200.png"
    }
  ]
}
How can you change what instance of id.webmaker.org is being used?

By default all authentication will go through https://id.webmaker.org however, it's also possible to point passport-webmaker at your own instance of id.webmaker.org. This is especially helpful if maybe you want to debug on a developmental/staging server, like we do here at Mozilla on a regular basis.

Below we append three parameters to the options object to be used when creating the strategy. They are: authorizationURL, tokenURL and profileURL. Changing these three URLs is all you need to change your id instance.

passport.use(new WebmakerStrategy({
    clientID: WEBMAKER_CLIENT_ID,
    clientSecret: WEBMAKER_CLIENT_SECRET,
    state: true,
    authorizationURL: "https://id.mofostaging.net/login/oauth/authorize",
    tokenURL: "https://id.mofostaging.net/login/oauth/access_token",
    profileURL: "https://id.mofostaging.net/user"
  },
  function(accessToken, refreshToken, profile, done) {
    User.findOrCreate({ id: profile.id }, function (err, user) {
      return done(err, user);
    });
  }
 ));
How can I change the login flow used by passport-webmaker?

You can tell passport-webmaker to use the signup flow vs. the signin flow by assigning the string value to the optional action parameter when calling passport.authenticate(). The default is signin.

app.get('/auth/webmaker',
  passport.authenticate('webmaker', { scopes: ['user', 'email'], action: "signup" }));
What is "Error: OAuth 2.0 authentication requires session support when using state."?

passport-webmaker requires persistent login session support in order to be used properly. It is a requirement of using passport.js's internal implementation of state which is a randomly generated string used to prevent CSRF-like attacks and other man-in-the-middle intrusions. Often times errors like these occur when your web app doesn't support sessions, or they aren't being configured properly with passport.js.

Check out the passport.js documentation for information on configuring login sessions.

Misc. potential errors and their causes

Error: "{"statusCode":400,"error":"Bad Request","message":"child "state" fails because ["state" is required]","validation":{"source":"query","keys":["state"]}}"

Cause: You have either forgotten to set the state parameter when initializing your strategy, or have disabled it by setting it to false.

Error: The refreshToken parameter is undefined.

Cause: This is perfectly normal, id doesn't support this type of request. It's just a place holder.

Credits

  • Jared Hanson for his incredible work on passport.js, great documentation and more.
    • Some code snippets and documentation layout were also heavily inspired by his work on his own passport modules!
  • MoFo DevOps for providing guidance and technical support where necessary, as well as insight on the OAuth flow.