swift_companion/docs/pedagogie/etape-02-oauth-intra.md

É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

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 → 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/) :

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	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/ :

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 :

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 :

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 (à rédiger quand l’étape 2 est validée) : vue 1 — champ login, appel API, erreurs 404 / réseau.

Documentation API utile :

• apidoc
• User : GET /v2/users/:id ou recherche par login (voir doc)