How to use it

First of all, to learn how to implement a passport strategy you can look here.

In our case, we have to do several things:

Set our introspection endpoint

If we use express then you should do something similar to this:

app.post('/oauth/introspection', [
  passport.authenticate(['passport-token-introspection'], { session: false, assignProperty: 'rs' }),
  introspection(data), // we will talk about this method later...
  server.errorHandler(),
],);

By doing this, we rest assure that introspection strategy will be used whenever this endpoint is called.

In order to call this endpoint you will have to provide some specific parameters:

token=<your-token-here>&token_type_hint=access_token&id=<server-id>&secret=<secret>

The only optional parameter is token_type_hint. You can use it to optimize your token validation in the introspection function.

Set the introspectionStrategy

passport.use(new IntrospectionStrategy(
  (id, secret, done) => {
    data.ResourceServerModel.findOneBy('id', id)
      .then(rs => {
        if (!rs || rs.secret !== secret) { return done(null, false); } // 401
        return done(null, rs);
      })
      .catch(err => { if (err) { return done(err); } });
  },
));

The anonymous function passed to the IntrospectionStrategy will be called whenever the endpoint is hit with the proper parameters and you will receive there the resource server id and the secret. You should do your verifications and check if the resource server is valid or not. Here, once the resource server existence has been validated we pass it through the middleware pipeline.

Implement the introspection function

This function will be responsible of validating the token and send a response. Here you can find some simple implementation:

function introspectionImpl(req, res, next: (args?) => any): Promise<void> {
  const rs: IResourceServer = req.rs;
  const token: string = req.body.token;
  const hint: string = req.body.token_type_hint;

  function resolve(result: boolean) {
    res.send({
      active: result,
    });
    next();
  }

  if (!token) { return next(new Error('No token passed as a parameter')); }
    // let's assume it's an access token.
    const tk = jwt.decode(token, { json: true });
    if (tk) {
      return checkAccessToken(token, rs)
        .then(result => resolve(result))
        .catch(err => { next(err); });
    } else {
      // refresh token
      return checkRefreshToken(token, rs)
        .then(result => resolve(result))
        .catch(err => { next(err); });
    }
}

I hope that you can find this useful. 😉