InstallProvider
provides a way to manage configuration and functionality for adding an OAuth flow to Slack apps. It contains capabilities for OAuth URL generation, state verification, authorization code exchange, as well as interfaces for storing installation details like user and bot tokens.
Constructs a new instance of the InstallProvider
class
Parameters:
Name | Type | Required | |
---|---|---|---|
opts | InstallProviderOptions |
✓ |
Name | Type | |
---|---|---|
installationStore | InstallationStore |
|
stateStore | StateStore |
This method handles HTTP requests to the application’s installation page. It can be used to automatically render a typical installation page with an “Add to Slack” button.
Parameters:
Name | Type | Required | |
---|---|---|---|
req | IncomingMessage |
✓ | |
res | ServerResponse |
✓ | |
options | InstallPathOptions |
✗ | |
installOptions | InstallURLOptions |
✗ |
Returns Promise<void>
Returns a URL that is suitable for including in an Add to Slack button. Uses the instance’s stateStore to generate a value for the state
OAuth parameter. Can disable state generation by setting stateVerification
to false
. Can prescribe a specific state
OAuth parameter value by setting the state
argument to this function explicitly.
Parameters:
Name | Type | Required | ||
---|---|---|---|---|
options | InstallURLOptions |
✓ | ||
stateVerification | boolean |
✗ (defaults to true ) |
||
state | string |
✗ |
Returns Promise<string>
This method handles the incoming callback request to the application after a redirection from slack.com following a successful user authorization. It can be used as a RequestListener in almost any HTTP server framework.
Verifies the state using the instance’s stateStore, exchanges the grant in the query parameters for an access token, and stores token and associated installation data in the instance’s installationStore.
Parameters:
Name | Type | Required | |
---|---|---|---|
req | IncomingMessage |
✓ | |
res | ServerResponse |
✓ | |
options | CallbackOptions |
✗ | |
installOptions | InstallURLOptions |
✗ |
Returns Promise<void>
Fetches installation data from the instance’s installationStore.
Parameters:
Name | Type | Required | |
---|---|---|---|
source | InstallationQuery |
✓ |
Returns Promise<AuthorizeResult>
Name | Type | |
---|---|---|
botId | string |
|
botRefreshToken | string |
|
botToken | string |
|
botTokenExpiresAt | number (UTC, seconds) |
|
botUserId | string |
|
enterpriseId | string |
|
teamId | string |
|
userRefreshToken | string |
|
userToken | string |
|
userTokenExpiresAt | number (UTC, seconds) |
Name | Type | Description | |
---|---|---|---|
beforeInstallation | (options: InstallURLOptions, callbackReq: IncomingMessage, callbackRes: ServerResponse) => Promise<boolean> |
Additional logic to run right before executing the Slack app installation with the given OAuth code parameter. When this method returns false , the InstallProvider skips the installation. A common use for returning false in this method is if the visiting user is not eligible to proceed with the Slack app installation flow. When returning false , this method is responsible for calling the callbackRes#end() method to build a complete HTTP response for the end-user. |
|
afterInstallation | (installation: Installation | OrgInstallation, options: InstallURLOptions, callbackReq: IncomingMessage, callbackRes: ServerResponse) => Promise<boolean> |
Additional logic to run right after executing the Slack app installation with the given OAuth code parameter. When this method returns false , the InstallProvider skips storing the installation in the database (or whatever implementation your InstallationStore uses). A common use for returning false in this method is if your app needs to cancel the installation and display an error page to the installing user. When returning false , this method is responsible for calling the callbackRes#end() method to build a complete HTTP response for the end-user. |
|
failure | (error: CodedError, options: InstallURLOptions, callbackReq: IncomingMessage, callbackRes: ServerResponse) => void |
failure is invoked if handleCallback fails at any point. When provided, this function must complete sending the HTTP response to the end-user by calling callbackRes#end() . |
|
failureAsync | (error: CodedError, options: InstallURLOptions, callbackReq: IncomingMessage, callbackRes: ServerResponse) => Promise<void> |
An asynchronous version of failure . If both are defined, both will be executed. |
|
success | (installation: Installation, options: InstallURLOptions, callbackReq: IncomingMessage, callbackRes: ServerResponse) => void |
success is invoked after handleCallback completes and has stored the installation data. When provided, this function must complete sending the HTTP response to the end-user by calling callbackRes#end() . |
|
successAsync | (installation: Installation, options: InstallURLOptions, callbackReq: IncomingMessage, callbackRes: ServerResponse) => Promise<void> |
An asynchronous version of success . If both are defined, both will be executed. |
An individual installation of the Slack app.
This interface creates a representation for installations that normalizes the responses from OAuth grant exchanges across auth versions (responses from the Web API methods oauth.v2.access
and oauth.access
). It describes some of these differences using the AuthVersion
generic placeholder type.
This interface also represents both installations which occur on individual Slack workspaces and on Slack enterprise organizations. The IsEnterpriseInstall
generic placeholder type is used to describe some of those differences.
This representation is designed to be used both when producing data that should be stored by an InstallationStore
, and when consuming data that is fetched from an InstallationStore
. Most often, InstallationStore
implementations are a database. If you are going to implement an InstallationStore
, it’s advised that you store as much of the data in these objects as possible so that you can return as much as possible inside fetchInstallation()
.
Name | Type | |
---|---|---|
appId | string | undefined |
|
authVersion | 'v1' | 'v2' |
|
bot | object |
|
enterprise | object |
|
enterpriseUrl | string | undefined |
|
incomingWebhook | object |
|
isEnterpriseInstall | boolean |
|
metadata | string |
|
team | object |
|
tokenType | string |
|
user | object |
Name | Type | |
---|---|---|
conversationId | string |
|
enterpriseId | string |
|
isEnterpriseInstall | boolean |
|
teamId | string |
|
userId | string |
Name | Type | Required | |
---|---|---|---|
deleteInstallation | (query: InstallationQuery, logger?: Logger) => Promise<void> |
✗ | |
fetchInstallation | (query: InstallationQuery, logger?: Logger) => Promise<Installation> |
✓ | |
storeInstallation | (installation: Installation, logger?: Logger) => Promise<void> |
✓ |
Customize the response headers and body data for additional user-specific data handling such as account mapping and activity tracking.
Name | Type | Description | |
---|---|---|---|
beforeRedirection | (request: IncomingMessage, response: ServerResopnse, options: InstallURLOptions) => Promise<boolean> |
When this method returns false , the InstallProvider skips state OAuth parameter generation, setting the state in HTTP cookies, generating an install URL and redirecting to the slack.com authorization URL. Common use cases for returning false include when the visiting user is not eligible to proceed with the Slack application installation flow. When returning false , this method is responsible for calling response#end() to build a complete HTTP response for the end-user. |
Name | Type | Description | |
---|---|---|---|
authorizationUrl | string |
The slack.com authorization URL. This defaults to https://slack.com/oauth/v2/authorize when OAuth v2 is used, otherwise it will be set to https://slack.com/oauth/authorize . |
|
authVersion | 'v1' | 'v2' |
The OAuth version to employ. Defaults to v2 . |
|
clientId | string |
Required. Your application client ID can be found under the Basic Information section of your application on api.slack.com/apps. | |
clientOptions | Omit<WebClientOptions, 'logLevel' | 'logger'> |
An object adhering to the @slack/web-api WebClientOptions interface, which can be used to customize the API client interacting with Slack's APIs under the hood in this package. |
|
clientSecret | string |
Required. Your application client secret can be found under the Basic Information section of your application on api.slack.com/apps. | |
directInstall | boolean |
If true , the install path web page rendering will be skipped and instead the user will be immediately redirected to the slack.com entry point for the OAuth process. Defaults to false . |
|
installationStore | InstallationStore |
An object adhering to the InstallationStore interface. Used to specify how application installation details like access token should be stored. Defaults to an instance of MemoryInstallationStore . |
|
installUrlOptions | InstallURLOptions |
An object adhering to the InstallURLOptions interface. Used to specify what permissions (scopes) the application should ask for, metadata to pass during the OAuth flow and override redirect URIs. |
|
legacyStateVerification | boolean |
Whether to skip checking browser cookies for state OAuth parameter verification. Defaults to false . Enabling this option is not recommended! This is intended to be used only for backwards-compatibility with versions 2.4 and older. |
|
logger | Logger |
An object adhering to the Logger interface. Used to specify how the application will log events. |
|
logLevel | LogLevel |
An object adhering to the LogLevel enum. Used to specify how verbosely the application should log. Defaults to INFO . |
|
stateCookieExpirationSeconds | number |
The expiration time in seconds for the state parameter used during the OAuth process. It defines an expiration time for the cookie used to store the state. Defaults to 600 . |
|
stateCookieName | string |
The cookie name used to house the state parameter during the OAuth process. Defaults to slack-app-oauth-state . |
|
stateSecret | string |
A secret value used for generating the state parameter used during the OAuth process (to prevent CSRF). |
|
stateStore | StateStore |
An object adhering to the StateStore interface. Stores state issued to the authorization server and verified the value returned at redirection during the OAuth flow (to prevent CSRF). Defaults to ClearStateStore . |
|
stateVerification | boolean |
Whether to enable verifying the state OAuth parameter. Defaults to true . |
Name | Type | |
---|---|---|
metadata | string |
|
redirectUri | string |
|
scopes | string | string[] |
|
teamId | string |
|
userScopes | string | string[] |
Name | Type | |
---|---|---|
appId | string | undefined |
|
bot | object |
|
enterprise | object |
|
incomingWebhook | object |
|
tokenType | string |
|
user | object |
Name | Type | |
---|---|---|
generateStateParam | (installOptions: InstallURLOptions, now: Date) => Promise<string> |
|
verifyStateParam | (now: Date, state: string) => Promise<InstallURLOptions> |