Flask-Dance

Warnings

• breaking Flask-Dance v7.0.0 removed the Twitter pre-set configuration and introduced support for Authorization Flow with PKCE. Existing Twitter integrations will break and require manual implementation or updating to a custom blueprint. Dexcom preset was added.
  Fix: For Twitter, migrate to a custom blueprint or an alternative library. Review documentation for Dexcom integration and PKCE if applicable.
• breaking Version 6.0.0 updated minimum supported versions to Flask 2.0.3 and Werkzeug 2.1. Version 5.0.0 also dropped support for Flask versions below 1.0.4, specifically adding support for Flask 2.0. Ensure your Flask and Werkzeug versions are compatible.
  Fix: Upgrade Flask to 2.0.3+ and Werkzeug to 2.1+ to ensure compatibility with Flask-Dance 6.x and 7.x.
• breaking Flask-Dance v4.0.0 dropped support for Python 2.7. It also added support for SQLAlchemy 1.4. Older Python 2.7 applications must be migrated to Python 3.
  Fix: Upgrade your application's Python version to 3.6+.
• breaking Older versions (pre-v1.0.0, specifically in 0.x releases) had breaking changes in how backends worked, including changes to `OAuthConsumerMixin` columns setting `nullable=False`, which could require database migrations if upgrading from very old versions. Additionally, the attribute to store the backend changed from `backend` to `storage`.
  Fix: Consult `CHANGELOG.rst` for specific migration steps if upgrading from very old versions. Ensure `blueprint.storage = ...` is used instead of `blueprint.backend = ...`.
• gotcha For local development over HTTP (non-HTTPS), you must set the `OAUTHLIB_INSECURE_TRANSPORT` environment variable to `1`. However, this should NEVER be used in production environments, as it disables security checks and makes your application vulnerable.
  Fix: Set `export OAUTHLIB_INSECURE_TRANSPORT=1` for local testing. Always use HTTPS in production and remove this environment variable.
• gotcha An open issue (#438 on GitHub) indicates that `oauthlib` version 3.3.0 breaks the current implementation of Flask-Dance, preventing OAuth flows from working correctly. This is a critical dependency issue.
  Fix: Downgrade `oauthlib` to a compatible version (e.g., `oauthlib<3.3.0`) until Flask-Dance officially supports `oauthlib==3.3.0` or a fix is released. Monitor the Flask-Dance GitHub issues for updates.

Install

• pip install Flask-Dance Basic installation
• pip install Flask-Dance[sqla] With SQLAlchemy storage

Imports

• make_github_blueprint

  from flask_dance.contrib.github import make_github_blueprint

  Commonly used preset blueprint for GitHub.
• github

  from flask_dance.contrib.github import github

  Context local for making requests to GitHub API; similar imports exist for other providers (e.g., `google`, `facebook`).
• OAuth2ConsumerBlueprint

  from flask_dance.consumer import OAuth2ConsumerBlueprint

  For creating custom OAuth 2.0 blueprints not covered by presets.
• OAuthConsumerMixin

  from flask_dance.consumer.storage.sqla import OAuthConsumerMixin

  Used with SQLAlchemy for defining the OAuth token model.
• SQLAlchemyStorage

  from flask_dance.consumer.storage.sqla import SQLAlchemyStorage

  Used to configure SQLAlchemy as the token storage backend.

Quickstart

This quickstart demonstrates setting up a Flask application with GitHub OAuth using Flask-Dance. It registers a GitHub blueprint, which handles the OAuth flow. The root route checks if the user is authorized; if not, it redirects them to the GitHub login page. Once authorized, it fetches and displays the GitHub username. Ensure to set `FLASK_SECRET_KEY`, `GITHUB_OAUTH_CLIENT_ID`, and `GITHUB_OAUTH_CLIENT_SECRET` environment variables. For local development without HTTPS, `OAUTHLIB_INSECURE_TRANSPORT=1` must be set.

import os
from flask import Flask, redirect, url_for, session
from flask_dance.contrib.github import make_github_blueprint, github

app = Flask(__name__)
app.secret_key = os.environ.get("FLASK_SECRET_KEY", "supersekrit")

github_blueprint = make_github_blueprint(
    client_id=os.environ.get("GITHUB_OAUTH_CLIENT_ID"),
    client_secret=os.environ.get("GITHUB_OAUTH_CLIENT_SECRET"),
)
app.register_blueprint(github_blueprint, url_prefix="/login")

@app.route("/")
def index():
    if not github.authorized:
        return redirect(url_for("github.login"))
    resp = github.get("/user")
    assert resp.ok, resp.text
    return f"You are @{resp.json()['login']} on GitHub"

if __name__ == "__main__":
    # For local development with HTTP, set OAUTHLIB_INSECURE_TRANSPORT=1
    # Example: export OAUTHLIB_INSECURE_TRANSPORT=1
    app.run(debug=True)