Opentalent/ap2i @ develop

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 :

Se connecter à HelloAsso : un bouton "se connecter avec HelloAsso" est présent sur une page du logiciel. Il permet d'afficher une popup contenant le formulaire de connexion HelloAsso.
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.
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).
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 "Connecter à HelloAsso".

Ce bouton permet d'afficher une popup contenant le forumaire de connexion HelloAsso : https://auth.helloasso.com/authorize?<params>

On ajoute à l'URL de la page HelloAsso 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, pas utilisé.

Le formulaire ainsi affiché permet à l'utilisateur de s'authentifier sur HelloAsso, puis en cas de réussite, de confirmer vouloir lier son compte HelloAsso à son compte Opentalent.

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 : https://app.opentalent.fr/helloasso/callback.

Lorsqu'il redirige vers l'url de callback, HelloAsso y ajoute 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 valeur initiale utilisée pour le challenge PCKE, stockée en base.
redirect_uri : l'url de callback passée précédemment au formulaire HelloAsso..

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