From 5b28089d2f760754f17c893d4f7ee9a8713b0326 Mon Sep 17 00:00:00 2001 From: Vincenzo Mecca Date: Tue, 24 Sep 2024 15:48:21 +0200 Subject: [PATCH] [CST-10704][CST-14902][CST-15073] Adds ORCID login flow with private email --- epersonregistrations.md | 150 +++++++++++++++++++++++++++++++++++++++- epersons.md | 28 ++++++++ 2 files changed, 175 insertions(+), 3 deletions(-) diff --git a/epersonregistrations.md b/epersonregistrations.md index a16a95e3..da5b2f2f 100644 --- a/epersonregistrations.md +++ b/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": "user@institution.edu", "user": null, "type": "registration" } ``` - +2. User registration linked to an eperson: ```json { + "id": 2, "email": "user@institution.edu", "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": "power-user@orcid.org", + "user": "028dcbb8-0da2-4122-a0ea-254be49ca107", + "type": "registration", + "registrationType": "orcid", + "netId": "0000-1111-2222-3333", + "registrationMetadata": { + "email": [ + { + "value": "power-user@orcid.org", + "language": null, + "authority": "", + "confidence": -1, + "place": -1, + "overrides": "power-user@dspace.org" + } + ], + "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": [ "vincenzo.mecca@4science.com" ] + } +] +``` +2. Add an email inside the registration: +```json +[ + { + "op": "add", + "path": "/email", + "value": [ "vincenzo.mecca@4science.com" ] + } +] +``` + +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}** diff --git a/epersons.md b/epersons.md index 99c34012..c2a1dc66 100644 --- a/epersons.md +++ b/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**