Intercoop
Purpose
In the context of intercooperation among social economy entities,
these libraries implement a protocol to enable a user of a given entity
to use services provided by other entities having a bilateral agreement.
This is done keeping the users in control of which are the enabled
services and, most important, which entities will be transferred
their personal data to.
Some intended goals:
- Easely extend intercooperation to new entities by sharing a common protocol, so that:
- You implement once how your users access services provided by many other entities
- You implement once how to offer our services to users coming from many other entities
- Be certain that the services request comes from a user of the source entity
- Keep users in control of how and whom their personal data is transferred to
- Still avoid the user from having to type personal data again and again
Glossary
- Entity: one of the social economy peers that are intercooperating
- User: one of the legal or physical person who have rights regarding a entity
- Role: A set of rights a user might have within an entity (pe. member, worker, different kind of members...)
- Source entity: The entity a member has rights on.
- Target entity: The entity whose services are enabled for members of the source entity.
- Portal: Website for validated users of the source entity
- API: B2B web API offered by the target entity to the source entity.
Main protocol sequence
Case: a user of entity A (source) wants to enable service of intercooperation entity B (target):
Preconditions:
- Each entity has its own RSA public/private pair of keys
- Intercooperating entities share their public key among them and keep their private one secret
- User has validated its identity on web portal of entity A
Main course scenario:
- User indicates to source Portal the intent of activating a service on target entity
- Source portal shows the user which data will be transferred to target entity (member number, national id, name, address, emal...) and asks for consent
- User consents the transfer
- Source portal builds a message cointaining trasferred data and signs it using Source's private key.
- Source portal sends the message to https API on target entity
- Target API validates the signature with source's public key, stores the transferred data and generates a token for later reference
- Target API responds to Source Portal with an url on B having the token embedded inside.
- Source Portal redirects user's browser to that url, where the process to get the service can continue.
Errors
-
Portal -> API
- Not yaml message
- Missing message fields
- Not yaml payload
- Missing payload fields
- Source entity has no intercooperation agreement with target one
- Bad signature
-
Service errors
- Service unavailable (at all, for peer, for user, for role)
- Missing payload fields (because the application needs)
Workflow
Source portal's view
-
Portal renders intercooperation options
- Access to every provider info an services.
- Provider: Id, name, description, url, logo, services...
- Services: id, description, image, activation api
-
User click on one option
- Browser sends provider and service id
-
Portal asks the user permision to send several data
- Gather the required data for the service
- Gather the privacy policy from the service
- Obtain personal data from the portal ERP user
-
User accepts the transfer and the privacy police
-
Portal sends the info to the provider Api
- Gather required data for the service
- Build a signed package with it
- Send it to the service url
- Wait response
- Handle any error if it happens
- Else redirect user's browser to the url with the token
Target api's view