add doc/helloasso.md

doc/helloasso.md

@@ -0,0 +1,108 @@
+## Helloasso
+
+> Voir : 
+> https://ressources-opentalent.atlassian.net/wiki/spaces/SPEC/pages/421822467/User+Stories#La-mire-de-connexion
+> https://dev.helloasso.com/docs/mire-authorisation#2-enregistrement-de-votre-domaine-de-redirection
+
+### Principe général
+
+Une Organization doit pouvoir associer son compte Opentalent à son compte Helloasso. Ce lien permettra 
+ensuite des interactions avec HelloAsso comme par exemple le paiement de factures (en une ou plusieurs fois) 
+ou l’affichage de billetteries HelloAsso sur les pages de détails des évènements (agenda, sites Typo3).
+
+
+### Configuration initiale
+
+Les identifiants et clés d'API sont fournis par Helloasso, et enregistrés comme variables d'environnement (voir variables 
+`HELLOASSO_****`).
+
+On enregistre comme domaine de redirection le domaine opentalent.fr : https://opentalent.fr/ 
+(voir: `ConnectionService::setupOpentalentDomain()`)
+
+### Sandbox
+
+Toutes les URLs mentionnées ici ont une version équivalente de test : 
+
+* xxx.helloasso.com : Version de production
+* xxx.helloasso-sandbox.com : Version de test
+
+### Mise en oeuvre
+
+Pour lier une Organization à son compte Helloasso : 
+
+1. Se connecter à HelloAsso : un bouton "se connecter avec HelloAsso" est présent sur une page du logiciel. Il permet de rediriger l'utilisateur vers la page de connexion HelloAsso.
+2. Une fois identifié, Helloasso redirige le visiteur vers une page de callback dont on a fourni l'url au préalable. Ce retour s'accompagne d'un jeton d'autorisation HelloAsso que l'on récupère.
+3. Grâce à ce jeton d'autorisation, on récupère auprès de l'API HelloAsso un jeton d'accès (durée de vie: 30min) et un jeton de renouvellement (durée de vie: 30jours).
+4. Ce jeton d'accès est stocké en base, et sera ensuite attaché aux requêtes envoyées à l'API HelloAsso.
+
+A noter qu'on renouvelle ce jeton stocké en base de manière régulière afin que celui ci reste valide.
+
+Par ailleurs, l'utilisateur peut : 
+
+* dissocier son compte Helloasso de son compte Opentalent
+
+#### Se connecter avec HelloAsso
+
+La [page HelloAsso](https://local.app.opentalent.fr/helloasso) du front (V2) donne accès à un bouton "se connecter avec HelloAsso".
+
+Ce bouton permet de rediriger l'utilisateur vers la page de connexion HelloAsso : `https://auth.helloasso.com/authorize?<params>`
+
+On ajoute à cette URL une query composée des éléments suivants :
+
+* `client_id` : l'identifiant client Opentalent enregistré comme variable d'environnement.
+* `redirect_uri` : l'url vers laquelle l'utilisateur sera redirigé après s'être authentifié.
+* `code_challenge`: code challenge PKCE à générer en amont (voir : `OAuthPkceGenerator::generatePkce()`).
+* `code_challenge_method` : méthode du test, doit être égal à "S256".
+* `state` : *optionnel, utilité à revoir*.
+
+Une fois redirigé vers cette URL, l'utilisateur a accès à un formulaire de connexion lui permettant 
+de se connecter à son compte Helloasso. 
+
+
+#### Le callback après authentification
+
+Une fois l'authentification effectuée via le formulaire HelloAsso, l'utilisateur est redirigé vers l'URL de 
+callback fournie précédemment, URL à laquelle aura été ajoutée une query.
+
+Cette query de retour contient :
+
+* Un authorization_code en cas de succès
+* Un message d'erreur en cas de problème de configuration.
+
+A ce niveau là, si tout s'est bien déroulé, on dispose donc d'un jeton d'autorisation HelloAsso `authorization_code`.
+
+#### Récupérer et stocker les jetons d'accès
+
+On adresse ensuite une requête POST à l'adresse https://api.helloasso.com/oauth2/token, 
+contenant le body suivant (`application/x-www-form-urlencoded`) : 
+
+* `client_id` : l'identifiant client Opentalent enregistré comme variable d'environnement.
+* `client_secret` : la clé secrète Opentalent enregistré comme variable d'environnement.
+* `grant_type`: doit valoir 'authorization_code'.
+* `code`: l'authorization_code fourni précédemment.
+* `code_verifier`: la chaine de caractère générée pour le challenge, avant encodage *à revoir*.
+* `redirect_uri` : *à revoir*.
+
+On récupère ensuite une réponse JSON de la forme : 
+
+* `access_token` : le jeton qui servira pour les requêtes vers l'API, valable 30 min.
+* `refresh_token` : Le jeton permettant de demander le renouvellement de l'access_token, valable 30 jours.
+* `token_type` : doit valoir "bearer".
+* `expires_in` : la durée de validité du token d'accès, en secondes.
+* `organization_slug` : le slug de l'organization que l'on vient de connecter.
+
+On stocke enfin dans la table HelloAsso les valeurs de `access_token`, `refresh_token` et `organization_slug`, associées
+à l'id de l'Organization.
+
+#### Envoyer une requête à l'API HelloAsso
+
+TODO: à compléter
+
+#### Le renouvellement du jeton d'accès
+
+TODO: à compléter
+
+#### Dissocier le compte Helloasso de son compte Opentalent
+
+Pour dissocier le compte HelloAsso du compte Opentalent, il suffira de supprimer la ligne correspondant à 
+l'Organization dans la table `HelloAsso`.