# Backend Python / Flask

Aggiungere l'accesso a un'app Python Flask utilizzando la libreria Authlib e il flusso Authorization Code con PKCE.

Questa guida aggiunge l'accesso OIDC a un'app Flask utilizzando [Authlib](https://docs.authlib.org/en/latest/client/flask.html), che si occupa di discovery, PKCE e validazione dei token. Presuppone un client **confidential** (un backend in grado di custodire un secret).

Chi non ha ancora registrato un'applicazione può consultare [Prima di iniziare](https://dts-identity.com/it/docs/quickstarts.md#before-you-start). Per il protocollo sottostante, vedere [OpenID Connect (Authorization Code + PKCE)](https://dts-identity.com/it/docs/quickstarts/oidc-authorization-code.md).

## 1. Installare le dipendenze

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

## 2. Configurare il client

```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
    },
)
```

Mantenere `OIDC_CLIENT_ID` e `OIDC_CLIENT_SECRET` nell'ambiente, mai nel controllo di versione.

## 3. Avviare l'accesso

Authlib costruisce l'URL di autorizzazione con una challenge PKCE e uno `state`, li memorizza entrambi nella sessione e reindirizza il 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)
```

Il `redirect_uri` deve corrispondere esattamente a un valore registrato sull'applicazione.

## 4. Gestire il callback

Scambiare il code con i token. Authlib si occupa di validare la risposta, lo `state`, il verifier PKCE e l'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. Disconnettersi

Inviare l'utente all'endpoint di end session, quindi azzerare la propria sessione.

```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}")
```

Registrare `https://app.example.com/` come post-logout redirect URI sull'applicazione, nello stesso modo in cui si registra un redirect URI.

## Risoluzione dei problemi

- **La chiamata di discovery non riesce.** Verificare che `https://<your-domain>/.well-known/openid-configuration` sia raggiungibile dal proprio server e che il dominio sia l'host di accesso della propria istanza.
- **`mismatching_state` nel callback.** La sessione che ha avviato l'accesso deve essere la stessa che gestisce il callback. Assicurarsi che i cookie di sessione sopravvivano al redirect (`SameSite` corretto e, in produzione, cookie `secure` su HTTPS) e che `secret_key` sia identica su tutti i worker; una chiave casuale per worker interrompe silenziosamente la sessione a ogni redirect.
- **Non viene mai restituito un refresh token.** Includere `offline_access` nello scope e verificare che l'applicazione sia configurata per ricevere refresh token.

## Passi successivi

- [Applicazione single-page React](https://dts-identity.com/it/docs/quickstarts/react-spa.md) per un client che vive solo nel browser.
- [Proteggere un'API](https://dts-identity.com/it/docs/quickstarts/protect-an-api.md) per validare gli access token nella propria API Python.
- [Applicazioni](https://dts-identity.com/it/docs/integrations/applications.md) per rivedere le durate dei token e le altre impostazioni del client.
