@envoy/passport-envoy

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

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

Install

$ npm install @envoy/passport-envoy

Usage

Create an Application

Before using passport-envoy, you must register an application with Envoy by reaching out to the Envoy partnership team. Your application will be issued a client ID and client secret, which need to be provided to the strategy. You will also need to configure a redirect URI which matches the route in your application.

Configure Strategy

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

const { Strategy } = require("@envoy/passport-envoy");

passport.use(
  new Strategy({
    clientID: ENVOY_CLIENT_ID,
    clientSecret: ENVOY_CLIENT_SECRET,
    callbackURL: "http://www.example.com/auth/envoy/callback",
  })
);

profile is the result of querying the Envoy GraphQL API with the following query.

query User {
  me {
    id
    name: formattedName
    email
  }
}

What gets yielded to the verify callback has the following shape.

{
  "me": {
    "id": "12345",
    "name": "John Doe",
    "email": "[email protected]"
  }
}

You can customize the GraphQL query by passing in a profileQuery option to the strategy.

passport.use(
  new Strategy({
    clientID: ENVOY_CLIENT_ID,
    clientSecret: ENVOY_CLIENT_SECRET,
    callbackURL: "http://www.example.com/auth/envoy/callback",
    profileQuery: `
      query User {
        me {
          id
          name: formattedName
          email
          employee {
            id
          }
          organization {
            id
            name
          }
        }
      }
    `,
  })
);

If you are querying more than the me schema, don't forget to pass in a custom verify callback, or you'll only see data under me.

Authenticate Requests

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

For example, as route middleware in an Express application:

app.get("/auth/envoy", passport.authenticate("envoy", { scope: ["profile"] }));

app.get(
  "/auth/envoy/callback",
  passport.authenticate("envoy", { failureRedirect: "/login" }),
  function (req, res) {
    // Successful authentication, redirect home.
    res.redirect("/");
  }
);

Examples

Developers using the popular Express web framework can refer to an example as a starting point for their own web applications. The example shows how to authenticate users using Facebook. However, because both Facebook and Envoy use OAuth 2.0, the code is similar. Simply replace references to Facebook with corresponding references to Envoy.

License

The MIT License

Copyright (c) 2020-present Envoy <https://envoy.com>