laravel-connect/README.md

laravel-connect

Ce package permet d'utiliser Bluesquare Connect comme méthode d'authentification grâce au protocole OAuth 2.0.

Installation

Mettre à jour composer.json avec :

"repositories": [
    {
        "type": "vcs",
        "url": "https://git.bluesquare.io/bluesquare/laravel-connect"
    }
]

Puis installer le package :

composer require bluesquare/laravel-connect "2.1"

Mettre à jour le .env avec les identifiants du client OAuth généré sur Bluesquare Connect :

BCONNECT_CLIENT_ID=your_client_id
BCONNECT_CLIENT_SECRET=your_client_secret
BCONNECT_REDIRECT="${APP_URL}/connect/callback"

Et optionnellement :

# 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 :

use Bluesquare\Connect\Facades\Connect;

Connect::routes();

Si Blade est utilisé, un bouton "Connexion via Bluesquare Connect" peut être ajouté ainsi :

<x-connect-button/>

Sinon il suffit de rediriger vers /connect/authorize pour déclencher le flux.

Configuration personnalisée de User

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

Pour utiliser l'identifiant par défaut, il convient d'ajouter cette colonne à User :

$table->string('connect_id')->nullable();

Ou alors, et pour revenir à l'utilisation de email comme identifiant :

use HasConnectData;

protected $connectIdentifier = 'email';

Ensuite, pour injecter automatiquement les données fournies par Bluesquare Connect (liste indicative ci-dessous) :

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 :

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 :

$table->text('connect_access_token')->nullable();
$table->text('connect_refresh_token')->nullable();
$table->datetime('connect_expires_at')->nullable();

Il est ensuite possible de mettre à jour les utilisateurs avec cette commande :

php artisan connect:sync

Mais aussi de seulement mettre à jour les tokens avant expiration avec cette commande :

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

Pour terminer, il suffit d'ajouter le trait HasConnectWebhook à User.

Configurer le comportement du webhook

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).

Il est recommandé de personnaliser le cas de la suppression en ajoutant la fonction suivante à User.php :

public function onConnectDelete(array $data)
{
    // Optionnel : avec cette fonction on met à jour une dernière fois l'utilisateur
    $this->onConnectUpdate($data);

    //...supprimer l'utilisateur comme souhaité...
}

Les autres cas peuvent être personnalisés avec ces différentes fonctions :

public function onConnectCreate(array $data);
public function onConnectUpdate(array $data);
public function onConnectRestore(array $data);

Données fournies par Bluesquare Connect

• 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