@@ -24,12 +24,74 @@ oAuth (ne me demandez pas, je ne les ai plus !), vous pouvez continuer.
### Exemple
Un exemple d'utilisation de la librairie est dans le dossier `html`. Si vous
êtes pressé, vous pouvez vous baser dessus !
êtes pressé, vous pouvez vous baser dessus ! Notez que les fichiers dans `lib`
doivent également être présents sur votre serveur, mais que le serveur web doit
servir les fichiers dans `html` à la racine de votre serveur.
Si vous utilisez docker, vous pouvez lancer le site de démonstration avec la
commande suivante :
```
docker run -p 80:80 -v `pwd`:/var/www php:apache
```
Le site est alors accessible à l'adresse http://127.0.0.1
### Utilisation
Vous devez commencer par initialiser le client oAuth en l'initialisant (`$oauth = new oAuth2(...)`).
Le constructeur requiert tous les paramètres suivants (dans cet ordre) :
*`host` : Adresse du serveur oAuth - `https://auth.viarezo.fr` pour le serveur ViaRézo
*`clientId` : Client ID de votre client oAuth
*`clientSecret` : Client Secret de votre client oAuth
*`scope` : Liste du/des scope(s) à demander au serveur oAuth lors de la connexion. Généralement, vous n'avez besoin que de `default`
Le scope `linkcs:read` peut être nécessaire pour aller chercher des informations sur LinkCS.
*`authURL` : Chemin à ajouter derrière `host` pour l'autorisation (_authorize URL_) - `/oauth/authorize` pour le serveur ViaRézo
*`tokenURL` : Chemin à ajouter derrière `host` pour obtenir un token oAuth - `/oauth/token` pour le serveur ViaRézo
*`userDataURL` : Adresse appelée par le client oAuth une fois un token récupéré pour obtenir plus d'informations sur l'utilisateur.
Les informations récupérées sont accessibles avec la fonction `getUserData`. `/api/user/show/me` pour le serveur ViaRézo
*`myURL` : Adresse du serveur - passée au serveur oAuth lors de la connexion. Le serveur oAuth utilise ce nom
d'hôte lors de la redirection un fois la redirection terminée. En test, `http://localhost` peut faire l'affaire.
*`redirectURL` : Adresse du script gérant la connexion sur notre serveur. Généralement, c'est `/auth.php`.
Les valeurs `myURL` et `redirectURL` sont concaténées pour obtenir l'URL de redirection envoyée au serveur oAuth, vers
laquelle il redirige les utilisateurs une fois connectés. Cette adresse doit donc être dans les URLs de redirection
autorisées de votre client oAuth.
Sur n'importe quelle page, avant d'afficher du texte (les "Headers" ne doivent pas avoir été envoyés), vous pouvez
appeler `checkLogin` sur l'objet créé (`$oauth->checkLogin()`). Cette fonction retourne `true` si l'utilisateur est
connecté avec le client oAuth, `false` sinon. Si votre page nécessite une authentification, vous devez alors appeler
la fonction `forceLogin()` pour initier le processus de connexion.
Le script à l'adresse `myURL``redirectURL` doit appeler la fonction `forceLogin()` qui effectue la suite du processus
de connexion (vérification des informations renvoyées par le serveur oAuth, récupération du token et des informations
utlisateur). Si tout se passe bien, le script redirige l'utilisateur vers la page ayant appelé `forceLogin`. Sinon,
un message d'erreur est affiché. Pour un exemple de script redirigeant vers l'accueil si l'utilisateur est déjà connecté,
voir le fichier `auth.php` dans le dossier `html`.
Une fois l'utilisateur connecté (ce que vous ne manquez pas de vérifier avec `checkLogin` sur chaque page), vous pouvez
récupérer les informations de son profil oAuth avec la fonction `getUserData()`. Ces informations sont mises en cache
dans la session PHP à la connexion, vous n'avez donc pas besoin de les stocker dans la session vous-même.
Les champs que vous pouvez récupérer (à passer en paramètre à `getUserData`) sont :
*`id` : Identifiant unique oAuth
*`firstName` : Prénom
*`lastName` : Nom
*`gender` : Genre
*`login` : Nom d'utilisateur ViaRézo
*`email` : Adresse e-mail étudiant
*`birthDate` : Date de naissance - peut être passée au constructeur [DateTime](https://secure.php.net/manual/fr/class.datetime.php) pour une manipulation plus facile.
*`promo` : Promotion de l'étudiant (ne tient généralement pas compte des redoublements ou césures)
*`photo` : Adresse de la photo de l'étudiant - à ajouter après `https://auth.viarezo.fr/media/` pour récupérer la photo de l'étudiant.
*`updatedAt` : Date de dernière mise à jour du profil.
*`personType` : `STUDENT_CENTRALE` si l'étudiant est de Centrale Paris par exemple
*`roles` : Rôles de l'utilisateur à ViaRézo - généralement, vous préférerez utiliser `hasRole` pour savoir si l'utilisateur un rôle donné.
Appeler la fonction `getUserData` retourne un tableau avec tous les champs disponibles. Appeler la fonction avec
un champ inexistant retourne `null`.
Si vous voulez déconnecter l'utilisateur, il vous suffit de détruire la session PHP avec `session_destroy()`. Le script
`logout.php` montre un exemple avec également une déconnexion sur le serveur oAuth.
## Contributions
Vos contributions sont les bienvenues ! Il y a notamment un peu de travail
sur :
* la récupération de données avec des services externes (LinkCS)
Vos contributions sont les bienvenues ! Il y a notamment un peu de travail sur :
* la récupération de données avec des services externes (notamment les informations LinkCS)
* le rafraîchissement du token (refresh token - chemin /refresh)
* des tests unitaires si ça vous chante
* PHPDoc pour documenter les fonctions de la librairie
