214 lines
4.0 KiB
Markdown
214 lines
4.0 KiB
Markdown
# laravel-connect
|
|
|
|
The Bluesquare Connect package allows you to use its OAuth server and sync its resources.
|
|
|
|
## Installation
|
|
|
|
Update your `composer.json`:
|
|
|
|
```
|
|
"repositories": [
|
|
{
|
|
"type": "vcs",
|
|
"url": "https://git.bluesquare.io/bluesquare/laravel-connect"
|
|
}
|
|
]
|
|
```
|
|
|
|
Install the package:
|
|
|
|
```bash
|
|
composer require bluesquare/laravel-connect "1.2"
|
|
```
|
|
|
|
Finally, update your `.env` with your client's credentials:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```blade
|
|
<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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
php artisan vendor:publish
|
|
```
|