Update documentation

Author: avvertix

README.md

@@ -3,15 +3,35 @@
 
 Add registration and log in to you application via third party identity providers (e.g. Gitlab, Facebook, ...).
 
-The package is compatible with the [Laravel Socialite](https://laravel.com/docs/8.x/socialite) providers 
-as well as the community driven [Socialite Providers](https://socialiteproviders.com/) website.
+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.
 
-> Requires **Laravel >= 7.20** and **PHP >= 7.2**
+The package is compatible with [Laravel Socialite](https://laravel.com/docs/socialite) providers 
+as well as the community driven [Socialite Providers](https://socialiteproviders.com/).
+
+**features**
+
+- Handle user registration via third party providers;
+- Handle user log in via third party providers;
+- Customizable controllers, migration and models that will live in your application namespace;
+- Save identity and token inside the database, using
+  [encryption and pseudoanonimization](#how-data-is-stored-in-the-database);
+- Provide login/register button as Blade component;
+- Support all [Laravel Socialite](https://laravel.com/docs/socialite)
+  and [Socialite Providers](https://socialiteproviders.com/);
+- Add custom providers.
+
+**requirements**
+
+`oneofftech/laravel-connect-identity` requires **Laravel >= 7.20** and **PHP >= 7.2**.
 
 > **The package is currently a Work In Progress.** The api might change without notice so it is not yet 
 suitable for production environments.
 
-## Installation
+## Getting started
+
+### Installation
 
 You can install this package via Composer by running this command in your terminal in the root of your project:
 
@@ -20,17 +40,21 @@ composer require oneofftech/laravel-connect-identity
 ```
 
 > The service provider `Oneofftech\Identities\IdentitiesServiceProvider::class` 
-> is automatically registered as part of the Laravel service discovery
+> is automatically registered as part of the Laravel service discovery.
 
-## Configuration
+### Generate migrations, controllers and models
 
-Scaffold the controllers, migrations 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
 ```
 
-Add the WithIdentities trait to your User model to use the `identities` relationship.
+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.
 
 ```php
 // ...
@@ -39,33 +63,26 @@ use Oneofftech\Identities\WithIdentities;
 
 class User extends Authenticatable
 {
-    use Notifiable, WithIdentities;
+    use WithIdentities;
 
     // ...
 }
 ```
 
+> If your application has a different namespace than `App` please refer 
+to [Using a personalized application namespace](#using-a-personalized-application-namespace)
+for additional required setup actions.
 
-Register the events to your events service provider.
+### Configure the Socialite providers
 
-> This will register the SocialiteWasCalled event for the Gitlab and Dropbox 
-providers that are included by default. If you are not using those providers
-this step is optional.
+Before using an identity provider, e.g. `facebook`, `google`, `github`, `gitlab`,
+configure the required options inside the `services` configuration file.
 
-```
-\Oneofftech\Identities\Facades\Identity::events();
-```
-
-    public function boot()
-    {
-        parent::boot();
-
-        \Oneofftech\Identities\Facades\Identity::events();
-    }
-
-
-Inserire i valori nei services secondo le specifiche di Laravel Socialite
+> To see the driver specific configuration please refer to 
+[Laravel's documentation](https://laravel.com/docs/socialite) or the
+[Socialite Providers documentation](https://socialiteproviders.com/).
 
+> The `redirect` url configuration is not required as the redirect url is set automatically.
 
 ```php
     'gitlab' => [
@@ -76,13 +93,67 @@ Inserire i valori nei services secondo le specifiche di Laravel Socialite
     ],
 ```
 
+If you are using one of the community maintained [Socialite Providers](https://socialiteproviders.com/)
+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`.
+
+```php
+
+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.
+
+```html
+<x-oneofftech-identity-link 
+    action="register" 
+    provider="gitlab" 
+    class="button button--primary" />
+```
+
+The available `action`s are `login` 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](https://laravel.com/docs/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.
+
+```html
+@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;
+To do so add the following lines in your `AppServiceProvider`;
 
 ```php
 
@@ -93,21 +164,81 @@ class AppServiceProvider extends ServiceProvider
 
     public function boot()
     {
-        Identity::useNamespace("KBox\\");
-        Identity::useIdentityModel("KBox\\Identity");
-        Identity::useUserModel("KBox\\User");
+        Identity::useNamespace("My\\Namespace\\");
+        Identity::useIdentityModel("My\\Namespace\\Identity");
+        Identity::useUserModel("My\\Namespace\\User");
 
         // ...
     }
 }
 ```
 
-The `ui:identities` command is namespace aware.
+### 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.
+
+```php
+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.
+
+```html
+<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](https://laravel.com/docs/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](https://divinglaravel.com/app_key-is-a-secret-heres-what-its-used-for-how-you-can-rotate-it)
+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 a login or a registration process as part of the token update.
+
 
+## Contributing
 
-## Basic Usage
+All types of contribution are accepted, bug-fix, documentation updates, new features!
 
-...
+We will have a contributing page soon, but meanwhile you can submit Pull Requests.
 
 ## License