README

Introduction

The ISS (International Space Station) aims to be a space station (client) of connection between the microservices of its ecosystem and the authentication and permissions microservice of the user that here is called in the script as Hub.permissions modules / microservices (Hub)

Installation

You can install the package via composer:

composer require bildvitta/iss-sdk:dev-develop

For everything to work perfectly in addition to having the settings file published in your application, run the command below:

php artisan hub:install

Configuration

This is the contents of the published config file:

return [
    'base_uri' => env('MS_HUB_BASE_URI', 'https://api-dev-hub.nave.dev'),

    'front_uri' => env('MS_HUB_FRONT_URI', 'https://develop.hub.nave.dev'),

    'prefix' => env('MS_HUB_API_PREFIX', '/api'),

    'model_user' => '\App\Entities\User',

    'model_company' => '\BildVitta\Hub\Entities\HubCompany::class',

    'programatic_access' => [
        'client_id' => env('HUB_PROGRAMMATIC_CLIENT'),
        'client_secret' => env('HUB_PROGRAMMATIC_SECRET')
    ],

    'oauth' => [
        'client_id' => env('HUB_CLIENT_ID', ''),
        'client_secret' => env('HUB_CLIENT_SECRET', ''),
        'redirect' => env('HUB_REDIRECT_URI', ''),
        'scopes' => env('HUB_SCOPE', 'profile'),

        'authorize_uri' => '/auth/authorize',
        'token_uri' => '/oauth/token',
        'userinfo_uri' => '/users/me'
    ]
];

With the configuration file hub.php published in your configuration folder it is necessary to create environment variables in your .env file:

MS_HUB_BASE_URI="https://api-dev-hub.nave.dev"

MS_HUB_PREFIX="/api"

Change permission and role model from spatie/laravel-permissions

You should change the default spatie/laravel-permissions models to ours, as we have some substantial changes to the use of Role and Permission.

// config/permission.php

return [
    'models' = [
        'permission' => \BildVitta\Hub\Entities\HubPermission::class,
        'role' => \BildVitta\Hub\Entities\HubRole::class,
    ]
];

If you already have a change to these models, just extend our classes to have the correct functionalities.

Add Trait on User Model

And remember to add the BildVitta\Hub\Traits\User\HasCompanyLinks Trait in the Users model.

// \App\Models\User

use BildVitta\Hub\Traits\User\HasCompanyLinks;

class User extends Authenticatable
{
    use HasCompanyLinks;
    ...
}

Remembering that this trait already has Spatie\Permission\Traits\HasRoles by default, so you can remove the Spatie\Permission\Traits\HasRoles trait from your user model.

Usage

All requests made to the ISS Service will return an instance of \Illuminate\Http\Client\Response, which implements the PHP ArrayAccess interface, allowing you to access JSON response data directly in the response

This also means that a variety of methods that can be used to inspect the response, follow some below:

$response = Hub::setToken('jwt')->auth()->permissions();

$response->body(); // string;
$response->json(); // array|mixed;
$response->collect(); // Illuminate\Support\Collection;
$response->status(); // int;
$response->ok(); // bool;
$response->successful(); // bool;
$response->failed(); // bool;
$response->serverError(); // bool;
$response->clientError(); // bool;
$response->header('content-type'); // string;
$response->headers(); // array;

Initialize ISS Service.

As there are several ways to program, there are also several ways to start the ISS Service.

Below are some ways to start the Service.

$token = 'jwt';

$hub = app('hub', [$token]); // instance 2
$hub = app('hub')->setToken($token); // instance 1
$hub = new \BildVitta\Hub\Hub($token); // instance 3
$hub = (new \BildVitta\Hub\Hub())->setToken($token); // instance 4
$hub = BildVitta\Hub\Facades\Hub::setToken($token); // instance 1

Authenticating User

To authenticate the Hub user in your module, it is necessary to use the middleware hub.auth = \ BildVitta \ Hub \ Middleware \ AuthenticateHubMiddleware.

