From ab289c729814382c9eb6e8c17a5687f9b2fcda63 Mon Sep 17 00:00:00 2001 From: Thomas Pathier <tpxp@live.fr> Date: Wed, 26 Dec 2018 21:37:02 +0100 Subject: [PATCH] Add more documentation about the functions and how they work --- README.md | 70 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 66 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 78ae6c9..60fec13 100644 --- a/README.md +++ b/README.md @@ -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 -- GitLab