passport-discord

Passport strategy for authentication with Discord through the OAuth 2.0 API.

This package is forked from @qgisk/passport-discord. Compared to all original packages, this removes Discord user connections & guilds fetching on login. The goal is to reduce sporadically occurring rate limit errors.

If Discord connections or guilds are still needed, they can be directly fetched from Discord. Advantage here is also to get more recent data.

Installation

npm install @soerenmetje/passport-discord --save

Usage

The usage is similar to all original packages. Therefore, it can serve as a drop-in replacement.

Configure Strategy

The Discord authentication strategy authenticates users via a Discord user account and OAuth 2.0 token(s). A Discord API client ID, secret and redirect URL must be supplied when using this strategy. The strategy also requires a verify callback, which receives the access token and an optional refresh token, as well as a profile which contains the authenticated Discord user's profile. The verify callback must also call cb providing a user to complete the authentication.

import { Strategy } from "@soerenmetje/passport-discord";
//const Strategy = require('@soerenmetje/passport-discord').Strategy;
import passport from "passport";
//const passport = require('passport')

const scopes = ["identify", "email", "connections", "guilds", "guilds.join"];
const prompt = "consent";

passport.serializeUser(function (user, done) {
  done(null, user);
});
passport.deserializeUser(function (obj, done) {
  done(null, obj);
});

passport.use(new Strategy({
    clientID: 'id',
    clientSecret: 'secret',
    callbackURL: 'callbackURL',
    scope: scopes,
    prompt: prompt,
},
(accessToken, refreshToken, profile, cb) => {
    // Find or create user in DB
    User.findOrCreate({ discordId: profile.id }, (err, user) => {
        return cb(err, user);
    });
}));

Authentication Requests

Use passport.authenticate(), and specify the 'discord' strategy to authenticate requests.

For example, as a route middleware in an Express app:

app.get('/auth/discord', passport.authenticate('discord'));
app.get('/auth/discord/callback', passport.authenticate('discord', {
  failureRedirect: '/',
  successRedirect: '/profile'
}));

Bot Authentication

If using the bot scope, the permissions option can be set to indicate specific permissions your bot needs on the server (permission codes):

app.get("/auth/discord", passport.authenticate("discord", { permissions: 66321471 }));

You can also determine the default guild by passing in a Guild Discord ID and toggle the appearance of the guilds dropdown,

app.get("/auth/discord", passport.authenticate("discord", { disable_guild_select: true, guild_id: 'id' }));

Extra: Refresh Token Usage

In some use cases where the profile may be fetched more than once or you want to keep the user authenticated, refresh tokens may wish to be used. A package such as passport-oauth2-refresh can assist in doing this.

npm install passport-oauth2-refresh --save

import passport from "passport";
//const passport = require('passport')
import { Strategy } from "@soerenmetje/passport-discord";
//const Strategy = require('@soerenmetje/passport-discord').Strategy
import refresh from "passport-oauth2-refresh";
//const refresh = require('passport-oauth2-refresh');

const discordStrategy = new Strategy({
    clientID: 'id',
    clientSecret: 'secret',
    callbackURL: 'callbackURL'
  },
  (accessToken, refreshToken, profile, cb) => {
    profile.refreshToken = refreshToken; // store this for later use
    // Find or create user in DB
    User.findOrCreate({ discordId: profile.id }, (err, user) => {
        return cb(err, user);
    });
});

passport.use(discordStrategy);
refresh.use(discordStrategy);

Then you need some event / point in time in your application when it is suitable to refresh the access token. Refreshing can look as follows:

refresh.requestNewAccessToken('discord', profile.refreshToken, (err, accessToken, refreshToken) => {
    if (err)
        throw Error(err);

    profile.accessToken = accessToken;  // Store this
});

Examples

The examples can be found in the /examples directory.

• Express
• vite-plugin-ssr (This one is with Vue but can be easily adapted)

Change Log

By this Repository

• Removed Discord user connections & guilds fetching on login.

By https://github.com/QGIsK/passport-discord

• Added a separate error when being rate limited by Discord. (Note: This does not kill the auth process, when being rate limited on scopes. The 'scope' will simply be empty)
• Rewrite of both original repositories in a more 'modern' fashion.

By https://github.com/tonestrike/passport-discord

• Ability to configure disable_guild_select, and guild_id parameters when authenticating bots
• Fixed bug causing callback to be called twice when get guilds request failed
• Fixed bug causing the response to be sent twice on error

Original Package: https://github.com/nicholastay/passport-discord

• No longer maintained

Disclaimer

No warranty for anything. Before using this strategy, it is strongly recommended that you read through the official docs page here, especially about the scopes and understand how the auth works.

Credits

• QGIsK - Author of the rewrite
• tonestrike - Author of intermediate fork
• Nicolas Tay - Original author of passport-discord package
• Jared Hanson -Author of Passport

License

Licensed under the MIT license.