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.
$ npm install @envoy/passport-envoyBefore 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.
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": "johndoe@example.com"
}
}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.
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("/");
}
);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.
Copyright (c) 2020-present Envoy <https://envoy.com>