Document how to access the "state" parameter

[dafortune]

Basically using passReqToCallback or providing an explicit option for that, the user might not be aware of the inheritance on the lib.

[joshcanhelp]

Working out some of the details of how this works but, in the meantime, I figure I would provide some information for anyone looking.

The state option can be set to true or false when configuring the strategy. This library will respect either value but will set it to true if it's not passed in (see this comment for more details).

You can access the value that Passport generates in the config callback by using passReqToCallback like so:

var auth0Strategy = new Auth0Strategy(
  {
    domain: process.env.AUTH0_DOMAIN,
    clientID: process.env.AUTH0_CLIENT_ID,
    clientSecret: process.env.AUTH0_CLIENT_SECRET,
    callbackURL: process.env.AUTH0_CALLBACK_URL,
    passReqToCallback: true
  },
  function (req, accessToken, refreshToken, extraParams, profile, done) {
    //
    // State value is in req.query.state ...
    //
    return done(null, profile);
  }
);
passport.use(auth0Strategy);

... or in the auth callback route with no changes to the config callback:

router.get(
  '/auth/callback',
  function (req, res, next) {
    //
    // State value is in req.query.state ...
    //
    passport.authenticate('auth0', function (err, user, info) {
      // ...
    })(req, res, next);
  }
);

Passport itself allows for a custom value to be passed to the authorize endpoint if you set state to false in the configuration options and use a custom value when calling passport.authenticate() like so:

router.get('/login', (req, res, next) => {
  const authenticator = passport.authenticate('auth0', { scope: 'openid email profile', state: 'custom' })
  authenticator(req, res, next)
});

Big thanks to this issue for explanation on how this works.

The problem here is that state is now false so this value is not checked against a stored version. It's up to the implementer to store the state value they want to use in session and then check during the callback. If this is not implemented, then state is not checked and codes can be just handed to the auth callback for checking (invoking the RFP that this parameter is meant to provide).

So, as it stands, to use a custom state, you need to store it before redirecting to the authorize endpoint and then check it in the auth callback route.

Marking this as closed for now, will update the README if anything useful comes out of the issue linked above.