Proteggi la tua applicazione con OAuth 2.0 e gestisci l'incorporamento fluido degli Iframe all'interno della dashboard di DonutWork.

Autenticazione e Incorporamento

DonutWork utilizza un solido modello di sicurezza per garantire che le applicazioni di terze parti possano accedere ai dati in modo sicuro fornendo un'esperienza utente unificata. Questa guida copre il flusso di lavoro di Dual-Auth e i requisiti per l'incorporamento di Iframe di livello enterprise.

1. Il Flusso di Lavoro OAuth 2.0

Le applicazioni utilizzano un flusso standard OAuth 2.0 Authorization Code per ottenere l'accesso autorizzato ai dati di un'azienda.

Step 1: Richiesta di Autorizzazione

Rindirizza l'utente al server di autorizzazione di DonutWork. Ciò avviene quando un utente installa o accede alla tua app per la prima volta.

Endpoint: GET /i3/oauth/authorize

Parametri:

client_id: Il tuo identificativo univoco dell'applicazione.
redirect_uri: L'endpoint dove verrà inviato il codice.
response_type: Sempre code.
scope: Elenco (spazio o virgola) dei permessi nel formato canonico resource:action (es. customers:read charges:write).
requisito minimo scope: includere almeno company:read per completare correttamente il flusso di connessione OAuth delle app.
state: Una stringa univoca per prevenire attacchi CSRF.

Step 2: Scambio del Token

Una volta che l'utente approva la richiesta, DonutWork lo reindirizza al tuo redirect_uri con un code. Scambia immediatamente questo codice con un token di accesso.

Endpoint: POST /i3/oauth/token (Form-Encoded)

Corpo:

client_id: Il tuo identificativo dell'applicazione.
client_secret: Il tuo segreto protetto dell'applicazione.
code: Il codice di autorizzazione ricevuto nel reindirizzamento.
redirect_uri: Deve corrispondere all'URI utilizzato nello Step 1.

Step 3: Persistenza

Memorizza in modo sicuro i valori access_token e refresh_token restituiti. Questi token consentono alla tua app di effettuare chiamate API dirette a DonutWork (es. a /2026-02-01/customers.json).

2. Contesto Iframe e Sicurezza

Quando un'applicazione viene renderizzata all'interno della dashboard di DonutWork, viene incorporata tramite un Iframe. Ogni richiesta al punto di ingresso della tua applicazione include una firma di sicurezza.

Parametri della Richiesta

DonutWork aggiunge i seguenti parametri di query all'URL della tua applicazione:

company: L'identificativo univoco dell'azienda attiva.
hmac: Una firma crittografica della richiesta.
timestamp: Il timestamp Unix della richiesta.

Verifica della Firma (HMAC-SHA256)

Per verificare che la richiesta sia autentica e provenga da DonutWork, è necessario convalidare il parametro hmac utilizzando il tuo client_secret.

Procedura di Verifica:

Rimuovi il parametro hmac dalle coppie chiave-valore.
Ordina alfabeticamente i parametri rimanenti per chiave.
Concatena le chiavi e i valori ordinati in una stringa di query (es. company=C123&timestamp=1740000000).
Calcola l'HMAC-SHA256 di questa stringa utilizzando il tuo client_secret come chiave.
Confronta il risultato con l' hmac fornito.

const crypto = require('crypto');

function verifyHmac(queryParams, clientSecret) {
  const { hmac, ...params } = queryParams;
  const message = Object.keys(params)
    .sort()
    .map(key => `${key}=${params[key]}`)
    .join('&');

  const expectedHmac = crypto
    .createHmac('sha256', clientSecret)
    .update(message)
    .digest('hex');

  return hmac === expectedHmac;
}

1. ARGS = QueryString.Remove("hmac")
2. SORTED_MSG = ARGS.SortByKey().Join("&")
3. SIGNATURE = HMAC_SHA256(SORTED_MSG, APP_CLIENT_SECRET)
4. VALIDATE(SIGNATURE == QueryString["hmac"])

3. Requisiti di Integrazione UI

Poiché l'applicazione viene eseguita in un Iframe cross-site, si applicano le policy standard di sicurezza del browser.

Gestione della Sessione

I browser moderni bloccano i cookie di terze parti per impostazione predefinita. Per mantenere una sessione all'interno dell'Iframe, i cookie di sessione devono utilizzare i seguenti attributi:

SameSite=None: Consente l'invio del cookie in un contesto cross-site.
Secure=true: Richiesto quando viene utilizzato SameSite=None.

Se i tuoi cookie non hanno SameSite=None; Secure, gli utenti verranno disconnessi immediatamente dopo il reindirizzamento o durante la navigazione all'interno dell'app.

Content Security Policy (CSP)

Assicurati che gli header del tuo server consentano a DonutWork di incorporare la tua applicazione:

Content-Security-Policy: frame-ancestors 'self' https://hub.donutwork.com;
X-Frame-Options: ALLOW-FROM https://hub.donutwork.com

4. Scoperta delle Funzionalità

Come fase finale del flusso di autenticazione, la tua applicazione dovrebbe dichiarare le sue "capability" alla piattaforma. Ciò consente a DonutWork di effettuare il proxy delle richieste alla tua app (Azioni).

Azione: PUT /2026-02-01/integrations.json

Questa dichiarazione dovrebbe includere il tuo app_token (utilizzato da DonutWork per chiamarti) e un manifesto degli endpoint supportati. Fai riferimento alla Guida alla Scoperta delle Applicazioni per i dettagli.

Per i dettagli del flusso di disinstallazione (DELETE uninstall_url con company_id + HMAC verify), vedi Come costruire.

Autenticazione e Governance Iframe