Bona fide referer workflow; implement bonafidebot

[opqdonut]

We need to support applying for a bona fide status. The application should work roughly like this:

• User applies for a bona fide catalogue item in REMS and names a referer (who should already have an idp-provided bona fide status)
  • Form should have: referer email address, free text field, and a license
• Referer should get an email, and be able to approve/reject the user once logged in to REMS
• If the referer approves, the application is approved and an entitlement to the bona fide resource is granted
• Elixir AAI reads the bona fide entitlement from REMS (via permission API Implement ELIXIR Permissions API #1319)
  • This should be a ResearcherStatus visa with "by": "peer"
• Bona fide status is pushed to Elixir via an API (Pushing bona fide status #2513)
• Sometime later a super-user (or rather, a human handler for the workflow in question) can log in and close or revoke the application thus ending the entitlement and bona fide status (e.g. does not trust person anymore)

Plan:

• bona fide status is modeled as a catalogue item with a default workflow that has bonafidebot as handler
• bonafidebot sends a decision request by email to the given address (like review request Reviewer/decider invitation #2040)
• the referer clicks on the link in his email, logs in, and his bona fide status (or lack of it) is sent by Elixir AAI to REMS (requires Configurable extra user attributes #2130 Reading bona fide status from IDP #2142).
  • The referer is given the decider role for the application.
• bonafidebot waits for the decision from the referer, verifies the situation and responds with a clear message
  • possibility for bots to return (error) messages to the user directly (split out to Bona fide bot UX improvements #2511)
  • bonafidebot approves when decider approves and has bona fide status
  • bonafidebot rejects when decider rejects
  • bonafidebot rejects when decider does not have bona fide status
    • or perhaps the application should be left waiting and the referer can try to get a bona fide status and try again?
• customize email text for decision request (currently it's a generic "Bonafide Bot has requested a decsion from you ...") (split out to Bona fide bot UX improvements #2511)
  • one option is to just use extra-translations to override the email text for the bonafide rems instance
• generating ResearcherStatus visas (in addition to the current ControlledAccessGrants visas) (split out to Pushing bona fide status #2513)

Notes and questions:

• Later, bonafidebot could be an external integration that uses event notifications (instead of a REMS core feature) (Event notifications #2095)
• No bot is needed if the decision request command handler checks the bona fide status
  however, the bot solution allows us to isolate the bona fide -related code in one place.
• Display a message that the user does not have bona fide status when trying to approve? This would require specific code and break the isolation. A bot message would not.
• A review request or decision request? A decider is more natural to have the other close/reject commands than just a reviewer.
• There are separate idp-provided bona fide status, and REMS-provided bona fide status
  • Clarify: Can someone who has received bona fide status from REMS give out further bona fide statuses after relogging (when idp can see from REMS they have bona fide)?
    • Answer: No
• Idea: workflow could restrict which groups (via user attributes) can can act as decider (kinda similar to Pre-defined deciders for decider workflow #2069)
  • This would allow for a nicer UX in the case where the referer does not have the right bona fide status

[opqdonut]

Awaiting decision / spec.

[Macroz]

Let's plan this further by splitting into separate tasks. Not blocked i.e. required feature and planning can proceed and waits implementation.

Bot can be suitable for this.

Should decision request (or comment request) always allow adding by email that sends an invitation to REMS? It is likely that at the beginning of any REMS instance, the people have not yet logged in to REMS so won't be available in the autocomplete because they are not in the users table.

[opqdonut]

Architecture idea:

• user applies for a catalogue item, fills in email of referer
• bonafidebot sends a decision request by email to the given address (see Reviewer/decider invitation #2040)
• decider logs in, his bona fide status (or lack of it) is sent by the idp (see Configurable extra user attributes #2130 Reading bona fide status from IDP #2142)
• decider sends an approve (or reject) decision
• bonafidebot waits for the decision, verifies that the decider has bona fide status and then approves or rejects the application
• an entitlement for a bona fide resource is entered in the db
• next time the user logs in, the idp checks via the rems permission api (Implement ELIXIR Permissions API #1319) that the user has been given bona fide status, and sends the status to rems

bonafidebot can either be in REMS, or an external intergration that uses event notifications (#2095)

Other ideas:

• no bot is needed if the decision request command handler checks the bona fide status
  • however, the bot solution allows us to isolate the bona fide -related code in one place

[mikael-linden]

For good usability, REMS should not allow the decider to approve an application if they don't have the bona fide status themselves. Instead, it should provide an informative message to the user why they can't approve the application.

Notice also that there are two ways to receive the bona fide status:
(1) User's Home Organisation (its IdP) tells the user is a researcher.
(2) A user qualifying to (1) vouches for the bona fide status (via this REMS feature)
In other words, the endorsement chain has just one link; a person who has received their bona fide qualifications via endorsement in REMS cannot endorse other persons. This feature is done by the IdP releasing proper bona fide status attribute. The REMS implementation must just check the endorser's bona fide status from the IdP's attribute and not from its internal database.

[opqdonut]

Yes, thanks for the clarification, that was our understanding too.

The message is also a good point.

[Macroz]

Waiting for a couple tasks and review in meeting this week. Plan seems possible with no big issues. I updated the task to reflect the general understanding.

[jaakkocsc]

We've now received API credentials on ELIXIR AAI for pushing the bona fide grants. But no clear spec on what to push yet.

[jaakkocsc]

An example content to push:
{ "jku": "https://login.elixir-czech.org/oidc/jwk", "kid": "rsa1", "typ": "JWT", "alg": "RS256" } { "sub": "[email protected]", "ga4gh_visa_v1": { "asserted": 1588240500, "by": "peer", "source": "https://elixir-europe.org/", "type": "ResearcherStatus", "value": "https://doi.org/10.1038/s41431-018-0219-y" }, "iss": "https://login.elixir-czech.org/oidc/", "exp": 1639478414, "iat": 1607942414, "jti": "1f2aec8f-7a5b-4200-8dbb-23048f8fb420" }

[jaakkocsc]

Approved push spec is very simple: we just pass the elixir-id as an URL parameter and that's it:
https://perun.elixir-czech.cz/rems/?elixirid={elixir_user_id}

[opqdonut]

moved leftovers to #2511 #2513