To prepare your Slack app for distribution, you will need to enable Bolt OAuth and store installation information securely. Bolt supports OAuth and will handle the rest of the work; this includes setting up OAuth routes, state verification, and passing your app an installation object which you must store.
To enable OAuth, you must provide:
-
clientId
, clientSecret
, stateSecret
and scopes
(required)
- An
installationStore
option with handlers that store and fetch installations to your database (optional, strongly recommended in production)
Development and Testing
We’ve provided a default implementation of the installationStore
FileInstallationStore
which you can use during app development and testing.
const { App } = require('@slack/bolt');
const { FileInstallationStore } = require('@slack/oauth');
const app = new App({
signingSecret: process.env.SLACK_SIGNING_SECRET,
clientId: process.env.SLACK_CLIENT_ID,
clientSecret: process.env.SLACK_CLIENT_SECRET,
stateSecret: 'my-state-secret',
scopes: ['channels:history', 'chat:write', 'commands'],
installationStore: new FileInstallationStore(),
});
This is not recommended for use in production - you should implement your own production store. Please see the example code to the right and our other examples.
Installing your App
-
Initiating an installation: Bolt for JavaScript provides an Install Path
/slack/install
out-of-the-box. This endpoint returns a simple page with an Add to Slack
button which initiates a direct install of your app (with a valid state
parameter). An app hosted at www.example.com would serve the install page at www.example.com/slack/install.
- 💡 You can skip rendering the provided default webpage and navigate users directly to Slack authorize URL by setting
installerOptions.directInstall: true
in the App
constructor (example).
-
Add to Slack: The Add to Slack
button initiates the OAuth process with Slack. After users have clicked Allow to grant your app permissions, Slack will call your app’s Redirect URI (provided out-of-the-box), and prompt users to Open Slack. See the Redirect URI section below for customization options.
-
Open Slack: After users Open Slack, and here after as your app processes events from Slack, your provided installationStore
’s fetchInstallation
and storeInstallation
handlers will execute. See the Installation Object section below for more detail on arguments passed to those handlers.
-
If you need additional authorizations (user tokens) from users inside a team when your app is already installed, or have a reason to dynamically generate an install URL, manually instantiate an ExpressReceiver
, assign the instance to a variable named receiver
, and then call receiver.installer.generateInstallUrl()
. Read more about generateInstallUrl()
in the OAuth docs.
- 💡 Bolt for JavaScript does not support OAuth for custom receivers. If you’re implementing a custom receiver, you can use our Slack OAuth library, which is what Bolt for JavaScript uses under the hood.
Redirect URI
Bolt for JavaScript provides a Redirect URI Path /slack/oauth_redirect
. Slack uses the Redirect URI to redirect users after they complete an app’s installation flow.
💡 You will need to add the full Redirect URI including your app domain in your Slack app configuration settings under OAuth and Permissions, e.g. https://example.com/slack/oauth_redirect
.
To supply your own custom Redirect URI, you can set redirectUri
in the App options and installerOptions.redirectUriPath
. You must supply both, and the path must be consistent with the full URI.
const app = new App({
signingSecret: process.env.SLACK_SIGNING_SECRET,
clientId: process.env.SLACK_CLIENT_ID,
clientSecret: process.env.SLACK_CLIENT_SECRET,
stateSecret: 'my-state-secret',
scopes: ['chat:write'],
redirectUri: 'https://example.com/slack/redirect', // here
installerOptions: {
redirectUriPath: '/slack/redirect', // and here!
},
});
Installation object
Bolt will pass your installationStore
’s storeInstallation
handler an installation
. This can be a source of confusion for developers who aren’t sure what shape of object to expect. The installation
object should resemble:
{
team: { id: 'T012345678', name: 'example-team-name' },
enterprise: undefined,
user: { token: undefined, scopes: undefined, id: 'U01234567' },
tokenType: 'bot',
isEnterpriseInstall: false,
appId: 'A01234567',
authVersion: 'v2',
bot: {
scopes: [
'chat:write',
],
token: 'xoxb-244493-28*********-********************',
userId: 'U012345678',
id: 'B01234567'
}
}
Bolt will pass your fetchInstallation
and deleteInstallation
handlers an installQuery
object:
{
userId: 'U012345678',
isEnterpriseInstall: false,
teamId: 'T012345678',
enterpriseId: undefined,
conversationId: 'D02345678'
}
Org-wide installation
To add support for org-wide installations, you will need Bolt for JavaScript version 3.0.0
or later. Make sure you have enabled org-wide installation in your app configuration settings under Org Level Apps.
Installing an org-wide app from admin pages requires additional configuration to work with Bolt. In that scenario, the recommended state
parameter is not supplied. Bolt will try to verify state
and stop the installation from progressing.
You may disable state verification in Bolt by setting the stateVerification
option to false. See the example setup below:
const app = new App({
signingSecret: process.env.SLACK_SIGNING_SECRET,
clientId: process.env.SLACK_CLIENT_ID,
clientSecret: process.env.SLACK_CLIENT_SECRET,
scopes: ['chat:write'],
installerOptions: {
stateVerification: false,
},
});
To learn more about the OAuth installation flow with Slack, read the API documentation.