docs(auth): spec connexion LinkedIn (OIDC)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Colin Maudry
@@ -0,0 +1,145 @@
|
|||||||
|
# Connexion avec LinkedIn (OIDC) — Design
|
||||||
|
|
||||||
|
Date : 2026-06-24
|
||||||
|
Branche : `dev`
|
||||||
|
|
||||||
|
## Objectif
|
||||||
|
|
||||||
|
Permettre aux utilisateurs de créer un compte / se connecter à decp.info via
|
||||||
|
LinkedIn, comme les boutons « Se connecter avec Google/GitHub » d'autres sites.
|
||||||
|
Beaucoup d'utilisateurs viennent de LinkedIn ; réduire la friction d'inscription.
|
||||||
|
|
||||||
|
Portée : **LinkedIn uniquement** (pas d'abstraction multi-provider pour
|
||||||
|
l'instant). Code simple et direct.
|
||||||
|
|
||||||
|
## Mécanisme
|
||||||
|
|
||||||
|
LinkedIn fournit _« Sign In with LinkedIn using OpenID Connect »_ (OIDC).
|
||||||
|
On utilise la bibliothèque **Authlib** (intégration Flask) : elle gère la
|
||||||
|
découverte OIDC, la redirection, l'échange `code → token`, la validation du
|
||||||
|
token et le `state` anti-CSRF. Scopes demandés : `openid profile email`.
|
||||||
|
|
||||||
|
On ne stocke que l'**email** (comme l'auth existante), pas le nom ni la photo.
|
||||||
|
|
||||||
|
## Flux
|
||||||
|
|
||||||
|
1. L'utilisateur clique sur **« Connexion avec LinkedIn »** (présent sur
|
||||||
|
`/connexion` et `/inscription`).
|
||||||
|
2. `GET /auth/linkedin` → Authlib redirige vers LinkedIn.
|
||||||
|
3. L'utilisateur autorise → LinkedIn redirige vers
|
||||||
|
`GET /auth/linkedin/callback?code=...&state=...`.
|
||||||
|
4. Authlib échange le `code`, valide le token, expose l'identité OIDC :
|
||||||
|
`sub`, `email`, `email_verified`.
|
||||||
|
5. Résolution / liaison du compte (voir ci-dessous).
|
||||||
|
6. `login_user(user, remember=True)` → redirection vers `/compte/admin`
|
||||||
|
(ou le `next` validé via `safe_next`).
|
||||||
|
|
||||||
|
## Schéma (migrations additives, dans `db._migrate`)
|
||||||
|
|
||||||
|
- `users.password_hash` devient **nullable** : un compte créé via LinkedIn n'a
|
||||||
|
pas de mot de passe. Un tel utilisateur pourra s'en créer un plus tard via
|
||||||
|
le flux « mot de passe oublié ».
|
||||||
|
|
||||||
|
- SQLite ne permet pas de retirer un `NOT NULL` par `ALTER COLUMN`. La
|
||||||
|
migration recrée la table `users` sans la contrainte `NOT NULL` sur
|
||||||
|
`password_hash` si elle est encore présente (copie des données,
|
||||||
|
`PRAGMA table_info` pour détecter l'état). Les nouvelles installations
|
||||||
|
créent directement le schéma sans `NOT NULL` sur `password_hash`.
|
||||||
|
|
||||||
|
- Nouvelle table :
|
||||||
|
|
||||||
|
```sql
|
||||||
|
CREATE TABLE IF NOT EXISTS oauth_identities (
|
||||||
|
provider TEXT NOT NULL, -- 'linkedin'
|
||||||
|
subject TEXT NOT NULL, -- le 'sub' OIDC stable
|
||||||
|
user_id INTEGER NOT NULL,
|
||||||
|
created_at TEXT NOT NULL,
|
||||||
|
PRIMARY KEY (provider, subject),
|
||||||
|
FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
## Résolution / liaison du compte (au callback)
|
||||||
|
|
||||||
|
Logique extraite dans une fonction testable `resolve_oauth_user(provider, subject, email, email_verified)` :
|
||||||
|
|
||||||
|
1. Si `(linkedin, sub)` existe dans `oauth_identities` → on connecte le
|
||||||
|
`user_id` lié.
|
||||||
|
2. Sinon, si un `user` existe déjà avec cet **email** → **liaison
|
||||||
|
automatique** : insert dans `oauth_identities`, et si `email_verified`
|
||||||
|
était `0`, on le passe à `1` (LinkedIn garantit un email vérifié).
|
||||||
|
3. Sinon → **création** d'un nouvel utilisateur (`email`,
|
||||||
|
`password_hash = NULL`, `email_verified = 1`) + insert `oauth_identities`.
|
||||||
|
Aucun email de vérification Brevo n'est envoyé.
|
||||||
|
|
||||||
|
Décision produit : la liaison par email est automatique (l'email LinkedIn est
|
||||||
|
vérifié, le risque est faible).
|
||||||
|
|
||||||
|
## Fichiers touchés
|
||||||
|
|
||||||
|
- **`src/auth/oauth.py`** (nouveau) : `init_oauth(app)` — initialise Authlib et
|
||||||
|
enregistre le provider LinkedIn (config OIDC, client id/secret depuis l'env).
|
||||||
|
- **`src/auth/routes.py`** : deux routes
|
||||||
|
- `GET /auth/linkedin` — démarre le flux (`authorize_redirect`).
|
||||||
|
- `GET /auth/linkedin/callback` — récupère l'identité, appelle
|
||||||
|
`resolve_oauth_user`, `login_user`, redirige.
|
||||||
|
- `resolve_oauth_user(...)` — logique de résolution (testable).
|
||||||
|
- **`src/auth/db.py`** : schéma `oauth_identities`, migration `password_hash`
|
||||||
|
nullable, helpers `get_oauth_identity(provider, subject)`,
|
||||||
|
`link_oauth_identity(provider, subject, user_id)`,
|
||||||
|
`create_oauth_user(email)`.
|
||||||
|
- **`src/auth/setup.py`** : appel à `init_oauth(app)`.
|
||||||
|
- **`src/pages/connexion.py`** et **`src/pages/inscription.py`** : bouton
|
||||||
|
« Connexion avec LinkedIn ».
|
||||||
|
- **`pyproject.toml`** : ajout de la dépendance `authlib`.
|
||||||
|
- **`.template.env`** : `LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`.
|
||||||
|
|
||||||
|
## UI du bouton
|
||||||
|
|
||||||
|
- Libellé : **« Connexion avec LinkedIn »**.
|
||||||
|
- Style : texte blanc sur fond `rgb(10, 102, 194)` (bleu de marque LinkedIn,
|
||||||
|
`#0A66C2`).
|
||||||
|
- Un lien `<a href="/auth/linkedin">` (initiation par GET, pas de CSRF requis),
|
||||||
|
placé sous le formulaire email/mot de passe, séparé par un « ou ».
|
||||||
|
- Présent sur `/connexion` et `/inscription`.
|
||||||
|
|
||||||
|
## Gestion d'erreurs
|
||||||
|
|
||||||
|
- L'utilisateur annule / refuse sur LinkedIn → `/connexion?error=oauth_cancelled`.
|
||||||
|
- Échange de token échoué, ou pas d'email renvoyé par LinkedIn →
|
||||||
|
`/connexion?error=oauth_failed` (loggé via `logger.exception`).
|
||||||
|
- `state` invalide → détecté par Authlib → `oauth_failed`.
|
||||||
|
- Messages ajoutés dans `ERROR_MESSAGES` de `connexion.py`.
|
||||||
|
|
||||||
|
## Tests (dans `tests/auth/`)
|
||||||
|
|
||||||
|
Sans appel réseau réel à LinkedIn : on **mocke** le retour `userinfo` /
|
||||||
|
l'identité OIDC exposée par Authlib.
|
||||||
|
|
||||||
|
- `resolve_oauth_user` :
|
||||||
|
- nouvel utilisateur (création + `email_verified = 1`, pas de password).
|
||||||
|
- liaison par email à un compte existant (insert identity, promotion
|
||||||
|
`email_verified`).
|
||||||
|
- identité déjà liée (retour du même `user_id`, pas de doublon).
|
||||||
|
- Migration : `password_hash` accepte `NULL` ; table `oauth_identities` créée.
|
||||||
|
- Helpers db : `get_oauth_identity`, `link_oauth_identity`, `create_oauth_user`.
|
||||||
|
|
||||||
|
## Prérequis hors code (côté admin du projet)
|
||||||
|
|
||||||
|
1. Créer une application sur le **LinkedIn Developer Portal**.
|
||||||
|
2. Activer le produit _« Sign In with LinkedIn using OpenID Connect »_.
|
||||||
|
3. Déclarer les redirect URIs autorisées :
|
||||||
|
- `http://localhost:8050/auth/linkedin/callback` (dev)
|
||||||
|
- `https://test.decp.info/auth/linkedin/callback` (test.decp.info)
|
||||||
|
- `https://decp.info/auth/linkedin/callback` (prod)
|
||||||
|
4. Récupérer le **Client ID** et le **Client Secret**, les renseigner dans
|
||||||
|
`.env` (`LINKEDIN_CLIENT_ID`, `LINKEDIN_CLIENT_SECRET`).
|
||||||
|
|
||||||
|
L'URL de callback est construite à partir de `APP_BASE_URL` (déjà présent dans
|
||||||
|
l'env).
|
||||||
|
|
||||||
|
## Hors périmètre (YAGNI)
|
||||||
|
|
||||||
|
- Google / GitHub / autres providers.
|
||||||
|
- Stockage du nom ou de la photo de profil LinkedIn.
|
||||||
|
- Page de gestion « délier mon compte LinkedIn » (pourra venir plus tard).
|
||||||
Reference in New Issue
Block a user