Search code examples
oauth-2.0discord

Give role to users that are added to a guild through guilds.join scope, Discord OAuth2.0


I want to integrate Discord's OAuth2.0 on my website so I can add users to my guild and give them a specific role.

I've searched Developer Portal Documentation but I didn't find anything.


Solution

  • The Discord Oauth implementation is described at https://discordapp.com/developers/docs/topics/oauth2. You'll probably want to read it together with RFC 6749 to get an overview of how Oauth works in general.

    You will need not only a Discord "application", but this application also needs a bot account which you have already joined to the guild (that is, "server") in question. The bot needs to have CREATE_INSTANT_INVITE and MANAGE_ROLES permissions in the guild, and the bot account needs to have a role that is higher in the role list than the role it will be assigning to users. On the other hand you don't need to have the bot actually connected to the Discord websocket gateway for this.

    The steps will be:

    1. Send the user to an authorization URL at Discord, with query parameters identifying your application, and requesting the identify and guilds.join scopes.

    2. If the user identifies correctly and approves the request, his browser will eventually be redirected to an URL of your choosing that points to your backend server. This URL is given as a parameter in the authorization URL, and must be whitelisted in your app control panel in advance.

      Common mistake: The redirect URL must match the whitelisted URL character for character. It's not enough that one is a prefix of the other.

      When you receive the redirect it's time to check (using session cookies or whatever you're using) that the user is someone you want to add to your guild,

    3. Discord adds certain query strings to the redirect URL that your backend can use to construct a token exchange request to Discord. In this request you provide the secret credentials for your app together with a cryptographic code from the redirection, and you get a bearer token that represents the combination of your app and the rights you've got from that particular user.

      Common mistake: One of the parameters to the token exchange request must be the original redirect URL once again. This must be identical to the one you used in step 1. It cannot be a different URL even if the different URL is also whitelisted for your app!

      Common mistake: Most of the parameters to the token exchange request go in the POST body, which must be encoded in application/x-www-form-urlencoded format. Sometimes people use HTTP stacks that default to encoding their data as JSON, and are confused it doesn't work. It will not work to put application/x-www-form-urlencoded in a Content-Type header if the actual data you send are serialized as JSON.

      Caveat: You may find code examples floating around that attempt to give the token exchange parameters as query parameters in the URL rather than in a POST body. Discord used to accept this, but doesn't anymore.

    4. Make a Get current user request authenticated with the bearer token you got in the token exchange. This gives you the Discord ID of the user you're talking to.

    5. You now have the information you need to make an Add guild member request, which is authenticated with your fixed bot token and contains the bearer token for the user in the PUT body, which must be JSON this time. You can use the optional roles parameter to set the roles the new member will start out with.

      Common mistake: This should be a PUT request, not POST.

    I'm assuming you hardcode (or configure) the IDs of the guild you're managing and the role you're assigning.

    Beware that even though Discord IDs are (64-bit) integers, they should be serialized as strings in JSON bodies, for compatibility with languages such as JavaScript that don't support so large integers natively.

    (Also see https://discordapp.com/developers/docs/reference#authentication for details of the authentication for steps 4 and 5).