Flask-Dance Example App: Slack Edition

This repository provides an example of how to use Flask-Dance to write a simple Slack integration. The example code is in slack.py -- all the other files in this repository are secondary. You can run this example code locally, or deploy it to Heroku for free to see how it runs in a production-style environment.

Heroku Installation

Heroku is a great way to get up and running fast, and you don't even need to open the terminal!

Step 1: Deploy to Heroku

It's easy, and it's free! Just click on this button:

You can leave all the fields at their default values: we'll fill them in later. The only thing that matters right now is the app name, and Heroku will autogenerate a name for you if you leave that field blank. Using an autogenerated name is perfectly fine, just take note of what it is.

Note that your app isn't functional yet, and if you try to visit it right now, you'll end up at a Slack error page. That's OK, we're not done yet!

Step 2: Get OAuth credentials from Slack

Visit the Slack API page at https://api.slack.com/, click on "My Apps" at the top, and create a new application. You can fill in most of the fields however you want, but the "Redirect URI(s)" field is special. To fill it out, you'll need that app name from Heroku. The correct redirect URI is https://APPNAME.herokuapp.com/login/slack/authorized. For example, if Heroku assigned you an app name of peaceful-lake, your redirct URI must be https://peaceful-lake.herokuapp.com/login/slack/authorized. Once you've filled in all of the fields, click "Create Application". Slack will give you a client ID and client secret, which we'll use in the next step.

Step 3: Give OAuth credentials to your app on Heroku

Go to Heroku and visit the settings page for your app. (You can get there from your Heroku dashboard, or by clicking on the "Manage App" button after the deploy step is finished.) On that page, there should be a section called "Config Variables" where you can manage the config vars for your application. You'll need click the "Reveal Config Vars" button to see which variables are available, and then the "Edit" button to allow you to change these variables.

Take the client ID you got from Slack, and paste it into the "VALUE" field next to the SLACK_OAUTH_CLIENT_ID field, replacing the dummy value that was there before. Similarly, take the client secret you got from Slack, and paste it into the "VALUE" field next to the SLACK_OAUTH_CLIENT_SECRET field, replacing the dummy value that was there before. Click the "Save" button when you're done.

Step 4: Visit your app and connect to Slack team!

Your app name from Heroku will determine the URL that your app is running on: the URL will be https://APPNAME.herokuapp.com. For example, if Heroku assigned you an app name of peaceful-lake, your app will be available at https://peaceful-lake.herokuapp.com. Visit that URL, and you should immediately be redirected to connect your Slackbot to your Slack team!

Local Installation

If you'd prefer to run this locally on your computer, you can do that as well.

Step 1: Get OAuth credentials from Slack

Visit the Slack API page at https://api.slack.com/, click on "My Apps" at the top, and create a new application. You can fill in most of the fields however you want, but you must set the "Redirect URI(s)" field to http://localhost:5000/login/slack/authorized. Once you've filled in all of the fields, click "Create Application". Slack will give you a client ID and client secret, which we'll use in step 3.

Step 2: Install code and dependencies

Run the following commands on your computer:

git clone https://github.com/singingwolfboy/flask-dance-slack.git
cd flask-dance-slack
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

These commands will clone this git repository onto your computer, create a virtual environment for this project, activate it, and install the dependencies listed in requirements.txt.

Step 3: Set environment variables

Many applications use environment variables for configuration, and Flask-Dance is no exception. You'll need to set the following environment variables:

• FLASK_APP: set this to slack.py
• SLACK_OAUTH_CLIENT_ID: set this to the client ID you got from Slack.
• SLACK_OAUTH_CLIENT_SECRET: set this to the client secret you got from Slack.
• OAUTHLIB_RELAX_TOKEN_SCOPE: set this to true. This indicates that it's OK for Slack to return different OAuth scopes than requested; Slack does that sometimes.
• OAUTHLIB_INSECURE_TRANSPORT: set this to true. This indicates that you're doing local testing, and it's OK to use HTTP instead of HTTPS for OAuth. You should only do this for local testing. Do not set this in production! [oauthlib docs]

The easiest way to set these environment variables is to define them in an .env file. You can then install the python-dotenv package to make Flask automatically read this file when you run the dev server. This repository has a .env.example file that you can copy to .env to get a head start

Step 4: Run your app and connect to Slack team!

Run your app using the flask command:

flask run

Then, go to http://localhost:5000/ to visit your app and connect it to your Slack team!

If you get an error message that says "Could not locate a Flask application", then you need to install the python-dotenv package using pip:

pip install python-dotenv

Once the package is installed, try the flask run command again!

Learn more!

Fork this GitHub repo so that you can make changes to it. Read the documentation for Flask and Flask-Dance to learn what's possible. Ask questions, learn as you go, build your own OAuth-enabled web application, and don't forget to be awesome!