# 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](https://docs.authlib.org/en/latest/client/flask.html), 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](https://dts-identity.com/pt/docs/quickstarts.md#before-you-start). Para o protocolo subjacente, consulte [OpenID Connect (Authorization Code + PKCE)](https://dts-identity.com/pt/docs/quickstarts/oidc-authorization-code.md).

## 1. Instalar as dependências

```bash
pip install flask authlib requests
```

## 2. Configurar o cliente

```python
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:

```python
@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.

```python
@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.

```python
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

- [Aplicação de página única em React](https://dts-identity.com/pt/docs/quickstarts/react-spa.md) para um cliente exclusivamente de browser.
- [Proteger uma API](https://dts-identity.com/pt/docs/quickstarts/protect-an-api.md), para validar access tokens na sua própria API em Python.
- [Aplicações](https://dts-identity.com/pt/docs/integrations/applications.md) para rever os tempos de vida dos tokens e outras definições do cliente.
