ap2i/doc/helloasso.md

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 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.