Skip to Content

Backend Python / Flask

Acrescente o início de sessão a uma aplicação Python Flask com a biblioteca Authlib e o fluxo Authorization Code com PKCE.

Este guia acrescenta o início de sessão OIDC a uma aplicação Flask com Authlib, que trata da discovery, do PKCE e da validação dos tokens. Parte do princípio de que se trata de um cliente confidential (um backend capaz de guardar um segredo).

Se ainda não registou uma aplicação, consulte Antes de começar. Para o protocolo subjacente, consulte OpenID Connect (Authorization Code + PKCE).

1. Instalar as dependências

pip install flask authlib requests

2. Configurar o cliente

import os

from authlib.integrations.flask_client import OAuth
from flask import Flask, redirect, session, url_for

app = Flask(__name__)
app.secret_key = os.environ["SESSION_SECRET"]

oauth = OAuth(app)
oauth.register(
    "idp",
    client_id=os.environ["OIDC_CLIENT_ID"],
    client_secret=os.environ["OIDC_CLIENT_SECRET"],
    # Your instance's login domain (issuer). Authlib reads the discovery
    # document and configures all endpoints from it.
    server_metadata_url="https://<your-domain>/.well-known/openid-configuration",
    client_kwargs={
        "scope": "openid profile email offline_access",
        "code_challenge_method": "S256",  # send a PKCE challenge as well
    },
)

Mantenha OIDC_CLIENT_ID e OIDC_CLIENT_SECRET no ambiente, nunca no controlo de versões.

3. Iniciar a autenticação

O Authlib constrói o URL de autorização com um desafio PKCE e um state, guarda ambos na sessão e redireciona o browser:

@app.route("/login")
def login():
    redirect_uri = url_for("callback", _external=True)  # e.g. https://app.example.com/callback
    return oauth.idp.authorize_redirect(redirect_uri)

O redirect_uri tem de corresponder exatamente a um valor registado na aplicação.

4. Processar o callback

Troque o código por tokens. O Authlib valida a resposta, o state, o verifier do PKCE e o ID token.

@app.route("/callback")
def callback():
    tokens = oauth.idp.authorize_access_token()

    claims = tokens["userinfo"]  # validated ID-token claims
    session["user"] = {"sub": claims["sub"], "name": claims.get("name"), "email": claims.get("email")}
    session["id_token"] = tokens["id_token"]

    # Optional: fetch additional claims from UserInfo
    # userinfo = oauth.idp.userinfo(token=tokens)

    return redirect("/")

5. Terminar sessão

Envie o utilizador para o endpoint de end session e limpe depois a sua própria sessão.

from urllib.parse import urlencode

@app.route("/logout")
def logout():
    metadata = oauth.idp.load_server_metadata()
    params = urlencode({
        "id_token_hint": session.get("id_token", ""),
        "post_logout_redirect_uri": "https://app.example.com/",
    })
    session.clear()
    return redirect(f"{metadata['end_session_endpoint']}?{params}")

Registe https://app.example.com/ como post-logout redirect URI na aplicação, da mesma forma que regista um redirect URI.

Resolução de problemas

  • A chamada de discovery falha. Confirme que https://<your-domain>/.well-known/openid-configuration é acessível a partir do seu servidor e que o domínio é o host de início de sessão da sua instância.
  • mismatching_state no callback. A sessão que iniciou a autenticação tem de ser a mesma que processa o callback. Garanta que os cookies de sessão sobrevivem ao redirecionamento (SameSite correto e, em produção, cookies secure sobre HTTPS) e que a secret_key é idêntica em todos os workers; uma chave aleatória por worker quebra silenciosamente a sessão em cada redirecionamento.
  • Nunca é devolvido um refresh token. Inclua offline_access no scope e confirme que a aplicação está configurada para receber refresh tokens.

Passos seguintes

Nesta página