README

Add registration and log in to you application via third party identity providers (e.g. Gitlab, Facebook, ...).

While the package provides controllers, models, migrations and routes to handle registration and login actions it does not dictate how the user interface should look and how to validate users' data. It does however provide a starting point that you can customize based on your needs.

The package is compatible with Laravel Socialite providers as well as the community driven Socialite Providers.

features

Handle user registration via third party providers;
Handle user log in via third party providers;
Allow existing user to link a third party identity;
Customizable controllers, migration and models that will live in your application namespace;
Save identity and token inside the database, using encryption and pseudoanonimization;
Provide login/register/connect button as Blade component;
Support all Laravel Socialite and Socialite Providers;
Add custom providers.

requirements

oneofftech/laravel-connect-identity requires Laravel >= 8.0 and PHP >= 7.3.

The package is currently a Work In Progress. The api might change without notice so it is not yet suitable for production environments.

Getting started

Installation

You can install this package via Composer by running this command in your terminal in the root of your project:

composer require oneofftech/laravel-connect-identity

The service provider Oneofftech\Identities\IdentitiesServiceProvider::class is automatically registered as part of the Laravel service discovery.

Generate migrations, controllers and models

The package provides the login and registration features via traits. Once the oneofftech/laravel-connect-identity package has been installed, you can generate the controllers, models and migrations scaffolding using the ui:identities Artisan command:

php artisan ui:identities

Now you can add the WithIdentities trait to your User model. This is required to use the identities relationship required during the registration/login process.

// ...

use Oneofftech\Identities\WithIdentities;

class User extends Authenticatable
{
    use WithIdentities;

    // ...
}

If your application has a different namespace than App please refer to Using a personalized application namespace for additional required setup actions.

Configure the Socialite providers

Before using an identity provider, e.g. facebook, google, github, gitlab, configure the required options inside the services configuration file.

To see the driver specific configuration please refer to Laravel's documentation or the Socialite Providers documentation.

The redirect url configuration is not required as the redirect url is set automatically.

    'gitlab' => [
        'client_id' => env('GITLAB_CLIENT_ID'),
        'client_secret' => env('GITLAB_CLIENT_SECRET'),
        'redirect' => null, // set in the controller no need to specify
        'instance_uri' => env('GITLAB_INSTANCE_URI', 'https://gitlab.com/')
    ],

If you are using one of the community maintained Socialite Providers remember to register their events in your EventsServiceProvider.

If you are not using those providers this step is optional.

oneofftech/laravel-connect-identity provides out-of-the-box support for the gitlab and dropbox driver. If you are using those two you might add the following call to your EventsServiceProvider.

public function boot()
{
    parent::boot();

    \Oneofftech\Identities\Facades\Identity::events();
}

This will register the SocialiteWasCalled event for the Gitlab and Dropbox providers that are included by default.

Include the login and register buttons

oneofftech/laravel-connect-identity does not dictate your User Interface preferences, however we provide a Blade Component to quickly add login and register links/buttons.

<x-oneofftech-identity-link 
    action="register" 
    provider="gitlab" 
    class="button button--primary" />

The available actions are login, connect and register. The provider refers to what identity provider to use, the name of the provider is the same as the Socialite providers' name. See Blade components for more.

In case of errors, mainly connected to validation, you can catch those by looking at the used provider key in the Laravel default ErrorBag.

@error('gitlab')
    <span class="field-error" role="alert">
        {{ $message }}
    </span>
@enderror

Digging Deeper

Using a personalized application namespace

While the ui:identities command is namespace aware some of the runtime configuration is not.

If you are using a custom application namespace instead of the default App, you need to tell which namespace and models to use.

To do so add the following lines in your AppServiceProvider;

use Oneofftech\Identities\Facades\Identity;

class AppServiceProvider extends ServiceProvider
{

    public function boot()
    {
        Identity::useNamespace("My\\Namespace\\");
        Identity::useIdentityModel("My\\Namespace\\Identity");
        Identity::useUserModel("My\\Namespace\\User");

        // ...
    }
}

Passing additional data to the registration

Sometimes you will need additional parameters do create a user after the authorization process on the third party service. To do so you can add as many parameters in the request made to the register route that redirects to the third party service.

By default additional request parameters are guarded and so you have to explicitly tell their name. You can do this by defining an attributes property or an attributes method on the RegisterController that returns an array of strings that represent the name of the allowed parameters.

protected $attributes = ['name'];

protected function attributes()
{
    return  ['name'];
}

The additional attributes will then passed to the validator(array $data) and create(array $data) function defined within the RegisterController.

If you are using the provided IdentityLink Blade component the data should be specified as associative array inside the parameters property.

<x-oneofftech-identity-link 
    action="register" 
    provider="gitlab" 
    :parameters="$arrayOfAdditionalParameters"
    class="button button--primary" />

Where $arrayOfAdditionalParameters is an associative array, e.g. ['invite' => 'token_value'].

How data is stored in the database

Whenever possible data is stored encrypted or in a pseudo-anonymized form.

Encryption works by using the Laravel's Encryption and the configured application key (i.e. APP_KEY). If you want to use a different key use the IDENTITY_KEY environment variable, the used cipher will be the same as configured in app.cipher.

The pseudo-anonymized values are stored as hashes of the original data.

Here is how sensible data is stored:

data	technique
identifier within third party service	pseudo-anonymized
authentication token	encrypted
refresh token	encrypted

If you need to rotate the APP_KEY specify your old key inside OLD_IDENTITY_KEY to be able to still read encrypted values.

Warning as of now no automated job is available for re-encrypting data with the new key. This operation happens during registration or while connecting an identity as part of the token update.

Contributing

Thank you for considering contributing to the Connect Identity for Laravel! You can find how to get started in our contribution guide.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

License

Laravel Connect Identity is licensed under the MIT license.

oneofftech / laravel-connect-identity

Maintainers

Details