Manually authenticate with Slack OAuth

In today's digital age, collaboration and communication tools are essential for efficient teamwork. One such tool that has gained immense popularity among professionals is Slack. Slack provides a seamless platform for teams to collaborate, share ideas, and stay connected.

However, to access the full potential of Slack and to use it in your application, it is crucial to understand and implement OAuth, which stands for Open Authorization. OAuth is a widely-used authentication protocol that allows users to grant third-party applications access to their Slack workspace without sharing their login credentials. This grants users control over their data and enhances security.

In this comprehensive guide, we will walk you through the process of implementing Slack OAuth step-by-step.

What is OAuth?

OAuth, which stands for Open Authorization, is an open standard for authorization that allows users to grant third-party applications access to their resources without sharing their login credentials. It is a widely-used authentication protocol that is used by many popular applications, including Slack, Google, Facebook, and Twitter.

Why use OAuth?

Enhanced Security: By allowing users to grant third-party applications access to their server resources, OAuth eliminates the need for users to share sensitive login details with third-party services, thereby reducing the risk of password leaks.

Granular Access Control: OAuth allows users to grant granular access to their resources using "scopes". For example, a user can grant an application access to read certain resources, but not modify or delete them.

Standardization: OAuth is a standardized protocol, offering broad support and streamlined authentication processes across different services and platforms.

How does OAuth work?

OAuth employs a token-based mechanism for both authentication and authorization. Let's break down the OAuth flow within the context of integrating with Slack:

1. Request: The client (a third-party application) requests the user's authorization to access their Slack workspace.

2. Consent: The user authorizes the Slack application to grant the client access to their workspace, typically through a consent screen that details the requested permissions.

3. Grant: Slack then issues an authorization grant, a credential that represents the user's authorization, to the client.

4. Token Exchange: The client exchanges this authorization grant for an access token, which comes with a refresh token for maintaining long-term access without needing to re-authorize.

5. Access: Using the access token, the client can now make API calls to Slack on the user's behalf within the granted scope.

6. Refreshing: If the access token expires, the client uses the refresh token to obtain a new access token without the user's intervention, maintaining seamless access to the user's Slack resources.

What are scopes?

Scopes are strings that define the specific actions that third-party applications are permitted to perform on behalf of the user. When a client requests access, it must specify which scopes it requires. For Slack integrations, scopes control permissions for actions such as reading messages, posting updates, accessing user profile information, or changing workspace settings. Users can review and modify these scopes, thereby maintaining control over the level of access they're comfortable granting to their resources.

Setting up Slack app

Creating a Slack app

To get started with Slack OAuth, you need to create a Slack app. Follow these steps to create a new app:

1. Sign in to the Slack API website: Visit the Slack API website and sign in with your Slack account.

2. Create a new app: Click on the "Create New App" button to create a new Slack app. Provide a name for your app and select the Slack workspace where you want to install and test your app.

3. Configure your app settings: Once your app is created, you will be redirected to the app settings page. This is where you can configure various settings for your app, such as the app name, description, icon, and other details.

4. Enable OAuth: In the app settings page, navigate to the "OAuth & Permissions" section. Enable the "OAuth & Permissions" toggle to enable OAuth for your app.

Configure OAuth in Your Slack App

After enabling OAuth for your Slack app, you need to configure the OAuth & Permissions settings. This is where you define the scopes and permissions your app requires to access user data. Follow these steps to configure the settings:

1. Add Redirect URLs: In the "Redirect URLs" section, add the URLs where Slack will redirect users after they authorize your app. Make sure to include both the development and production URLs if applicable.

2. Define Scopes: Scopes determine the level of access your app has to a user's Slack workspace. In the "Scopes" section, select the scopes required for your app. Scopes may include permissions to read channels, send messages, manage users, and more. Choose the scopes that align with your app's functionality. Here is a full list of scopes.

3. Save Changes: After configuring the redirect URLs and scopes, save your changes to apply the OAuth settings.

Generating an authorization URL

