Flask-OIDC

Warnings

• breaking Version 2.0.0 represents a major rebase of Flask-OIDC's API on the Authlib library. This introduced significant breaking changes in how the library is configured and used compared to 1.x versions.
  Fix: Review the official documentation and migration guides for Authlib and Flask-OIDC v2.x. Many configuration options and API calls have changed or been removed. For example, `oidc.credentials_store` and other constructor parameters were removed.
• deprecated The `OpenIDConnect.user_getinfo()` and `OpenIDConnect.user_getfield()` methods are deprecated. User information should now be accessed via `session["oidc_auth_profile"]` or `g.oidc_user.userinfo`.
  Fix: Replace calls to `oidc.user_getinfo()` or `oidc.user_getfield()` with direct access to `session["oidc_auth_profile"]` or the properties of `g.oidc_user` (available since 2.2.0).
• breaking The `redirect_uri` sent to the ID provider in earlier 2.x versions (e.g., 2.0.3) was forced to HTTPS. In 2.1.0, this was changed to no longer force HTTPS based on OIDC spec recommendations. If you explicitly need to force HTTPS (or any specific URL), use `OIDC_OVERWRITE_REDIRECT_URI`.
  Fix: For applications needing specific `redirect_uri` behavior, especially forcing HTTPS, explicitly set the `OIDC_OVERWRITE_REDIRECT_URI` configuration option. Review the behavior in versions 2.0.3 and 2.1.0 in the changelog.
• gotcha The `oidc.redirect_to_auth_server()` method was initially removed in 2.x and then re-added in version 2.2.2 for compatibility with v1.x usage patterns.
  Fix: If migrating from 1.x and encountering issues with `redirect_to_auth_server()`, ensure you are on version 2.2.2 or later if you need to use this specific method. Otherwise, adapt your code to newer 2.x patterns for redirection.
• gotcha A `SECRET_KEY` for the Flask application is absolutely critical for session management and overall security. Failing to set a strong, unique secret key will lead to security vulnerabilities.
  Fix: Always set `app.config['SECRET_KEY']` to a long, random string. It is highly recommended to manage this key via environment variables in production. For example, `os.environ.get('FLASK_SECRET_KEY', 'default_for_dev')`.
• gotcha The `client_secrets.json` file is mandatory for OIDC configuration unless the `OIDC_ENABLED` setting is explicitly set to `False`. Before version 2.3.1, not having this file would cause issues even if `OIDC_ENABLED` was set to `False`.
  Fix: Ensure a valid `client_secrets.json` file is present or that `OIDC_ENABLED` is set to `False` (requires version 2.3.1 or higher for `client_secrets.json` to be entirely optional in this disabled state). The structure requires a top-level `web` key.
• breaking Version 2.4.0 includes a fix for an open redirect vulnerability in login and logout URLs. While this is a fix, applications relying on or inadvertently enabling such redirects could experience changes in behavior or breakages.
  Fix: Upgrade to version 2.4.0 or later to apply the security fix. Review any custom login/logout redirect logic to ensure it is not negatively impacted by the fix and adheres to secure redirect practices.

Install

• pip install flask-oidc Install stable version

Imports

• OpenIDConnect

  from flask_oidc import OpenIDConnect

  The primary class for OIDC integration.
• g

  from flask import g

  Flask's global object, used to access OIDC user information after login (e.g., `g.oidc_user`).
• session

  from flask import session

  Flask's session object, stores 'oidc_auth_profile' for user information.

Quickstart

This quickstart demonstrates a basic Flask application integrated with Flask-OIDC. It configures the OIDC extension, protects a route using `oidc.require_login`, and provides simple login/logout functionality. Configuration details for your OIDC provider are expected in a `client_secrets.json` file. Ensure `FLASK_SECRET_KEY` and the `client_secrets.json` path are set, ideally via environment variables, and configure `OIDC_REDIRECT_URI` to match your registered callback URL.

import os
from flask import Flask, redirect, url_for, render_template_string, g, session
from flask_oidc import OpenIDConnect

app = Flask(__name__)
app.config.update({
    'SECRET_KEY': os.environ.get('FLASK_SECRET_KEY', 'a_very_secret_key_that_should_be_random'),
    'OIDC_CLIENT_SECRETS': os.environ.get('OIDC_CLIENT_SECRETS_FILE', './client_secrets.json'),
    'OIDC_REDIRECT_URI': os.environ.get('OIDC_REDIRECT_URI', 'http://localhost:5000/oidc_callback'),
    'OIDC_SCOPES': ['openid', 'email', 'profile'],
    'OIDC_COOKIE_SECURE': False, # Use True in production with HTTPS
    'OIDC_CALLBACK_ROUTE': '/oidc_callback', # The default callback route.
    'OIDC_REQUIRE_VERIFIED_EMAIL': False # Set to True for stricter validation
})

oidc = OpenIDConnect(app)

HTML_TEMPLATE = '''
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"></head>
<body>
    {% if g.oidc_user.is_authenticated() %}
        Hello, {{ g.oidc_user.userinfo.get('preferred_username', 'User') }}!
        <a href="{{ url_for('private') }}">Access Protected Area</a>
        <a href="{{ url_for('oidc_logout') }}">Log Out</a>
    {% else %}
        Welcome, anonymous user!
        <a href="{{ url_for('private') }}">Log In</a>
    {% endif %}
</body>
</html>
'''

@app.route('/')
def index():
    return render_template_string(HTML_TEMPLATE)

@app.route('/private')
@oidc.require_login # Protect this route.
def private():
    return f"Hello, {g.oidc_user.userinfo.get('email')}! This is a protected area."

@app.route('/logout')
def oidc_logout():
    oidc.logout()
    return redirect(url_for('index'))

# Example client_secrets.json content (create this file next to your app.py):
# {
#   "web": {
#     "client_id": "YOUR_CLIENT_ID",
#     "client_secret": "YOUR_CLIENT_SECRET",
#     "auth_uri": "YOUR_PROVIDER_AUTH_URI",
#     "token_uri": "YOUR_PROVIDER_TOKEN_URI",
#     "userinfo_uri": "YOUR_PROVIDER_USERINFO_URI",
#     "issuer": "YOUR_PROVIDER_ISSUER",
#     "redirect_uris": ["http://localhost:5000/oidc_callback"],
#     "token_introspection_uri": "YOUR_PROVIDER_TOKEN_INTROSPECTION_URI" (optional)
#   }
# }

if __name__ == '__main__':
    # For local development, ensure OIDC_CLIENT_SECRETS_FILE points to a valid file.
    # Replace with your actual OIDC provider details in client_secrets.json
    # And set FLASK_SECRET_KEY in your environment.
    # export FLASK_SECRET_KEY="a_strong_random_secret_key"
    # If using HTTP (not recommended for production), set OIDC_COOKIE_SECURE to False.
    # Otherwise, ensure your application runs over HTTPS.
    app.run(debug=True, port=5000)