Bolt-js: Document using OAuth with an instance of ExpressReceiver

[mwbrooks]

Description

Original reference: https://github.com/slackapi/bolt-js/pull/711#issuecomment-745693232

A common use-case that we've experienced is that developers needing to use OAuth with an instance of ExpressReceiver. This may happen because the developer is extending the receiver, such as adding custom routes.

Our current OAuth documentation explains how to set up OAuth using the App constructor. But it doesn't explain how to set up OAuth using an instance of ExpressReceiver.

I've created this issue rather than making the update in pull https://github.com/slackapi/bolt-js/pull/711 because it's not immediately clear _where_ we should document this. We will want to use a new code example (see below) and that will require a new documentation section.

• Do we want to create a subsection under the current Basic Concepts - Authenticating with OAuth?
• Or, do we want to create an ExpressReceiver section and ExpressReceiver - Authenticating with OAuth subsection?
• Or, something else?
• How does this impact Bolt for Python documentation?

Code example for using OAuth with an instance of ExpressReceiver:

const customReceiver = new ExpressReceiver({
  signingSecret: process.env.SLACK_SIGNING_SECRET,
  clientId: process.env.SLACK_CLIENT_ID,
  clientSecret: process.env.SLACK_CLIENT_SECRET,
  stateSecret: 'my-state-secret',
  scopes: ['channels:read', 'groups:read', 'channels:manage', 'chat:write', 'incoming-webhook'],
  installationStore: {
    storeInstallation: async (installation) => {
      // change the line below so it saves to your database
      return await database.set(installation.team.id, installation);
    },
    fetchInstallation: async (InstallQuery) => {
      // change the line below so it fetches from your database
      return await database.get(InstallQuery.teamId);
    },
    storeOrgInstallation: async (installation) => {
      // include this method if you want your app to support org wide installations
      // change the line below so it saves to your database
      return await database.set(installation.enterprise.id, installation);
    },
    fetchOrgInstallation: async (InstallQuery) => {
      // include this method if you want your app to support org wide installations
      // change the line below so it fetches from your database
      return await database.get(InstallQuery.enterpriseId);
    },
  },
})

const app = new App({
  receiver: customReceiver
});

What type of issue is this? (place an x in one of the [ ])

• [ ] bug
• [ ] enhancement (feature request)
• [ ] question
• [x] documentation related
• [ ] example code related
• [ ] testing related
• [ ] discussion

Requirements (place an x in each of the [ ])

• [x] I've read and understood the Contributing guidelines and have done my best effort to follow them.
• [x] I've read and agree to the Code of Conduct.
• [x] I've searched for any related issues and avoided creating a duplicate issue.

[stevengill]

Maybe we just add an example app for this instead of adding a section to the docs?

[mwbrooks]

Good idea! Example app would be useful regardless and it could be an easy way to help people while we find a good way to document it.

[seratch]

@mwbrooks I just wanted to check the current status of this. Are we going to add an example OAuth app under examples directory sometime in the future?

[mwbrooks]

@seratch I don't believe anyone is working on it currently. I think adding an OAuth app example under the examples/ directory would be an extremely helpful addition that would not require as much work as the other ideas (e.g. docs)

[seratch]

@mwbrooks Thanks. I agree that having an example should be a great addition. I've updated the labels of this issue.