Skip to content

05. Authentication Setup

Jump to bottom
Derick M edited this page Aug 10, 2023 · 8 revisions

General Notes

Strategies

  • The strategies array accepts an unlimited number of Discord, Telegram, and Local strategies. Though if you add more than 1 of each, you will need to explore custom strategies.

Area Restrictions

  • areaRestrictions accepts an unlimited number of items as well with the following format:
{
  "areaRestrictions": [
    {
      "roles": ["discord_role_1", "telegram_group_1", "none", "local"],
      "areas": ["newyork", "downtown"]
    }
  ]
},
  • Areas must align with the names provided in your areas.json file
  • All roles in the array will be limited to all of the areas provided
  • "none" indicates that users who are NOT logged in will have those area restrictions
  • "local" refers to users that are logging in with a local auth strategy

Always Enabled Perms

  • If no strategies are in the strategies array or all of them are disabled, ALL perms that are enabled will automatically be added to this array for convenience.
  • Any perms in this array will be visible to users that aren't logged in - and added to those that are logged in, even if their role isn't specifically in the roles array for that perm

When Testing / Making Changes to Authentication

  • You must either change your session secret in your config to reset all the sessions OR truncate the session table
  • You can also manually clear the cookies in your browser if you are just testing for yourself
  • Permissions are set into the cookie upon login, so they must be reset whenever changes are made

Discord

Discord based authentication strategy that enables access filtering by role and user IDs.

Enable Developer Mode in the Discord Client

This enables you to see the ability to copy and paste channel, role, and user IDs when right clicking/long pressing

  1. Open up your Discord client
  2. Go to Preferences => Advanced
  3. Toggle Developer Mode

Create and Invite your Bot

This creates the bot necessary to allow ReactMap to communicate with Discord

  1. Go to the Discord Dev website

  2. Click New Application

  3. Give your application a name

  4. Navigate to Bot from the sidebar

  5. Click Add Bot, then Yes, do it!

  6. Add the Gateway Intents

Gateway Intents

  1. Click Reset Token, then Yes, do it!
  2. Click the new Copy button, save this for later!

Bot Token

  1. Navigate to OAuth2 from the sidebar
  2. Copy the CLIENT ID and save this for later
  3. Click Reset Secret, then Yes, do it!
  4. Click the new Copy button, save this for later!
  5. Click Add Redirect
  6. Type https://www.yourmapurl.com/auth/discord/callback

OAuth2 Section

  1. Navigate to URL Generator from the sidebar
  2. Under scopes select bot
  3. Under permissions select admin for easy setup, feel free to narrow this down once comfortable
  4. Copy the Generated URL at the bottom

Screen Shot 2022-05-28 at 1 21 25 PM

  1. Paste that URL into a new browser tab, select your server under Add To Server, then click Continue
  2. Click Authorize

Add to ReactMap

  1. Copy and paste the Discord example from the Config Explanation
  2. Set enabled to true
  3. If you want to add a log channel, right click on the channel that you want to use in your Discord client and click Copy ID, paste this ID into the logChannelId, make sure it has " around it!
  4. Paste your botToken, clientId, and clientSecret from the above steps into their respective positions, make sure to have "s around the values!
  5. Set the redirectUri to the same one that you set in step 14 in the above section

In each of these sections below you can add an unlimited number of IDs to each of the respective arrays

  1. Add your Discord server to the allowedGuilds section. Right click on your server's icon in your Discord client and click Copy ID. If your ID is 907337201044582452, your allowed guilds will look like this:
{
  "allowedGuilds": ["907337201044582452"]
}
  1. Add your Discord ID to "allowedUsers", same as above, if your Discord ID is 232732575494307841, your allowed users will look like this:
{
  "allowedUsers": ["232732575494307841"]
}

This gives you admin access to everything.

  1. In the Authentication => Perms section of the config, you can now put specific role IDs in each of the roles arrays. Like allowedGuilds and allowedUsers, every role must have " around it.
{
  "pokemon": {
    "enabled": true,
    "roles": ["232732575494307842", "232732575494307843"]
  },
}

Important Notes

  • Your Discord bot must have a higher role than the roles you put in each of the roles arrays
  • In order to use the log channel, your bot must have access to send messages in that channel

Telegram

Credit to: Ninjasoturi Telegram based authentication strategy that enables access filtering by user IDs and group IDs (not channels) the user is a member of.