To begin the authorization process, you'll need to redirect users to Slack's authorization endpoint. The base URL for this is https://slack.com/oauth/v2/authorize.

Append your app's Client ID and a space-separated list of scopes to the URL. Your Client ID is located on the App Management page of your Slack app. For example, you might add client_id=YOUR_CLIENT_ID and scope=incoming-webhook,commands to your authorization URL.

You must include a redirect_uri parameter in the authorization URL, which tells Slack where to send the user after they've approved the app installation. This URI must be an HTTPS address and is where Slack will redirect users along with the temporary authorization code. The redirect_uri should match or be a subdirectory of a Redirect URL that you've configured in the App Management page.

It's highly recommended to include a state parameter in the URL. This value should be unique to the user and your application should verify it when Slack redirects the user back with the temporary authorization code. This step is crucial for protecting against Cross-Site Request Forgery (CSRF) attacks.

The complete URL will look something like this: https://slack.com/oauth/v2/authorize?scope=incoming-webhook,commands&client_id=YOUR_CLIENT_ID&redirect_uri=https://example.com/path&state=UNIQUE_STATE_VALUE

Handling the OAuth callback

Listen for the OAuth callback

Once the user has granted (or denied) access to your application, Slack will redirect them to the redirect URI you specified with additional query parameters appended to the URL. Your application must listen for this callback because it contains important information about the user's authorization decision.

1. Check the State: If you used a state parameter, verify it first to ensure the request is valid and originated from your application.

2. Look for the Authorization Code: Slack will provide an authorization code as a query parameter if the user approved the request. This code is essential for the next step in the OAuth process.

3. Handle Errors: If the user denies access or if there was another issue, Slack will append an error message to the callback URL, which you should handle appropriately in your application.

Exchanging the authorization code for an access token

To swap the authorization code for an access token, you need to make a POST request to the oauth.v2.access endpoint.

fetch('https://slack.com/api/oauth.v2.access', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
        code: 'YOUR_AUTHORIZATION_CODE',
        client_id: 'YOUR_CLIENT_ID',
        client_secret: 'YOUR_CLIENT_SECRET'
    })
})
.then(response => response.json())
.then(data => {
    console.log(data);
})
.catch(error => console.error('Error:', error));

Replace YOUR_AUTHORIZATION_CODE, YOUR_CLIENT_ID, and YOUR_CLIENT_SECRET with your actual authorization code, client ID, and client secret.

Expiry

Slack OAuth tokens do not expire. However, they can be revoked under certain conditions, such as a user uninstalling your app, a workspace owner removing the app, or if the user who initially authenticated the Slack app has their account deactivated.

Make API calls with the access token

Once you have obtained an access token, you can use it to make API calls to Slack on behalf of the bot user. To do this, you need to include the access token in the Authorization header of your API requests.

Conclusion

In this comprehensive blog post, we delved into the world of Slack OAuth, understanding its significance and implementation. We explored the fundamentals of OAuth, how it works, and its role in securing authorization for third-party applications.

We then focused on setting up Slack OAuth, guiding you through the process of creating a Slack app, configuring OAuth and permissions settings, and obtaining the necessary OAuth tokens. With these tokens in hand, we learned how to implement Slack OAuth in both server-side and client-side applications, enabling seamless integration with the Slack platform.

Security is paramount when it comes to OAuth implementations, and we discussed best practices for storing OAuth tokens, handling token revocation, and monitoring and logging OAuth activities. By following these practices, you can safeguard user data and maintain the integrity of your application.

With the knowledge gained from this blog post, you are well-equipped to understand and implement Slack OAuth in your own applications. Remember to follow best practices, prioritize security, and stay up to date with any changes or updates in the Slack API documentation.

OAuth serves as a powerful tool for enabling secure and seamless integration with Slack, enhancing collaboration and productivity within teams. As you embark on your journey of implementing Slack OAuth, may your applications thrive and bring value to users in the Slack ecosystem.

Happy coding and integrating with Slack OAuth!

More Resources

Slack provides a guide on implementing this flow, which is where we got most of our information from. You can find it here.