Enhanced Login flow for ORCID Authorization feature

epersonregistrations.md

@@ -13,24 +13,168 @@ As we don't have a use case to retrieve an eperson registration based on the ema
 ## Search EPerson registration
 **/api/eperson/registrations/search/findByToken?token=<:token>**
 
-Exposes the registered email address based on the token.  
-Also exposes whether it's a new user registration, or a password reset for an existing user.
+Exposes the registered email address based on the token or the `netId`.
+Also exposes whether it's a new user registration, or a password reset for an existing user. It can expose also `metadata` involved during the registration process, with the overridden values. Lastly, the `registrationType` fields is used to discriminate between the registration flow / procedure.
 
+### Examples
+1. User registration not linked to an eperson:
 ```json
 {
+  "id": 1,
   "email": "[email protected]",
   "user": null,
   "type": "registration"
 }
 ```
-
+2. User registration linked to an eperson:
 ```json
 {
+  "id": 2,
   "email": "[email protected]",
   "user": "028dcbb8-0da2-4122-a0ea-254be49ca107",
   "type": "registration"
 }
 ```
+3. User registration done using **orcid** that didn't provide an email:
+```json
+{
+  "id": 3,
+  "email": null,
+  "user": "028dcbb8-0da2-4122-a0ea-254be49ca107",
+  "type": "registration",
+  "registrationType": "orcid",
+  "netId": "0000-1111-2222-3333",
+  "registrationMetadata": {
+    "eperson.orcid": [
+      {
+        "value": "0000-1111-2222-3333",
+        "language": null,
+        "authority": "",
+        "confidence": -1,
+        "place": -1
+      }
+    ],
+    "eperson.firstname": [
+      {
+        "value": "Power",
+        "language": null,
+        "authority": "",
+        "confidence": -1,
+        "place": -1,
+        "overrides": "Power U."
+      }
+    ],
+    "eperson.lastname": [
+      {
+        "value": "User",
+        "language": null,
+        "authority": "",
+        "confidence": -1,
+        "place": -1
+      }
+    ]
+  }
+}
+```
+> Note that the `registrationMetadata` is filled with metadata coming from the external login provider (i.e. **ORCID**) and enriched with the `overrides` field containg metadata value coming from the linked `user`.
+> 
+> In the previous case the `eperson.firstname` metadata related to the `registration-data` **overrides** the value of the `metadata` previously setted for that related `user` (i.e. `Power U.`).
+
+4. User registration done using **orcid** that provided an email:
+```json
+{
+  "id": 4,
+  "email": "[email protected]",
+  "user": "028dcbb8-0da2-4122-a0ea-254be49ca107",
+  "type": "registration",
+  "registrationType": "orcid",
+  "netId": "0000-1111-2222-3333",
+  "registrationMetadata": {
+    "email": [
+      {
+        "value": "[email protected]",
+        "language": null,
+        "authority": "",
+        "confidence": -1,
+        "place": -1,
+        "overrides": "[email protected]"
+      }
+    ],
+    "eperson.orcid": [
+      {
+        "value": "0000-1111-2222-3333",
+        "language": null,
+        "authority": "",
+        "confidence": -1,
+        "place": -1
+      }
+    ],
+    "eperson.firstname": [
+      {
+        "value": "Power",
+        "language": null,
+        "authority": "",
+        "confidence": -1,
+        "place": -1,
+        "overrides": "Power U."
+      }
+    ],
+    "eperson.lastname": [
+      {
+        "value": "User",
+        "language": null,
+        "authority": "",
+        "confidence": -1,
+        "place": -1
+      }
+    ]
+  }
+}
+```
+> In the previous case the registration has been confirmed by providing a valid email, or just because the orcid login provided an email-account. This email is treated as an additional metadata, but in fact it's just duplicating the `email` field to provide the `overrides` fields.
+
+## Updated EPerson registration
+**PATCH /api/eperson/registrations/<:id>?token=<:token>**
+
+To update the EPerson registration, perform a patch with the JSON below to the eperson registrations endpoint, by providing the registration `token` and the `id` of the registration. 
+
+1. Replace the existing email inside the registration:
+```json
+[
+  {
+    "op": "replace",
+    "path": "/email",
+    "value": [ "[email protected]" ]
+  }
+]
+```
+2. Add an email inside the registration:
+```json
+[
+  {
+    "op": "add",
+    "path": "/email",
+    "value": [ "[email protected]" ]
+  }
+]
+```
+
+The allowed path is the one involving the `email` field, while the operation allowed are:
+
+- `replace` - if a different value was set
+- `add` - if none already set
+
+This method, if successful, will renew the `token` and as a side effect it will send a new Email to the provided `email` value.
+
+We can have the following cases:
+- `email` related to an account: a validation link for reviewing the information is sent to that email address.
+- new `email`: a link to the same authentication method provided is sent to that email address 
+
+Status codes:
+
+* 204 Created - if the operation succeed with a new token generated, and e new mail sent to the `email` provided in the request
+* 401 Unauthorized - if registration is disabled the token provided is not valid or absent
+* 422 Unprocessable Entity - if the email address was omitted or the operation is not valid
 
 ## Create new EPerson registration
 **POST /api/eperson/registrations?accountRequestType={requestType_forgot_or_register}**

epersons.md

@@ -279,6 +279,34 @@ Status codes:
 * 401 Unauthorized - if the token doesn't allow you to create this account
 * 422 Unprocessable Entity - If the provided password not respects the rules configured in the regular expression
 
+## Merge eperson registration data
+**POST /api/eperson/epersons/<:uuid>?token=<:token>&override=<:metadata-fields>**
+
+Allows the merge of some `registrationData` related to the provided *registration-token* (i.e. `<:token>`) into an already actived user account.
+This action is permitted by:
+  - ***logged-user***: that has the same `uuid` as the one specified with the `<:uuid>` param.
+  - ***anonymous-user***: that provides a `validation-token` (i.e. a token obtained via email confirmation)
+
+The `override` parameter contains the list of *metadata-fields* that will be overwritten for that linked user.
+
+The token was previously sent via Email from the [Create new EPerson registration](epersonregistrations.md#create-new-eperson-registration).
+
+This example shows a simlpe request:
+
+```bash
+curl -X POST http://${dspace.url}/api/eperson/epersons/${id-eperson}?token=${token}&override=${metadata-fields} \
+     -H "Content-Type: application/json" \
+     -H "Authorization: Bearer ${bearer-token}" \
+```
+
+As you can see, the request has an ***empty body***.
+
+Status codes:
+* 201 Created - if the operation succeed
+* 400 Bad Request - if the `uuid` provided doesn't exist, or if some `override` element isn't found inside the linked user item.
+* 401 Unauthorized - The user is anonymous, the `uuid` of the user is not the same as the one logged in, or if the `token` is not valid (i.e. expired or wrong type).
+* 403 Forbidden - The user is authenticated, the `token` is not valid or the `uuid` is not the same as the one of the user.
+
 ## Linked entities
 ### Groups
 **GET /api/eperson/epersons/<:uuid>/groups**