Clarify that OAuth is not supported by custom receivers.

[mwbrooks]

Summary

Problem

Some developers have experienced confusion from the mention of ExpressReceiver in the OAuth documentation. This is understandable because ExpressReceiver doesn't have any formal documentation. Specifically, this sentence is the source of confusion:

Your app only has built-in OAuth support when using the built-in ExpressReceiver

Solution

I've taken a stab at rewording this section by:

• Removing the mention of ExpressReceiver from the opening paragraph
• Focusing on opening paragraph on how Bolt handles OAuth out-of-the-box
• Adding a disclaimer at the bottom that OAuth is not supported by custom receivers
  • This is where the org-level disclaimer is mentioned
• Linking custom receivers to our custom receiver section
  • The custom receiver section introduces the concept of the built-in ExpressReceiver

Requirements (place an x in each [ ])

• I've read and understood the Contributing Guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.

[codecov]

Codecov Report

Merging #711 (018d92c) into main (4c7ecf1) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #711   +/-   ##
=======================================
  Coverage   82.32%   82.32%           
=======================================
  Files           8        8           
  Lines         758      758           
  Branches      250      250           
=======================================
  Hits          624      624           
  Misses         78       78           
  Partials       56       56           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 4c7ecf1...018d92c. Read the comment docs.

[stevengill]

This looks good. Definitely more clear. The one usecase we aren't currently covering is when folks want to use our built in express Receiver but extend it.

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
});

All OAuth related fields can be passed into an instance of our ExpressReceiver here. This is a usecase I've seen a handful of times when folks want to add custom endpoints.

[mwbrooks]

Good point @stevengill. I'll try to update this PR with the use-case of extending the ExpressReceiver. I think we might as well tackle it now, since it's came up in the past and you've already mentioned the source code for it.

[mwbrooks]

After looking into documenting how to use OAuth with an instance of ExpressReceiver, I think it's best to work on it as a separate task so that we don't block this update. The reason is that it may require a new section in the documentation in order to show the code sample.

I've created issue #715 to track the work.

[avery100]

Hi, does this mean that Bolt OAuth is not supported in this deployment tutorial?
https://slack.dev/bolt-js/deployments/aws-lambda

There is a code example in that tutorial that features a custom receiver;
I'm able to generate with Bolt an Add To Slack button (install, redirect and events paths) but had to remove the "token", but then the subsequent events from Slack get this error:
offline: GET /slack/oauth_redirect (λ: slack)
⚡️ Bolt app is running!
offline: (λ: slack) RequestId: ckl9bcumb0002pevsbxcvbipz Duration: 1459.68 ms Billed Duration: 1500 ms

offline: POST /slack/events (λ: slack)
⚡️ Bolt app is running!
[WARN] bolt-app Authorization of incoming event did not succeed. No listeners will be called.
[ERROR] bolt-app Error: Cannot read property 'token' of undefined
at new AuthorizationError (/Library/WebServer/Documents/HeyAxl/hey-axl-app/node_modules/@slack/oauth/src/errors.ts:37:5)
at InstallProvider. (/Library/WebServer/Documents/HeyAxl/hey-axl-app/node_modules/@slack/oauth/src/index.ts:135:13)
at step (/Library/WebServer/Documents/HeyAxl/hey-axl-app/node_modules/@slack/oauth/dist/index.js:44:23)
at Object.next (/Library/WebServer/Documents/HeyAxl/hey-axl-app/node_modules/@slack/oauth/dist/index.js:25:53)
at fulfilled (/Library/WebServer/Documents/HeyAxl/hey-axl-app/node_modules/@slack/oauth/dist/index.js:16:58)
at processTicksAndRejections (internal/process/task_queues.js:97:5) {
code: 'slack_bolt_authorization_error'
}

---- i assumed that Bolt's implementation of OAuth handled getting the "Exchanging a temporary authorization code for an access token" part but then i realized i am using a custom receiver due to the aws-serverless-express in this tutorial.
Should i be implementing my own using the @slack/oauth library? Should the tutorial mention this more explicitly or is there something else going on?
Your help is greatly appreciated.