sangho-oauth (Python)

« Se connecter avec Sangho » — Authorization Code + PKCE (RFC 7636, méthode S256).

Librairie distincte du SDK de paiement (sangho) : OAuth identifie une personne, le SDK encaisse un paiement. N'installez ceci que pour un bouton « Se connecter avec Sangho ».

Deux couches :

1. sangho_oauth.SanghoOAuthClient — client framework-agnostique (PKCE, échange de code, refresh, révocation, userinfo), sans Django. Utilisable avec Flask, FastAPI, un script…
2. sangho_oauth.providers.sangho — provider django-allauth, pour les projets Django, comme le provider GitHub ou Google. Il s'appuie sur la machinerie d'allauth (état anti-CSRF, PKCE, complete_social_login).

Python 3.10 à 3.14 ; Django 4.2, 5.2 et 6.x ; django-allauth 65. Testé localement sur les cinq versions de Python (3.14 en préversion 3.14.0rc2), Django 4.2 (Python 3.10), 5.2 (3.10) et 6.1 (3.14) ; la CI (.github/workflows/ci.yml) couvre les combinaisons Python/Django supportées.

Installation

pip install sangho-oauth              # client seul
pip install "sangho-oauth[allauth]"   # + provider django-allauth

Prérequis chez Sangho

Créez un client OAuth dans le tableau de bord Sangho (Clés API → Clients OAuth) et enregistrez l'URL de redirection exacte de votre site. Vous obtenez un client_id et un client_secret (affiché une seule fois). Le client est confidentiel : le secret est obligatoire pour l'échange du code, le refresh et la révocation, et ne doit jamais atteindre un navigateur.

Django (django-allauth)

# settings.py
INSTALLED_APPS += [
    "allauth", "allauth.account", "allauth.socialaccount",
    "sangho_oauth.providers.sangho",
]

SOCIALACCOUNT_PROVIDERS = {
    "sangho": {
        "APPS": [{
            "client_id": env("SANGHO_CLIENT_ID"),
            "secret": env("SANGHO_CLIENT_SECRET"),
            "key": "",
        }],
        "BASE_URL": "https://accounts.sangho.ga",   # hôte OAuth de Sangho (une base terminée par /o est acceptée)
        "REDIRECT_URI": "",                          # voir ci-dessous
        "TIMEOUT": 15,                               # secondes (jeton, profil)
        "VERIFY_SSL": True,                          # jamais False en production
    },
}

# urls.py
urlpatterns += [path("accounts/", include("allauth.urls"))]

<a href="{% url 'sangho_login' %}">Se connecter avec Sangho</a>

Les réglages sont lus à l'exécution. Le délai et la vérification TLS sont appliqués par la bibliothèque : aucun adaptateur social personnalisé n'est nécessaire dans votre projet.

Vérifications de configuration

python manage.py check (et check --deploy) signale : sangho_oauth.W001 (aucun client_id), E002 (BASE_URL non https), E003 (VERIFY_SSL=False), E004 (REDIRECT_URI non https) — les trois erreurs sont ignorées quand DEBUG=True.

Journaux

Les échecs sont journalisés avec leur cause réelle dans le logger sangho_oauth (ex. Sangho token request refused: HTTP 401 invalid_client), là où allauth n'affiche qu'un message générique. Aucun secret, code ni jeton n'est écrit dans les journaux.

Sécurité

• L'identifiant de compte est sub (stable, opaque), jamais l'e-mail.
• L'e-mail n'est marqué vérifié que si Sangho renvoie email_verified=true. Ne liez pas automatiquement un compte existant par e-mail (EMAIL_AUTHENTICATION: False, valeur par défaut d'allauth pour ce provider).
• PKCE est toujours actif ; le serveur de Sangho l'exige.

Usage direct (sans Django)

from sangho_oauth import SanghoOAuthClient

sangho = SanghoOAuthClient(
    client_id="…", client_secret="…",
    redirect_uri="https://monapp.com/auth/sangho/callback",
    base_url="https://accounts.sangho.ga",
)

# 1. Redirection
auth_request = sangho.create_authorization_request()
session["oauth_code_verifier"] = auth_request.code_verifier
session["oauth_state"] = auth_request.state
return redirect(auth_request.url)

# 2. Callback
tokens = sangho.exchange_code(
    code=request.args["code"],
    code_verifier=session.pop("oauth_code_verifier"),
    received_state=request.args["state"],
    expected_state=session.pop("oauth_state"),
)
profile = sangho.get_user_info(tokens.access_token)   # profile["sub"] = identifiant stable à stocker

SanghoOAuthClient se ferme avec close() ou comme gestionnaire de contexte ; verify= et http_client= (un httpx.Client) permettent un CA personnalisé, un proxy ou un transport de test.

Erreurs

from sangho_oauth import SanghoOAuthError

try:
    tokens = sangho.exchange_code(...)
except SanghoOAuthError as e:
    # e.code : "state_mismatch" (CSRF ou session expirée : ne PAS poursuivre), "invalid_client" (secret refusé),
    #          "invalid_grant" (code expiré ou déjà utilisé), "network_error", "invalid_response"…
    logger.error("Sangho OAuth: %s — %s", e.code, e.description)

Scopes

sub est toujours renvoyé.

Développement et publication

Un Makefile regroupe toutes les commandes (make help). Il appelle scripts/dev.py (Python pur, sans shell POSIX) : ça fonctionne donc sous Windows/PowerShell comme sous Linux et macOS, et python scripts/dev.py <commande> marche sans make. Les environnements virtuels sont créés avec uv s'il est installé, sinon python -m venv (ou le lanceur py -3.X sous Windows). Si python n'est pas le bon exécutable : make test PYTHON=python3.

make install                        # venv .venv + dépendances de dev
make test                           # pytest
make lint                           # ruff
make matrix                         # tests sur Python 3.10 → 3.14 (un venv .venv-X.Y par version, nécessite uv)
make venv PY=python3.14 VENV=.venv314   # venv pour une autre version de Python
make test DJANGO=">=4.2,<5.0"       # tests avec une version de Django précise
make check                          # lint + tests + build + twine check
make release                        # tag vX.Y.Z → .github/workflows/release.yml publie sur PyPI

La publication utilise le trusted publishing de PyPI (aucun jeton à stocker) : configurez-le une fois sur PyPI pour ce dépôt (environnement pypi). À défaut : make publish avec TWINE_USERNAME=__token__ et TWINE_PASSWORD.