Creating the bot

  1. To create a Telegram bot you need to open a chat with BotFather and hit start. Then send it a message /newbot and follow the instructions.
  2. When the bot is created, you receive an API key. Save it for later and keep it safe!
  3. Send /mybots to BotFather.
  4. Select your bot and navigate to Bot settings -> Domain -> Set domain.
  5. Send your map's domain e.g. https://map.mydomain.com, http://www.mymap.com. The domain doesn't accept custom ports or localhost!
  6. The bot is all set and ready to be invited to your group.

In /mybots menu you can use the Edit Bot -menu to customize the name, description and profile picture of the bot. After you've invited your bot to all the chats you need and converted them to supergroups (explained below), you might also want to navigate to Bot Settings -> Group Privacy and turn that on.

Creating a group

  1. If your community doesn't already have a group or you wish to further filter users who get access to your map, create a new group from your Telegram client's menu -> New Group.
  2. Give the group a name and hit next.
  3. Use the search bar to search for @RawDataBot and the bot you just created using its username, select them and hit create.
  4. The RawDataBot will send info in the group about every action performed.
  5. From the first message you'll notice that the chat's type is group. We want to change that to supergroup because that changes the group ID and we don't want to have that happen later by accident.
  6. When in the group's chat window, click the group's title and from the popup click the button located in top right to edit the group.
  7. Set Chat history for new members to visible and save the changes.
  8. RawDataBot will now post two messages detailing the changes made. From there you'll find your new group ID (starting with -1001....) that you'll use in ReactMap's config.
  9. You can now have RawDataBot tell you your personal user ID by sending any message to the chat. Or if you need to find some other user's ID, have them send a message or invite them to the group. User ID's are positive numbers with no set length.
  10. You can now remove RawDataBot and set the chat history back to invisible for new members if you wish.
  11. If your bot's group privacy is on, it will leave the group. Before inviting it back you first need to turn group privacy off from BotFather's menu.

Configure ReactMap

  1. Copy and paste the Telegram example from the Config Explanation.
  2. Set enabled to true.
  3. Copy your Bot API key you received from BotFather into botToken.
  4. Copy all the group IDs you use for authenticating into groups. The array can hold unlimited ammount of IDs and they must have " around each of them.
{
  "groups": ["-1001222333444", "-1001555666777"]
}
  1. In the Authentication => Perms section of the config, you can now put specific group or user IDs in each of the roles arrays. Like groups, very role must have " around it.
{
  "pokemon": {
    "enabled": true,
    "roles": ["-1001222333444", "1234567"]
  },
}
  1. Add your Telegram bot's username (without @) into telegramBotName located in the customRoutes object. More details about the location of this variable in Config Explanation.
{
  "map": {
    "customRoutes": {
      "telegramBotName": "MyAuthentication_bot"
    }
  }
}

Local

  • This authentication method is very barebones and is generally meant to be used alongside Discord, Telegram, or as a base for a custom authentication method.
  • Enabling it allows users to register and login on the same page client side
  • When used alongside Discord or Telegram, if a user "Links" them from the profile page on the map, it saves the allowed perms from each in the database, allowing them to login with Discord/Telegram once, then using a username/password after that
  • In the roles arrays, you must add "local" if you want users that aren't linking a Discord/Telegram to have access to those perms

Custom

ReactMap supports any number of custom authentication methods. This wiki will cover a very basic setup of how to get started but this should only be considered if you're somewhat comfortable with coding/JavaScript.

Example Situation:

  • Your map is served on multiple domains for separate areas and has multiple Discord servers. Since each bot can only have one redirectUri in ReactMap, you have to setup a second Discord bot.
  • Server 1 URL is https://map1.my_map_url.com
  • Server 2 URL is https://map2.my_map_url.com

Setup Instructions

Create the file

  1. Copy the original Discord strategy - cp server/src/strategies/discord.js server/src/strategies/map2_discord.js
  2. You can make edits to this new, git friendly file if you would like, it but you shouldn't have to to get started

Edit the strategies section in your config

  1. Add a second Discord entry in your strategies array in the config
  2. Set the name property to map2_discord (needs to match the new filename in step 1)
  3. Create a second Discord bot and fill out all of the information in the config, note that your redirect url will change:
  • from /auth/discord/callback
  • to /auth/map2_discord/callback

Edit the multiDomain section in your config

More information about this will be covered in the Multi Domain Setup section of this wiki

  1. At a minimum, it needs to look like this though:
  "multiDomains": [
    {
      "domain": "map2.my_map_url.com",
      "customRoutes": {
        "discordAuthUrl": "/auth/map2_discord/callback",
      }
    }
  ],

Now when users from https://map2.your_map_url.com login, they will use the correct bot and be redirected to the correct subdomain afterwards.

Clone this wiki locally