Connexion avec Sangho (OAuth2)
« Se connecter avec Sangho » permet à votre plateforme d’authentifier ses utilisateurs via leur compte Sangho existant, sans jamais manipuler leur mot de passe — comme « Se connecter avec Google ». Sangho agit comme fournisseur d’identité (code d’autorisation OAuth2 + PKCE obligatoire), distinct des clés API pk_/sk_ qui authentifient vos appels serveur vers l’API Sangho.
Hôte canonique : accounts.sangho.com. Les intégrations déjà configurées sur dash.sangho.com/o/… continuent de fonctionner (rétrocompatibilité), mais toute nouvelle intégration doit utiliser accounts.sangho.com.
1. Créer un client OAuth
Un client OAuth se crée en self-service depuis l’onglet Clés API de votre dashboard Sangho : nom, description, URI de redirection. Le client_secret (SANGHO_SECRET côté votre plateforme) n’est affiché qu’une seule fois à la création — conservez-le immédiatement dans votre gestion de secrets.
Un client créé en self-service n’est jamais « de confiance a priori » : l’écran de consentement Sangho s’affiche systématiquement à chaque connexion d’un nouvel utilisateur. C’est attendu, pas une erreur de configuration.
2. Flux d’autorisation (PKCE obligatoire)
| Étape | Endpoint | Description |
|---|---|---|
| 1. Rediriger l'utilisateur | GET /o/authorize/ | Avec client_id, redirect_uri, response_type=code, scope, state, code_challenge, code_challenge_method=S256 |
| 2. Consentement | — | L'utilisateur se connecte à Sangho (si besoin) puis autorise votre application |
| 3. Callback | votre redirect_uri | Sangho redirige avec ?code=…&state=… (vérifiez state contre CSRF) |
| 4. Échanger le code | POST /o/token/ | grant_type=authorization_code, code, redirect_uri, client_id, code_verifier |
| 5. Rafraîchir | POST /o/token/ | grant_type=refresh_token, refresh_token, client_id |
| 6. Révoquer | POST /o/revoke_token/ | token, client_id — invalide un access ou refresh token |
PKCE (code_challenge/code_verifier, méthode S256) est obligatoire, y compris pour un client confidentiel côté serveur — la requête est rejetée sans lui. Les access tokens expirent après 1 heure, les refresh tokens après 30 jours.
3. Scopes et profil utilisateur
| Scope | Revendications renvoyées par /o/userinfo/ |
|---|---|
| profile | name, given_name, family_name, picture |
| email, email_verified |
GET /o/userinfo/ (avec Authorization: Bearer <access_token>) renvoie toujours sub : un identifiant stable et opaque (UUID), jamais l’adresse e-mail — utilisez-le comme clé d’identité pérenne côté plateforme, l’e-mail pouvant changer.
4. Révocation et suspension
Un propriétaire de client OAuth peut suspendre son client depuis le dashboard (suspend/activate) : plus aucune nouvelle autorisation ni échange de token n’est accepté pour ce client_id, mais un access token déjà émis reste valable jusqu’à expiration naturelle (pas de révocation rétroactive immédiate) — comme la plupart des fournisseurs OAuth2.