guidephase3
This commit is contained in:
161
docs/pedagogie/etape-02-oauth-intra.md
Normal file
161
docs/pedagogie/etape-02-oauth-intra.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# Étape 2 — OAuth2 Intra + token unique
|
||||
|
||||
> **Prérequis :** étape 1 OK (`swiftyCompanion/swifty_companion/` créé, `flutter run` fonctionne).
|
||||
|
||||
## Objectif de l’étape
|
||||
|
||||
1. Obtenir un **access token** via **OAuth2 de l’Intra** (pas un token par requête API).
|
||||
2. Stocker les secrets dans **`.env`** (racine `swiftyCompanion/` ou dossier `swifty_companion/` — un seul endroit, documenté dans le README).
|
||||
3. Avoir un **service d’auth** réutilisable pour toutes les futures requêtes `api.intra.42.fr`.
|
||||
|
||||
Les **vues** (recherche login, profil) viennent aux étapes 3–4 ; ici on pose l’authentification API.
|
||||
|
||||
---
|
||||
|
||||
## 2.1 — Vérifier l’app
|
||||
|
||||
```bash
|
||||
cd ~/projets/42School/swifty_companion/swiftyCompanion/swifty_companion
|
||||
flutter pub get
|
||||
flutter run -d <device>
|
||||
```
|
||||
|
||||
L’écran compteur par défaut suffit pour valider l’étape 1.
|
||||
|
||||
---
|
||||
|
||||
## 2.2 — Créer l’application OAuth sur l’Intra
|
||||
|
||||
1. [profile.intra.42.fr/oauth/applications](https://profile.intra.42.fr/oauth/applications) → **New application**.
|
||||
2. Renseigner :
|
||||
- **Name** : ex. `swifty_companion_dev`
|
||||
- **Website** : URL factice ou repo perso (souvent requis)
|
||||
- **Redirect URI** : doit correspondre **exactement** à ce que l’app utilisera (voir 2.3)
|
||||
3. Noter **UID** (= `CLIENT_ID`) et **SECRET** (= `CLIENT_SECRET`).
|
||||
|
||||
Copier `swiftyCompanion/.env.example` → `.env` (même niveau que le README rendu ou dans `swifty_companion/`) :
|
||||
|
||||
```env
|
||||
CLIENT_ID=...
|
||||
CLIENT_SECRET=...
|
||||
REDIRECT_URI=...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2.3 — Choisir le `REDIRECT_URI` (mobile)
|
||||
|
||||
Deux approches courantes en Flutter :
|
||||
|
||||
| Approche | Redirect URI typique | Packages |
|
||||
|----------|----------------------|----------|
|
||||
| **Deep link** (recommandé mobile) | `com.example.swifty_companion://callback` | `flutter_appauth` + config Android/iOS |
|
||||
| **Boucle locale / custom scheme** | variante documentée dans [apidoc OAuth](https://api.intra.42.fr/apidoc) | `url_launcher` + écoute du retour |
|
||||
|
||||
Le même URI doit être :
|
||||
|
||||
- dans le formulaire Intra ;
|
||||
- dans `.env` ;
|
||||
- dans `AndroidManifest` / iOS (intent filter) si deep link.
|
||||
|
||||
**Android** : `applicationId` actuel = `com.example.swifty_companion` (`android/app/build.gradle.kts`).
|
||||
|
||||
Endpoints 42 (référence) :
|
||||
|
||||
| Étape | URL |
|
||||
|-------|-----|
|
||||
| Autorisation | `GET https://api.intra.42.fr/oauth/authorize` |
|
||||
| Token | `POST https://api.intra.42.fr/oauth/token` |
|
||||
| API | `GET https://api.intra.42.fr/v2/...` avec header `Authorization: Bearer <token>` |
|
||||
|
||||
Paramètres authorize usuels : `client_id`, `redirect_uri`, `response_type=code`, `scope=public`.
|
||||
|
||||
---
|
||||
|
||||
## 2.4 — Dépendances Flutter suggérées
|
||||
|
||||
Dans `swifty_companion/` :
|
||||
|
||||
```bash
|
||||
flutter pub add flutter_dotenv http
|
||||
# selon le flux choisi, par ex. :
|
||||
# flutter pub add flutter_appauth
|
||||
```
|
||||
|
||||
| Package | Rôle |
|
||||
|---------|------|
|
||||
| `flutter_dotenv` | Charger `.env` au démarrage |
|
||||
| `http` | Échange code → token + appels API |
|
||||
| `flutter_appauth` | Flux OAuth2 + redirect natif (optionnel mais pratique) |
|
||||
|
||||
---
|
||||
|
||||
## 2.5 — Architecture minimale (fichiers à créer)
|
||||
|
||||
```
|
||||
lib/
|
||||
├── main.dart # dotenv.load + MaterialApp
|
||||
├── config/
|
||||
│ └── env.dart # lecture CLIENT_ID, etc.
|
||||
└── services/
|
||||
└── intra_auth_service.dart # token en mémoire (singleton)
|
||||
```
|
||||
|
||||
Règles sujet :
|
||||
|
||||
- **Un seul token** : le service le garde après le login OAuth ; les futures requêtes réutilisent `getAccessToken()`.
|
||||
- **Ne pas** appeler `/oauth/token` avant chaque `GET /v2/users/...`.
|
||||
|
||||
Pseudo-contrat du service :
|
||||
|
||||
```dart
|
||||
class IntraAuthService {
|
||||
String? _accessToken;
|
||||
String? get accessToken => _accessToken;
|
||||
bool get isAuthenticated => _accessToken != null;
|
||||
|
||||
Future<void> signIn(); // ouvre le flux OAuth, stocke le token
|
||||
Future<String> getValidToken(); // retourne le token (bonus : refresh plus tard)
|
||||
}
|
||||
```
|
||||
|
||||
Test manuel étape 2 : bouton « Se connecter à l’Intra » → navigateur / WebView → retour app → afficher temporairement « Connecté » ou le login `/v2/me`.
|
||||
|
||||
---
|
||||
|
||||
## 2.6 — `.env` et assets
|
||||
|
||||
Si `flutter_dotenv` charge depuis la racine du package Flutter :
|
||||
|
||||
1. Placer `.env` dans `swifty_companion/` (ignoré par git).
|
||||
2. Déclarer dans `pubspec.yaml` :
|
||||
|
||||
```yaml
|
||||
flutter:
|
||||
assets:
|
||||
- .env
|
||||
```
|
||||
|
||||
> En production soutenance : les correcteurs créent **leur** `.env` avec **leur** app OAuth ; ne jamais committer le fichier.
|
||||
|
||||
---
|
||||
|
||||
## 2.7 — Critère « terminé » pour l’étape 2
|
||||
|
||||
| Check | OK si |
|
||||
|-------|--------|
|
||||
| OAuth Intra | Connexion obtient un access token |
|
||||
| Token unique | Plusieurs appels API utilisent le **même** token sans re-login |
|
||||
| Secrets | Uniquement dans `.env`, pas dans le code en dur |
|
||||
| Doc | README rendu rappelle où mettre `.env` et comment lancer l’app |
|
||||
|
||||
---
|
||||
|
||||
## Ensuite — étape 3
|
||||
|
||||
→ [etape-03-vue-recherche.md](etape-03-vue-recherche.md) (à rédiger quand l’étape 2 est validée) : **vue 1** — champ login, appel API, erreurs 404 / réseau.
|
||||
|
||||
Documentation API utile :
|
||||
|
||||
- [apidoc](https://api.intra.42.fr/apidoc)
|
||||
- User : `GET /v2/users/:id` ou recherche par login (voir doc)
|
||||
Reference in New Issue
Block a user