laravel-connect

The Bluesquare Connect package allows you to use its OAuth server and sync its resources.

Installation

Update your composer.json:

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

Install the package:

composer update bluesquare/laravel-connect

Finally, update your .env with your client's credentials:

BCONNECT_CLIENT_ID=your_client_id
BCONNECT_CLIENT_SECRET=your_client_secret
BCONNECT_REDIRECT=http://localhost:8000/connect/callback

Sign in with Bluesquare Connect

Follow there instructions to add Bluesquare Connect's authentication to your app.

Update your routes/web.php:

Connect::routes();

Add the "Sign in with Bluesquare Connect" button in your blade login page:

<x-connect-button/>

Make sure that the password column of users table is nullable.

Keep user tokens (optional)

First, make sure that your model implements HasConnectTokens trait.

Then, add the following columns to your table:

$table->text('connect_access_token')->nullable();
$table->text('connect_refresh_token')->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:

php artisan connect:sync

Live updates (optional)

First, configure a webhook on Bluesquare Connect :

https://your-app.com/api/connect/webhook

Then, update your routes/api.php:

Connect::apiRoutes();

Advanced usage

OAuth (sign in)

Authorization

Redirect to Bluesquare Connect authorization page:

public function authorize(Connect $connect)
{
    return $connect->redirect($optional_custom_state);
}

Authorization callback

Auto: check state, login and redirect

public function callback(Request $request, Connect $connect)
{
    return $connect->loginFromCallback($request, $optional_redirect_to);
}

Manual: check state

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:

php artisan vendor:publish