From de0f263a46304b0b6170a02fabb032e11aad41a3 Mon Sep 17 00:00:00 2001 From: Maxime Renou Date: Fri, 20 May 2022 11:18:09 +0200 Subject: [PATCH] update: README.md --- README.md | 285 ++++++++++++++++++++++++++++++-------------------------------- 1 file changed, 140 insertions(+), 145 deletions(-) diff --git a/README.md b/README.md index 6438a89..457cd84 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ # laravel-connect -The Bluesquare Connect package allows you to use its OAuth server and sync its resources. +Ce package permet d'utiliser [Bluesquare Connect](https://connect.bluesquare.io) comme méthode d'authentification grâce au protocole OAuth 2.0. ## Installation -Update your `composer.json`: +Mettre à jour `composer.json` avec : ``` "repositories": [ @@ -15,199 +15,194 @@ Update your `composer.json`: ] ``` -Install the package: +Puis installer le package : ```bash -composer require bluesquare/laravel-connect "1.2" +composer require bluesquare/laravel-connect "2.0" ``` -Finally, update your `.env` with your client's credentials: +Mettre à jour le `.env` avec les identifiants du client OAuth généré sur [Bluesquare Connect](https://connect.bluesquare.io) : ```bash BCONNECT_CLIENT_ID=your_client_id BCONNECT_CLIENT_SECRET=your_client_secret -BCONNECT_REDIRECT=http://localhost:8000/connect/callback +BCONNECT_REDIRECT="${APP_URL}/connect/callback" ``` -### Sign in with Bluesquare Connect +Et optionnellement : -Follow there instructions to add Bluesquare Connect's authentication to your app. - -Update your `routes/web.php`: +```bash +# URL du serveur OAuth +BCONNECT_URL=https://connect.bluesquare.io +# Données demandées (scopes) +BCONNECT_USER_SCOPES=profile ``` + +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`) + +Pour cela, il suffit de modifier le fichier `config/bconnect.php` généré via la commande `php artisan vendor:publish`. + +### Configuration minimale de `User` + +À 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. + +### Connexion + +Pour activer la connexion via Bluesquare Connect, il faut mettre à jour `web.php` en y ajoutant : + +```php +use Bluesquare\Connect\Facades\Connect; + Connect::routes(); ``` -Add the "Sign in with Bluesquare Connect" button in your blade login page: +Si Blade est utilisé, un bouton "Connexion via Bluesquare Connect" peut être ajouté ainsi : ```blade ``` -Make sure that the `password` column of users table is nullable. +Sinon il suffit de rediriger vers `/connect/authorize` pour déclencher le flux. -#### Keep user tokens (optional) +### Configuration personnalisée de `User` -First, make sure that your model implements `HasConnectTokens` trait. +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` -Then, add the following columns to your table: +Pour utiliser l'identifiant par défaut, il convient d'ajouter cette colonne à `User` : +```php +$table->string('connect_id')->nullable(); ``` + +Ou alors, et pour revenir à l'utilisation de `email` comme identifiant : + +```php +use HasConnectData; + +protected $connectIdentifier = 'email'; +``` + +Ensuite, pour injecter automatiquement les données fournies par Bluesquare Connect (liste indicative ci-dessous) : + +```php +protected $connectFillable = [ + 'name', + 'email' +]; +``` + +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 : + +```php +protected $connectIdentifier = ['connect_id' => 'oauth_id']; + +protected $connectFillable = [ + 'name' => 'fullname|Anonymous', + 'firstname' => ['firstname', 'nickname'], + 'email' => 'email_address', + 'group' => 'role|user' +]; +``` + +## Synchronisation des données _(optionnel)_ + +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. + +### 1. Synchronisation passive + +Le trait `HasConnectTokens` permet de conserver les tokens OAuth pour une utilisation future (par exemple, pour synchroniser les utilisateurs périodiquement). + +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(); +$table->datetime('connect_expires_at')->nullable(); ``` -### Database syncing - -Follow these instructions to sync your database with Bluesquare Connect. - -In your `AppServiceProvider`, specify in the `boot()` function which entities you want to sync: - -``` -$connect->setSynchronized([ - Role::class, - Company::class, - Team::class, - User::class, - UserTeam::class -]); -``` - -Your models must use `HasConnectSync` trait. This trait allows you to customize the syncing behavior. - -You also need to add this column to your synced tables: - -``` -$table->unsignedBigInteger('connect_resource_id')->unique(); -``` - -_You can customize this column name and the syncing behavior in your model. Take a look at `HasConnectSync`._ - -Finally, use this command to sync everything: +Il est ensuite possible de mettre à jour les utilisateurs avec cette commande : ```bash php artisan connect:sync ``` -#### Live updates (optional) +Mais aussi de seulement mettre à jour les tokens avant expiration avec cette commande : -First, configure a webhook on Bluesquare Connect : +```bash +php artisan connect:refresh +``` + +Il est conseillé d'appeler ces commandes périodiquement via une tâche CRON dans `Console/Kernel.php`. + +### 2. Synchronisation active (webhook) + +Avant tout, il est requis de créer une `App` liée au client utilisé sur Bluesquare Connect, et d'en activer le webhook. + +Ensuite, pour pouvoir utiliser le webhook, il faut ajouter ceci à `routes/api.php`: + +``` +use Bluesquare\Connect\Facades\Connect; + +Connect::apiRoutes(); +``` + +Cela va permettre à Bluesquare Connect d'appeler cette URL à chaque modification d'un utilisateur : ``` https://your-app.com/api/connect/webhook ``` -Then, update your `routes/api.php`: +Pour terminer, il suffit d'ajouter le trait `HasConnectWebhook` à `User`. -``` -Connect::apiRoutes(); -``` +#### Configurer le comportement du webhook -## Advanced usage +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). -### OAuth (sign in) +Il est recommandé de personnaliser le cas de la suppression en ajoutant la fonction suivante à `User.php` : -#### Authorization - -Redirect to Bluesquare Connect authorization page: - -``` -public function authorize(Connect $connect) +```php +public function onConnectDelete(array $data) { - return $connect->redirect($optional_custom_state); + // Optionnel : avec cette fonction on met à jour une dernière fois l'utilisateur + $this->onConnectUpdate($data); + + //...supprimer l'utilisateur comme souhaité... } ``` -#### Authorization callback +Les autres cas peuvent être personnalisés avec ces différentes fonctions : -Auto: check state, login and redirect - -``` -public function callback(Request $request, Connect $connect) -{ - return $connect->loginFromCallback($request, $optional_redirect_to); -} +```php +public function onConnectCreate(array $data); +public function onConnectUpdate(array $data); +public function onConnectRestore(array $data); ``` -Manual: check state +## Données fournies par Bluesquare Connect -``` -public function callback(Request $request, Connect $connect) -{ - $valid = $connect->checkState($request); - // ... -} -``` - -#### Tokens management - -``` -// Retrieve tokens from an authorization code -$connect_data = $connect->getAccessTokenFromAuthorizationCode($code); - -// Retrieve tokens from a refresh token -$connect_data = $connect->getAccessTokenFromRefreshToken($connect_data['refresh_token']); - -// With HasConnectTokens trait: get your local user tokens -$connect->getUserAccessToken($user); -``` - -#### User data - -``` -// Retrieve user data from an access token -$user_data = $connect->getUserData($connect_data['access_token']); - -// Example: find the corresponding user in your database -$user = User::where('email', $user_data['email'])->first(); -``` - -### OAuth (client) - -#### Token management - -``` -// Get an access token -$connect->getAccessToken(); - -// Delete the current access token from cache -$connect->deleteAccessToken(); -``` - -#### API resources - -``` -// Fetch all users -$connect->getAll('User'); - -// Fetch an user -$connect->get('User', 1); -``` - -#### Syncing - -``` -// Sync everything -$optional_resource_types = ['User', ...]; -$connect->syncAll($optional_resource_types); - -// Sync a specific resource -$connect->sync('User', 1); -``` - -### Webhook - -``` -// Handle a webhook request -$connect->handleWebhook($request); -``` - -### Configuration - -Publish our config file (`config/bconnect.php`) to customize the package configuration: - -```bash -php artisan vendor:publish -``` +- `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 \ No newline at end of file