Merge branch 'master' into 1676-feature-federation-technical-concept

README.md

@@ -9,21 +9,26 @@ The Corona crisis has fundamentally changed our world within a very short time.
 The dominant financial system threatens to fail around the globe, followed by mass insolvencies, record unemployment and abject poverty. Only with a sustainable new monetary system can humanity master these challenges of the 21st century. The Gradido Academy for Bionic Economy has developed such a system.
 
 Find out more about the Project on its [Website](https://gradido.net/). It is offering vast resources about the idea. The remaining document will discuss the gradido software only.
+
 ## Software requirements
 
 Currently we only support `docker` install instructions to run all services, since many different programming languages and frameworks are used.
 
-- [docker](https://www.docker.com/) 
+- [docker](https://www.docker.com/)
 - [docker-compose]
+- [yarn](https://phoenixnap.com/kb/yarn-windows)
 
 ### For Arch Linux
+
 Install the required packages:
+
 ```bash
 sudo pacman -S docker
 sudo pacman -S docker-compose
 ```
 
-Add group `docker` and then your user to it in order to allow you to run docker without sudo 
+Add group `docker` and then your user to it in order to allow you to run docker without sudo
+
 ```bash
 sudo groupadd docker # may already exist `groupadd: group 'docker' already exists`
 sudo usermod -aG docker $USER
@@ -31,26 +36,58 @@ groups # verify you have the group (requires relog)
 ```
 
 Start the docker service:
+
 ```bash
 sudo systemctrl start docker
 ```
 
+### For Windows
+
+#### docker
+
+The installation of dockers depends on your selected product package from the [dockers page](https://www.docker.com/). For windows the product *docker desktop* will be the choice. Please follow the installation instruction of your selected product.
+
+##### known problems
+
+* In case the docker desktop will not start correctly because of previous docker installations, then please clean the used directories of previous docker installation - `C:\Users` -  before you retry starting docker desktop. For further problems executing docker desktop please take a look in this description "[logs and trouble shooting](https://docs.docker.com/desktop/windows/troubleshoot/)"
+* In case your docker desktop installation causes high memory consumption per vmmem process, then please take a look at this description "[vmmen process consuming too much memory (Docker Desktop)](https://dev.to/tallesl/vmmen-process-consuming-too-much-memory-docker-desktop-273p)"
+
+#### yarn
+
+For the Gradido build process the yarn package manager will be used. Please download and install [yarn for windows](https://phoenixnap.com/kb/yarn-windows) by following the instructions there.
+
 ## How to run?
 
+As soon as the software requirements are fulfilled and a docker installation is up and running then open a powershell on Windows or an other commandline prompt on Linux.
+
+Create and navigate to the directory, where you want to create the Gradido runtime environment.
+
+```
+mkdir \Gradido
+cd \Gradido
+```
+
 ### 1. Clone Sources
+
 Clone the repo and pull all submodules
+
 ```bash
 git clone git@github.com:gradido/gradido.git
 git submodule update --recursive --init
 ```
 
 ### 2. Run docker-compose
-Run docker-compose to bring up the development environment 
+
+Run docker-compose to bring up the development environment
+
 ```bash
 docker-compose up
 ```
+
 ### Additional Build options
+
 If you want to build for production you can do this aswell:
+
 ```bash
 docker-compose -f docker-compose.yml up
 ```
@@ -73,6 +110,7 @@ A release is tagged on Github by its version number and published as github rele
 Each release is accompanied with release notes automatically generated from the git log which is available as [CHANGELOG.md](./CHANGELOG.md).
 
 To generate the Changelog and set a new Version you should use the following commands in the main folder
+
 ```bash
 git fetch --all
 yarn release
@@ -85,10 +123,10 @@ Note: The Changelog will be regenerated with all tags on release on the external
 
 ## Troubleshooting
 
-| Problem | Issue | Solution | Description |
+| Problem                                          | Issue                                                | Solution                                                                      | Description                                                                 |
-| ------- | ----- | -------- | ----------- |
+| ------------------------------------------------ | ---------------------------------------------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
 | docker-compose raises database connection errors | [#1062](https://github.com/gradido/gradido/issues/1062) | End `ctrl+c` and restart the `docker-compose up` after a successful build | Several Database connection related errors occur in the docker-compose log. |
-| Wallet page is empty | [#1063](https://github.com/gradido/gradido/issues/1063) | Accept Cookies and Local Storage in your Browser | The page stays empty when navigating to [http://localhost/](http://localhost/) |
+| Wallet page is empty                             | [#1063](https://github.com/gradido/gradido/issues/1063) | Accept Cookies and Local Storage in your Browser                              | The page stays empty when navigating to[http://localhost/](http://localhost/)  |
 
 ## Useful Links
 

docu/Concepts/TechnicalRequirements/UC_Introduction_of_Gradido-ID.md

@@ -0,0 +1,140 @@
+# Introduction of Gradido-ID
+
+## Motivation
+
+To introduce the Gradido-ID base on the requirement to identify an user account per technical key instead of using an email-address. Such a technical key ensures an exact identification of an user account without giving detailed information for possible missusage.
+
+Additionally the Gradido-ID allows to administrade any user account data like changing the email address or define several email addresses without any side effects on the identification of the user account.
+
+## Definition
+
+The formalized definition of the Gradido-ID can be found in the document [BenutzerVerwaltung#Gradido-ID](../BusinessRequirements/BenutzerVerwaltung#Gradido-ID).
+
+## Steps of Introduction
+
+To Introduce the Gradido-ID there are several steps necessary. The first step is to define a proper database schema with additional columns and tables followed by data migration steps to add or initialize the new columns and tables by keeping valid data at all.
+
+The second step is to decribe all concerning business logic processes, which have to be adapted by introducing the Gradido-ID.
+
+### Database-Schema
+
+#### Users-Table
+
+The entity users has to be changed by adding the following columns.
+
+| Column                   | Type   | Description                                                                            |
+| ------------------------ | ------ | -------------------------------------------------------------------------------------- |
+| gradidoID                | String | technical unique key of the user as UUID (version 4)                                   |
+| alias                    | String | a business unique key of the user                                                      |
+| passphraseEncryptionType | int    | defines the type of encrypting the passphrase: 1 = email (default), 2 = gradidoID, ... |
+| emailID                  | int    | technical foreign key to the new entity Contact                                        |
+
+##### Email vs emailID
+
+The existing column `email`, will now be changed to the primary email contact, which will be stored as a contact entry in the new `UserContacts` table. It is necessary to decide if the content of the `email `will be changed to the foreign key `emailID `to the contact entry with the email address or if the email itself will be kept as a denormalized and duplicate value in the `users `table.
+
+The preferred and proper solution will be to add a new column `Users.emailId `as foreign key to the `UsersContact `entry and delete the `Users.email` column after the migration of the email address in the `UsersContact `table.
+
+#### new UserContacts-Table
+
+A new entity `UserContacts `is introduced to store several contacts of different types like email, telephone or other kinds of contact addresses.
+
+| Column          | Type   | Description                                                                                                                                                            |
+| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| id              | int    | the technical key of a contact entity                                                                                                                                  |
+| type            | int    | Defines the type of contact entry as enum: Email, Phone, etc                                                                                                           |
+| usersID         | int    | Defines the foreign key to the `Users` table                                                                                                                         |
+| email           | String | defines the address of a contact entry of type Email                                                                                                                   |
+| phone           | String | defines the address of a contact entry of type Phone                                                                                                                   |
+| contactChannels | String | define the contact channel as comma separated list for which this entry is confirmed by the user e.g. main contact (default), infomail, contracting, advertisings, ... |
+
+### Database-Migration
+
+After the adaption of the database schema and to keep valid consistent data, there must be several steps of data migration to initialize the new and changed columns and tables.
+
+#### Initialize GradidoID
+
+In a one-time migration create for each entry of the `Users `tabel an unique UUID (version4).
+
+#### Primary Email Contact
+
+In a one-time migration read for each entry of the `Users `table the `Users.id` and `Users.email` and create for it a new entry in the `UsersContact `table, by initializing the contact-values with:
+
+* id = new technical key
+* type = Enum-Email
+* userID = `Users.id`
+* email = `Users.email`
+* phone = null
+* usedChannel = Enum-"main contact"
+
+and update the `Users `entry with `Users.emailId = UsersContact.Id` and `Users.passphraseEncryptionType = 1`
+
+After this one-time migration the column `Users.email` can be deleted.
+
+### Adaption of BusinessLogic
+
+The following logic or business processes has to be adapted for introducing the Gradido-ID
+
+#### Read-Write Access of Users-Table especially Email
+
+The ORM mapping has to be adapted to the changed and new database schema.
+
+#### Registration Process
+
+The logic of the registration process has to be adapted by
+
+* initializing the `Users.userID` with a unique UUID
+* creating a new `UsersContact `entry with the given email address and *maincontact* as `usedChannel `
+* set `emailID `in the `Users `table as foreign key to the new `UsersContact `entry
+* set `Users.passphraseEncrpytionType = 2` and encrypt the passphrase with the `Users.userID` instead of the `UsersContact.email`
+
+#### Login Process
+
+The logic of the login process has to be adapted by
+
+* search the users data by reading the `Users `and the `UsersContact` table with the email (or alias as soon as the user can maintain his profil with an alias)   as input
+* depending on the `Users.passphraseEncryptionType` decrypt the stored password
+  * = 1 :  with the email
+  * = 2 : with the userID
+
+#### Password En/Decryption
+
+The logic of the password en/decryption has to be adapted by encapsulate the logic to be controlled with an input parameter. The input parameter can be the email or the userID.
+
+#### Change Password Process
+
+The logic of change password has to be adapted by
+
+* if the `Users.passphraseEncryptionType` = 1, then
+
+  * read the users email address from the `UsersContact `table
+  * give the email address as input for the password decryption of the existing password
+  * use the `Users.userID` as input for the password encryption fo the new password
+  * change the `Users.passphraseEnrycptionType` to the new value =2
+* if the `Users.passphraseEncryptionType` = 2, then
+
+  * give the `Users.userID` as input for the password decryption of the existing password
+  * use the `Users.userID` as input for the password encryption fo the new password
+
+#### Search- and Access Logic
+
+A new logic has to be introduced to search the user identity per different input values. That means searching the user data must be possible by
+
+* searching per email (only with maincontact as contactchannel)
+* searching per userID
+* searching per alias
+
+#### Identity-Mapping
+
+A new mapping logic will be necessary to allow using unmigrated APIs like GDT-servers api. So it must be possible to give this identity-mapping logic the following input to get the respective output:
+
+* email -> userID
+* email -> alias
+* userID -> email
+* userID -> alias
+* alias -> email
+* alias -> userID
+
+#### GDT-Access
+
+To use the GDT-servers api the used identifier for GDT has to be switch from email to userID.