Authentification OAuth2 sur la plateforme Yapla

Découvrez le processus à suivre pour obtenir un jeton d'accès (access token) via le protocole OAuth2. Ce jeton est nécessaire pour effectuer des appels sécurisés à l'API GraphQL de Yapla au nom d'un utilisateur.

Flux d'authentification supportés

Yapla supporte deux flux standards et sécurisés :

1. Flux de code d'autorisation (Authorization Code Flow) : Idéal pour les applications web traditionnelles où le Client Secret peut être stocké de manière sécurisée sur un serveur.
2. Flux de code d'autorisation avec PKCE (Proof Key for Code Exchange) : Recommandé pour les clients publics, comme les applications mobiles ou les applications web à page unique (SPA), où le Client Secret ne peut pas être stocké en toute sécurité.

Étape 1 : Obtenir vos identifiants client OAuth

Avant de pouvoir vous connecter à l'API, vous devez obtenir un Client ID et, si nécessaire, un Client Secret. Ces identifiants sont uniques à votre application.

Action requise :

Pour recevoir vos identifiants, veuillez envoyer un courriel à support@yapla.com avec les informations suivantes :

• Nom de votre application : Un nom descriptif pour votre projet.
• Type de client : Spécifiez si votre application est confidentielle (serveur web) ou publique (SPA, mobile).
• Description de vos besoins : Expliquez brièvement à quoi servira votre intégration et les permissions (scopes) dont vous pensez avoir besoin. Les scopes applicables à votre client vous seront communiqués par notre équipe en fonction de cette description.
• URIs de redirection (Redirect URIs) : La ou les URLs complètes vers lesquelles Yapla redirigera l'utilisateur après son autorisation. Ces URLs doivent être précises et sécurisées (https).

Notre équipe traitera votre demande et vous retournera de manière sécurisée votre Client ID (et votre Client Secret si applicable).

Étape 2 : Rediriger l'utilisateur vers la page de consentement

La première étape consiste à rediriger l'utilisateur vers la page de consentement de Yapla.

A. Génération du code_verifier et code_challenge (Pour PKCE uniquement)

Si vous utilisez le flux PKCE, vous devez d'abord générer :

1. Un code_verifier : Une chaîne de caractères aléatoire de haute entropie.
2. Un code_challenge : Le code_verifier encodé en Base64 après avoir appliqué une fonction de hachage SHA-256. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

Vous devez stocker le code_verifier pour l'utiliser à l'étape 3.

B. Construction de l'URL d'autorisation

Vous devez construire une URL de la forme suivante :

https://login.yapla.com/oauth/authorize?response_type=code&client_id=[VOTRE_CLIENT_ID]&redirect_uri=[VOTRE_URI_DE_REDIRECTION]&scope=[SCOPES_ATTRIBUÉS]&state=[VALEUR_ALÉATOIRE]&code_challenge=[CHALLENGE_PKCE]&code_challenge_method=S256

Paramètres de l'URL :

• response_type=code: Valeur fixe.
• client_id=[VOTRE_CLIENT_ID]: Votre identifiant client.
• redirect_uri=[VOTRE_URI_DE_REDIRECTION]: Doit correspondre exactement à l'une des URIs fournies.
• scope=[SCOPES_ATTRIBUÉS]: La liste des permissions (séparées par des espaces) qui vous ont été attribuées.
• state=[VALEUR_ALÉATOIRE]: Une chaîne aléatoire pour prévenir les attaques CSRF. À vérifier au retour.
• code_challenge=[CHALLENGE_PKCE]: (PKCE) Le challenge généré.
• code_challenge_method=S256: (PKCE) Indique que le challenge a été haché avec SHA-256.

Après consentement, l'utilisateur est redirigé vers votre redirect_uri avec un code et le state en paramètres.

Étape 3 : Échanger le code d'autorisation contre un jeton d'accès

Avec le code reçu, votre application doit effectuer un appel POST vers le point de terminaison de jeton de Yapla pour obtenir l'access_token.

Endpoint : POST https://[VOTRE_SERVEUR_YAPLA]/oauth/token En-tête : Content-Type: application/x-www-form-urlencoded

Corps de la requête (Body) :

• grant_type: authorization_code
• code: Le code d'autorisation reçu.
• redirect_uri: La même URI de redirection.
• client_id: Votre Client ID.
• client_secret: (Non-PKCE) Votre Client Secret.
• code_verifier: (PKCE) Le code_verifier original que vous avez généré et stocké.

Exemple avec curl (Flux PKCE) :

curl -X POST \
  https://login.yapla.com/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'code=[CODE_REÇU]' \
  -d 'redirect_uri=[VOTRE_URI_DE_REDIRECTION]' \
  -d 'client_id=[VOTRE_CLIENT_ID]' \
  -d 'code_verifier=[VOTRE_CODE_VERIFIER]'

Réponse attendue (JSON) :

{
  "access_token": "xyz789...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "abc123...",
  "scope": "c3_12345 c3_67890"
}

Stockez le access_token et le refresh_token de manière sécurisée.

Étape 4 : Utiliser le jeton d'accès

Vous pouvez maintenant utiliser l'access_token pour faire des appels authentifiés à l'API GraphQL de Yapla.

Endpoint de l'API :

• Amérique du Nord : https://s1.yapla.com/graphql
• Europe : https://s2.yapla.com/graphql

Exemple d'appel API :

curl -X POST \
  https://[s1|s2].yapla.com/graphql \
  -H 'Authorization: Bearer [VOTRE_ACCESS_TOKEN]' \
  -H 'Content-Type: application/json' \
  -d '{"query": "{ company { name } }"}'

Félicitations, votre application est maintenant connectée à l'API Yapla !