LibPhpOauth
Librairie en PHP pour la connexion avec oAuth, conçue pour fonctionner facilement avec le serveur de ViaRézo
Utilisation
Pour utiliser cette librairie, vous aurez besoin de demander un client oAuth sur https://auth.viarezo.fr . Votre client doit avoir les caractéristiques suivantes :
- Nom : Nom de votre site
- Description : Une courte description de votre app
- Scopes :
default
au minimum. Si vous avez besoin de récupérer des informations de LinkCS, vous aurez certainement besoin de scopes spécifiques. - Méthodes d'authentification :
Authorization Code Grant
etRefresh Token
- URIs de redirection : Mettez deux adresses :
- https://addrese.de.votre.site/auth.php (site de production)
- http://monsite.test/auth.php (site de test - sur votre machine) Pensez à remplacer addresse.de.votre.site par la vraie adresse de votre site. Si vous voulez changer l'adresse de votre site de test, faites-le aussi.
ATTENTION Vos adresses de redirection doivent impérativement se finir
en /auth.php
, sans quoi le serveur oAuth refusera la redirection !
Une fois votre client validé par une personne ayant les droits sur le serveur 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 ! 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 dedefault
Le scopelinkcs:read
peut être nécessaire pour aller chercher des informations sur LinkCS. -
authURL
: Chemin à ajouter derrièrehost
pour l'autorisation (authorize URL) -/oauth/authorize
pour le serveur ViaRézo -
tokenURL
: Chemin à ajouter derrièrehost
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 fonctiongetUserData
./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 valeursmyURL
etredirectURL
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 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èshttps://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 utiliserhasRole
pour savoir si l'utilisateur un rôle donné. Appeler la fonctiongetUserData
retourne un tableau avec tous les champs disponibles. Appeler la fonction avec un champ inexistant retournenull
.
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 (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
Notez que toutes les contributions sont placées de manière irréversible sous licence TLMSVR
(voir le fichier LICENCE
).