Slack OAuth

The @slack/oauth package makes it simple to setup the OAuth flow for Slack apps. It supports V2 OAuth for Slack Apps as well as V1 OAuth for Classic Slack apps. Slack apps that are installed in multiple workspaces, like in the App Directory or in an Enterprise Grid, will need to implement OAuth and store information about each of those installations (such as access tokens).

The package handles URL generation, state verification, and authorization code exchange for access tokens. It also provides an interface for easily plugging in your own database for saving and retrieving installation data.

Installation

$ npm install @slack/oauth

Usage

These examples show how to get started using the most common features. You'll find more extensive documentation on the package's website.

Before building an app, you'll need to create a Slack app and install it to your development workspace. You'll also need to copy the Client ID and Client Secret given to you by Slack under the Basic Information of your app configuration.

It may be helpful to read the tutorials on getting started and getting a public URL that can be used for development.

Initialize the installer

This package exposes an InstallProvider class, which sets up the required configuration and exposes methods such as generateInstallUrl, handleCallback, authorize for use within your apps. At a minimum, InstallProvider takes a clientId and clientSecret (both which can be obtained under the Basic Information of your app configuration). InstallProvider also requires a stateSecret, which is used to encode the generated state, and later used to decode that same state to verify it wasn't tampered with during the OAuth flow. Note: This example is not ready for production because it only stores installations (tokens) in memory. Please go to the storing installations in a database section to learn how to plug in your own database.

const { InstallProvider } = require('@slack/oauth');

// initialize the installProvider
const installer = new InstallProvider({
  clientId: process.env.SLACK_CLIENT_ID,
  clientSecret: process.env.SLACK_CLIENT_SECRET,
  stateSecret: 'my-state-secret'
});

const { InstallProvider } = require('@slack/oauth');

// initialize the installProvider
const installer = new InstallProvider({
  clientId: process.env.SLACK_CLIENT_ID,
  clientSecret: process.env.SLACK_CLIENT_SECRET,
  stateSecret: 'my-state-secret',
  authVersion: 'v1' //required for classic Slack apps
});

Generating an installation URL

You'll need an installation URL when you want to test your own installation, in order to submit your app to the App Directory, and if you need an additional authorizations (user tokens) from users inside a team when your app is already installed. These URLs are also commonly used on your own webpages as the link for an "Add to Slack" button. You may also need to generate an installation URL dynamically when an option's value is only known at runtime, and in this case you would redirect the user to the installation URL.

The installProvider.generateInstallUrl() method will create an installation URL for you. It takes in an options argument which at a minimum contains a scopes property. installProvider.generateInstallUrl() options argument also supports metadata, teamId, redirectUri and userScopes properties.

installer.generateInstallUrl({
  // Add the scopes your app needs
  scopes: ['channels:read']
})

installer.generateInstallUrl({
  // Add the scopes your app needs
  scopes: ['channels:read'],
  metadata: JSON.stringify({some:'sessionState'})
})

Handling the OAuth redirect

After the user approves the request to install your app (and grants access to the required permissions), Slack will redirect the user to your specified redirect url. You can either set the redirect url in the app’s OAuth and Permissions page or pass a redirectUri when calling installProvider.generateInstallUrl. Your HTTP server should handle requests to the redirect URL by calling the installProvider.handleCallback() method. The first two arguments (req, res) to installProvider.handleCallback are required. By default, if the installation is successful the user will be redirected back to your App Home in Slack (or redirected back to the last open workspace in your slack app for classic Slack apps). If the installation is not successful the user will be shown an error page.

const { createServer } = require('http');

const server = createServer((req, res) =>  {
  // our redirect_uri is /slack/oauth_redirect
  if (req.url === '/slack/oauth_redirect') {
    // call installer.handleCallback to wrap up the install flow
    installer.handleCallback(req, res);
  }
})

server.listen(3000);

app.get('/slack/oauth_redirect', (req, res) => {
  installer.handleCallback(req, res);
});

const callbackOptions = {
  success: (installation, installOptions, req, res) => {
    // Do custom success logic here
    // Tips:
    // - Inspect the metadata with `installOptions.metadata`
    // - Add javascript and css in the htmlResponse using the </details>