Autenticazione OAuth2 sulla piattaforma Yapla

Di seguito il processo per ottenere un token di accesso (access token) tramite il protocollo OAuth2. Questo token serve per effettuare chiamate sicure all'API GraphQL di Yapla per conto di un utente.

Flussi di autenticazione supportati

Yapla supporta due flussi standard e sicuri:

Flusso con Codice di Autorizzazione (Authorization Code Flow): Ideale per applicazioni web tradizionali in cui il Client Secret può essere archiviato in modo sicuro su un server.
Flusso con Codice di Autorizzazione e PKCE (Proof Key for Code Exchange): Consigliato per i client pubblici, come applicazioni mobili o applicazioni web a pagina singola (SPA), in cui il Client Secret non può essere archiviato in modo sicuro.

Passaggio 1: Ottenere le credenziali del client OAuth

Prima di poterti connettere all'API, devi ottenere un Client ID e, se necessario, un Client Secret. Queste credenziali sono uniche per la tua applicazione.

Azione richiesta:

Per ricevere le tue credenziali, invia un'e-mail a support@yapla.com con le seguenti informazioni:

Nome dell'applicazione: Un nome descrittivo per il tuo progetto.
Tipo di client: Specifica se la tua applicazione è confidenziale (server web) o pubblica (SPA, mobile).
Descrizione delle tue esigenze: Spiega brevemente a cosa servirà la tua integrazione e i permessi (scope) di cui pensi di aver bisogno. Gli scope applicabili al tuo client ti saranno comunicati dal nostro team in base a questa descrizione.
URI di reindirizzamento (Redirect URIs): L'URL o gli URL completi a cui Yapla reindirizzerà l'utente dopo la sua autorizzazione. Questi URL devono essere precisi e sicuri (https).

Il nostro team elaborerà la tua richiesta e ti restituirà in modo sicuro il tuo Client ID (e il Client Secret se applicabile).

Passaggio 2: Reindirizzare l'utente alla pagina di consenso

Il primo passo consiste nel reindirizzare l'utente alla pagina di consenso di Yapla.

A. Generazione di `code_verifier` e `code_challenge` (Solo per PKCE)

Se utilizzi il flusso PKCE, devi prima generare:

Un code_verifier: Una stringa casuale ad alta entropia.
Un code_challenge: Il code_verifier codificato in Base64 dopo aver applicato una funzione di hash SHA-256. code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

Devi archiviare il code_verifier per utilizzarlo nel Passaggio 3.

B. Costruzione dell'URL di autorizzazione

Devi costruire un URL nel seguente formato:

https://login.yapla.com/oauth/authorize?response_type=code&client_id=[TUO_CLIENT_ID]&redirect_uri=[TUO_URI_DI_REINDIRIZZAMENTO]&scope=[SCOPE_ASSEGNATI]&state=[VALORE_CASUALE]&code_challenge=[CHALLENGE_PKCE]&code_challenge_method=S256

Parametri dell'URL:

response_type=code: Valore fisso.
client_id=[TUO_CLIENT_ID]: Il tuo client ID.
redirect_uri=[TUO_URI_DI_REINDIRIZZAMENTO]: Deve corrispondere esattamente a uno degli URI forniti.
scope=[SCOPE_ASSEGNATI]: L'elenco dei permessi (separati da spazi) che ti sono stati assegnati.
state=[VALORE_CASUALE]: Una stringa casuale per prevenire attacchi CSRF. Da verificare al ritorno.
code_challenge=[CHALLENGE_PKCE]: (PKCE) La challenge generata.
code_challenge_method=S256: (PKCE) Indica che la challenge è stata hashata con SHA-256.

Dopo aver dato il consenso, l'utente viene reindirizzato al tuo redirect_uri con un code e lo state nei parametri.

Passaggio 3: Scambiare il codice di autorizzazione con un token di accesso

Con il code ricevuto, la tua applicazione deve effettuare una richiesta POST all'endpoint dei token di Yapla per ottenere l'access_token.

Endpoint: POST https://login.yapla.com/oauth/token Intestazione (Header): Content-Type: application/x-www-form-urlencoded

Corpo della richiesta (Body):

grant_type: authorization_code
code: Il codice di autorizzazione ricevuto.
redirect_uri: Lo stesso URI di reindirizzamento.
client_id: Il tuo Client ID.
client_secret: (Non-PKCE) Il tuo Client Secret.
code_verifier: (PKCE) Il code_verifier originale che hai generato e archiviato.

Esempio con curl (Flusso 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=[CODICE_RICEVUTO]' \
  -d 'redirect_uri=[TUO_URI_DI_REINDIRIZZAMENTO]' \
  -d 'client_id=[TUO_CLIENT_ID]' \
  -d 'code_verifier=[TUO_CODE_VERIFIER]'

Risposta attesa (JSON):

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

Archivia l'access_token e il refresh_token in modo sicuro.

Passaggio 4: Utilizzare il token di accesso

Ora puoi utilizzare l'access_token per effettuare chiamate autenticate all'API GraphQL di Yapla.

Endpoint dell'API:

Nord America: https://s1.yapla.com/graphql
Europa: https://s2.yapla.com/graphql

Esempio di chiamata API:

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

Congratulazioni, la tua applicazione è ora connessa all'API di Yapla!