It will validate the token and create, if it does not exist, the user of the token in its user table.

Route::middleware('hub.auth')->get('/users/me', function () {
    return auth()->user()->toArray();
});

When we installed the package, we created the hub_uuid column in your user table.

Tf it is not possible to authenticate, the middleware will return 401.

User Authenticated

To access the token's user data directly, there is the \BildVitta\Hub\Contracts\Resources\AuthResourceContract interface

Check Token

It is verified whether the token passed by parameter or previously loaded in the ISS Service is valid.

Example of use:

try {
    Hub::auth()->check('jwt');
} catch (RequestException $requestException) {
    throw new Exception('invalid token');
}

Get Permissions

It is possible to obtain ALL the permissions of the token uploaded to the ISS Service.

Example of use:

try {
    $permissions = Hub::setToken('jwt')->auth()->permissions()['results']; // Implements `ArrayAccess`
    
    foreach ($permissions as $permission) {
        #TODO
    }
} catch (RequestException $requestException) {
    #TODO
}

Adding permission scope to entity listing.

Now we have added a scope that filters by the permission level of the logged in user. To use it is very simple, just add in the global scopes the PermissionScope class passing the permission that the user has to have, and then the magic happens ;D

Code example:

use BildVitta\Hub\Scopes\PermissionScope;

$query = RealEstateDevelopment::query();
$query->withGlobalScope('permission', new PermissionScope('real_estate_developments.show'));

$count = $query->count();
$query->pagination();

return (new RealEstateDevelopmentResource('index', $query->get()))->count($count);

Remembering that the scope name has to be permission, if not, it doesn't work <3

Notifications

Make sure the BroadcastServiceProvider is enabled in config/app.php

Add the ABLY_KEY key as an environment variable (ask your coordinator for this key)

ABLY_KEY=your-ably-key

Then, set the BROADCAST_CONNECTION environment variable to ably in your application's .env file:

BROADCAST_CONNECTION=ably

Check the routes/channels.php file if the private channel authentication route is correct.

use Illuminate\Support\Facades\Broadcast;

Broadcast::channel('notifications.{uuid}', function ($user, $uuid) {
    return (string) $user->uuid === (string) $uuid;
});

Ensure that the $user->uuid is the same as that used in the hub, otherwise it may result in a 403 in this private channel authentication api.

To finish, go to the BroadcastServiceProvider file and change it to this code.

Broadcast::routes([
    'middleware' => ['hub.check'],
    'prefix' => 'api',
]);

Ensure that the $user->uuid is the same as that used in the hub, otherwise it may result in a 403 in this private channel authentication api.

To finish, go to the BroadcastServiceProvider file and change it to this code.

Broadcast::routes([
    'middleware' => ['hub.check'],
    'prefix' => 'api',
]);

New Per-Company Permissioning (v2)

To use the new permissioning method, you must follow these steps and make the necessary changes for the reality of each project.

First, in the config/permissions.php file you must change the register_permission_check_method attribute from true to false, as we will control the permissioning method manually.

Example:

// config/permission.php
return [
    ...
    'register_permission_check_method' => false
    ...
];

After leaving it as false, in requests or policies the following change must be made (if applicable) to the ->can method that exists within the user (or the model that extends HasRoles or HasPermissions)

If the permission for the screen in question needs to be per company, you must pass the company's uuid as the second parameter of the can() method. Example:

$user->can('users.show', 'company-uuid');

The code above will check if the 'users.show' permission exists within the company passed as a parameter. If it does, it returns true, otherwise false.

If you have screens that do not require permission per company, but cases where, if the person has permission regardless of the link, just leave the can() method as it is, for example:

$user->can('users.show');

In the code above, it will search for this permission in any of the user's existing links, if found it returns true otherwise false.

Testing

coming soon...

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Credits

License

The MIT License (MIT). Please see License File for more information.

bildvitta / iss-sdk

Maintainers

Details