laravel-connect/README.md

208 lines
6.7 KiB
Markdown
Raw Permalink Normal View History

2020-05-12 16:56:50 +02:00
# laravel-connect
2020-05-11 16:26:34 +02:00
2022-05-20 11:18:09 +02:00
Ce package permet d'utiliser [Bluesquare Connect](https://connect.bluesquare.io) comme méthode d'authentification grâce au protocole OAuth 2.0.
2020-05-11 16:26:34 +02:00
## Installation
2022-05-20 11:18:09 +02:00
Mettre à jour `composer.json` avec :
2020-05-11 16:26:34 +02:00
```
"repositories": [
2020-05-12 16:56:50 +02:00
{
"type": "vcs",
"url": "https://git.bluesquare.io/bluesquare/laravel-connect"
}
2020-05-11 16:26:34 +02:00
]
```
2022-05-20 11:18:09 +02:00
Puis installer le package :
2020-05-11 16:26:34 +02:00
```bash
2022-06-02 10:12:47 +02:00
composer require bluesquare/laravel-connect "2.1"
2020-05-11 16:26:34 +02:00
```
2022-05-20 11:18:09 +02:00
Mettre à jour le `.env` avec les identifiants du client OAuth généré sur [Bluesquare Connect](https://connect.bluesquare.io) :
2020-05-11 16:26:34 +02:00
```bash
2020-05-12 16:56:50 +02:00
BCONNECT_CLIENT_ID=your_client_id
BCONNECT_CLIENT_SECRET=your_client_secret
2022-05-20 11:18:09 +02:00
BCONNECT_REDIRECT="${APP_URL}/connect/callback"
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
Et optionnellement :
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
```bash
# URL du serveur OAuth
BCONNECT_URL=https://connect.bluesquare.io
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
# Données demandées (scopes)
BCONNECT_USER_SCOPES=profile
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
Il est possible de modifier d'autres comportements, à savoir :
- Model utilisateur utilisé (par défaut `App\Models\User`)
- URL de connexion via Bluesquare Connect (par défaut `/connect/authorize`)
- Remember me : garder la session active post-connexion (par défaut `true`)
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
Pour cela, il suffit de modifier le fichier `config/bconnect.php` généré via la commande `php artisan vendor:publish`.
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
### Configuration minimale de `User`
2020-05-12 16:59:38 +02:00
2022-05-20 11:18:09 +02:00
À moins d'utiliser le trait `HasConnectData` (voir ci-dessous), il faut s'assurer que toutes les colonnes autres que `email` sont `nullable` dans la table `users` (y compris `password`).
La colonne `email` est alors utilisée comme identifiant de référence par Bluesquare Connect.
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
### Connexion
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
Pour activer la connexion via Bluesquare Connect, il faut mettre à jour `web.php` en y ajoutant :
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
```php
use Bluesquare\Connect\Facades\Connect;
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
Connect::routes();
```
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
Si Blade est utilisé, un bouton "Connexion via Bluesquare Connect" peut être ajouté ainsi :
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
```blade
<x-connect-button/>
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
Sinon il suffit de rediriger vers `/connect/authorize` pour déclencher le flux.
2020-05-13 12:38:26 +02:00
2022-05-20 11:18:09 +02:00
### Configuration personnalisée de `User`
2020-05-13 12:38:26 +02:00
2022-05-20 11:18:09 +02:00
Le trait `HasConnectData` permet d'exploiter au maximum les données fournies par Bluesquare Connect. Notamment :
- Définir quelle colonne sert d'identifiant unique (par défaut `connect_id`) avec `$connectIdentifier` ;
- Définir quelles données sont à injectées dans le Model à la connexion, avec `$connectFillable`
2020-05-13 12:38:26 +02:00
2022-05-20 11:18:09 +02:00
Pour utiliser l'identifiant par défaut, il convient d'ajouter cette colonne à `User` :
2020-05-11 16:26:34 +02:00
2022-05-20 11:18:09 +02:00
```php
$table->string('connect_id')->nullable();
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
Ou alors, et pour revenir à l'utilisation de `email` comme identifiant :
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
```php
use HasConnectData;
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
protected $connectIdentifier = 'email';
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
Ensuite, pour injecter automatiquement les données fournies par Bluesquare Connect (liste indicative ci-dessous) :
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
```php
protected $connectFillable = [
'name',
'email'
];
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
Il est possible de mapper les colonnes avec des noms différents et des valeurs par defaut, voire même d'injecter dans plusieurs colonnes, comme ceci :
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
```php
protected $connectIdentifier = ['connect_id' => 'oauth_id'];
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
protected $connectFillable = [
'name' => 'fullname|Anonymous',
'firstname' => ['firstname', 'nickname'],
'email' => 'email_address',
'group' => 'role|user'
];
```
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
## Synchronisation des données _(optionnel)_
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
Par défaut, les données des utilisateurs sont mises à jour à chaque nouvelle connexion.
Cependant, deux méthodes peuvent être utilisées pour conserver les données de tous les utilisateurs à jour sans reconnexion.
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
### 1. Synchronisation passive
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
Le trait `HasConnectTokens` permet de conserver les tokens OAuth pour une utilisation future (par exemple, pour synchroniser les utilisateurs périodiquement).
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
Avant tout, il faut ajouter ces colonnes dans la table `users` :
```php
$table->text('connect_access_token')->nullable();
$table->text('connect_refresh_token')->nullable();
$table->datetime('connect_expires_at')->nullable();
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
Il est ensuite possible de mettre à jour les utilisateurs avec cette commande :
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
```bash
php artisan connect:sync
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
Mais aussi de seulement mettre à jour les tokens avant expiration avec cette commande :
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
```bash
php artisan connect:refresh
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
Il est conseillé d'appeler ces commandes périodiquement via une tâche CRON dans `Console/Kernel.php`.
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
### 2. Synchronisation active (webhook)
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
Avant tout, il est requis de créer une `App` liée au client utilisé sur Bluesquare Connect, et d'en activer le webhook.
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
Ensuite, pour pouvoir utiliser le webhook, il faut ajouter ceci à `routes/api.php`:
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
use Bluesquare\Connect\Facades\Connect;
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
Connect::apiRoutes();
```
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
Cela va permettre à Bluesquare Connect d'appeler cette URL à chaque modification d'un utilisateur :
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
https://your-app.com/api/connect/webhook
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
Pour terminer, il suffit d'ajouter le trait `HasConnectWebhook` à `User`.
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
#### Configurer le comportement du webhook
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
Par défaut, le webhook se comporte ainsi :
- Lorsqu'un utilisateur est créé, il est inséré dans `users` comme à la première connexion ;
- Lorsqu'un utilisateur est mis à jour, il est modifié comme à chaque connexion / synchronisation ;
- Lorsqu'un utilisateur est supprimé, deux cas se présentent :
- si `User` implémente `SoftDeletes`, alors le webhook fait appel à `$user->delete()` ;
- si `SoftDeletes` est absent, alors la session utilisateur est simplement expirée en repassant `remember_token` à `null`.
- Si l'utilisateur est restauré, deux cas se présentent :
- si `User` implémente `SoftDeletes` et que l'utilisateur est bien présent en base de données, alors le webhook fait appel à `$user->restore()` ;
- si `SoftDeletes` est absent ou que l'utilisateur n'existe pas, alors on recréé l'utilisateur (s'il existe, il est simplement mis à jour).
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
Il est recommandé de personnaliser le cas de la suppression en ajoutant la fonction suivante à `User.php` :
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
```php
public function onConnectDelete(array $data)
{
// Optionnel : avec cette fonction on met à jour une dernière fois l'utilisateur
$this->onConnectUpdate($data);
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
//...supprimer l'utilisateur comme souhaité...
}
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
Les autres cas peuvent être personnalisés avec ces différentes fonctions :
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
```php
public function onConnectCreate(array $data);
public function onConnectUpdate(array $data);
public function onConnectRestore(array $data);
2020-05-12 16:56:50 +02:00
```
2022-05-20 11:18:09 +02:00
## Données fournies par Bluesquare Connect
2020-05-12 16:56:50 +02:00
2022-05-20 11:18:09 +02:00
- `id` et `connect_id` : identifiant unique de l'utilisateur
- `email` : adresse e-mail
- `name` : nom complet
- `firstname` et `nickname` : prénom
- `lastname` : nom de famille
- `avatar`, `picture` et `profile_picture` : URL de la photo de profil
- `company` : entreprise
- `job` : mêtier exercé dans l'entreprise
- `group` : rôle principal (les groupes sont personnalisées pour chaque App sur Bluesquare Connect)
- `groups` : tableau contenant tous les rôles associés à l'utilisateur