Skip to content

Applicazioni OAuth per partner


Un’applicazione OAuth di proprietà del partner è pensata per un’integrazione che si connette a più account Planfix. Le stesse credenziali dell’applicazione vengono usate per tutti gli account dei clienti, mentre ogni account controlla separatamente l’accesso e ogni utente acconsente alla propria connessione.

Se l’integrazione è destinata a un solo account, è più semplice creare un’applicazione di proprietà dell’account.

Creazione di un’applicazione

  1. Apri il tuo account partner.
  2. Vai a Applicazioni OAuth.
  3. Seleziona Crea applicazione.
  4. Inserisci il nome e la descrizione che verranno mostrati agli utenti e agli amministratori.
  5. Seleziona il tipo di client OAuth.
  6. Aggiungi gli URI di reindirizzamento.
  7. Seleziona gli ambiti REST API minimi necessari.
  8. Salva l’applicazione e copia le sue credenziali.

Una nuova applicazione è privata e richiede l’approvazione esplicita in ogni account a cui si connette.

Tipo di client OAuth

Tipo Applicazioni previste Credenziali
Pubblico Applicazioni per dispositivi mobili, desktop e browser, e client MCP locali. Solo client_id. Non è previsto un segreto client; PKCE S256 è obbligatorio.
Riservato Applicazioni lato server in cui il segreto può essere archiviato al di fuori del dispositivo dell’utente e del codice lato client. client_id e client_secret.

Il tipo di client OAuth è indipendente dal fatto che l’applicazione sia pubblicata. Ad esempio, un’applicazione mobile privata è un client OAuth pubblico senza segreto.

URI di reindirizzamento

Specifica tutti gli URL a cui Planfix può reindirizzare un utente dopo l’accesso.

  • Usa https per un servizio web.
  • http è consentito solo per indirizzi di loopback come localhost e 127.0.0.1.
  • Un client può usare una porta dinamica per un indirizzo di loopback, ma schema, host, percorso e query devono corrispondere.
  • Non usare caratteri jolly, frammenti URL o URI di reindirizzamento che non controlli.

Ambiti

Gli ambiti definiscono le autorizzazioni massime dell’applicazione. Richiedi solo i livelli di accesso necessari dall’elenco degli ambiti REST API.

Gli ambiti dell’applicazione non sostituiscono le normali autorizzazioni dell’utente. Anche quando un ambito viene concesso, l’applicazione può lavorare solo con i dati a cui l’utente ha accesso.

La modifica degli URI di reindirizzamento o degli ambiti crea una nuova versione da approvare. Gli account già connessi devono esaminare e approvare la nuova versione e gli utenti devono connettersi di nuovo.

Connessione di un account cliente

Un’applicazione privata di proprietà del partner deve essere approvata esplicitamente da un amministratore in ogni account.

  1. Apri l’applicazione nel tuo account partner.
  2. Nell’area del link di approvazione, inserisci il nome dell’account cliente.
  3. Copia il link generato e invialo a un amministratore di quell’account.
  4. Chiedi all’amministratore di verificare il proprietario, gli URI di reindirizzamento e gli ambiti, quindi di approvare l’applicazione.
  5. Dopo l’approvazione, gli utenti dell’account possono completare l’autorizzazione OAuth. Ogni utente acconsente separatamente per conto proprio.

Il link apre Gestione account → API → Applicazioni OAuth e MCP e mostra l’applicazione richiesta.

Un amministratore che sta anche connettendo l’applicazione può selezionare Approva e connetti.

Applicazioni private e pubblicate

Stato Modalità di accesso all’account
Privata Richiede sempre l’approvazione esplicita di un amministratore di ogni account.
Pubblicata Disponibile senza approvazione separata quando la policy dell’account è Consenti applicazioni pubblicate. Richiede comunque l’approvazione quando la policy è Solo applicazioni approvate.

La pubblicazione è una procedura di revisione Planfix separata. Prima di inviare un’applicazione, prepara un nome e una descrizione chiari, un insieme minimo di ambiti, URI di reindirizzamento funzionanti e documentazione per gli utenti sulla connessione e la rimozione dell’integrazione. Contatta il supporto Planfix per conoscere la procedura di pubblicazione.

Indirizzi di connessione

Usa gli endpoint OAuth globali del prodotto Planfix in cui si trova l’account dell’utente:




Non aggiungere il nome dell’account a un URL globale. L’utente seleziona l’account in una pagina Planfix. Il protocollo completo, inclusi resource, PKCE, aggiornamento dei token e revoca, è descritto in OAuth 2.0 per le applicazioni.

Gestione di un’applicazione

Un partner può:

  • modificare il nome e la descrizione;
  • modificare gli URI di reindirizzamento e gli ambiti;
  • disabilitare e riabilitare l’applicazione;
  • ruotare il segreto client di un’applicazione riservata;
  • generare un link di approvazione dell’applicazione per un account specifico.

Dopo la rotazione del segreto, il vecchio segreto client smette immediatamente di funzionare. Aggiorna il segreto sul server dell’integrazione e non inviarlo mai agli utenti.

La disabilitazione di un’applicazione blocca l’autorizzazione OAuth e i token emessi in ogni account. Questa azione interessa tutti i clienti che usano l’applicazione.

Raccomandazioni prima del lancio

  • Usa Authorization Code con PKCE S256 e convalida state.
  • Richiedi solo gli ambiti necessari.
  • Dopo l’accesso, mostra all’utente l’account selezionato.
  • Gestisci la rotazione dei token di aggiornamento: dopo un aggiornamento riuscito, il token di aggiornamento precedente non è più valido.
  • Non scrivere nei log token, codici di autorizzazione, code_verifier o segreti client.
  • Documenta come gli utenti possono disconnettere l’integrazione e richiedere la cancellazione dei propri dati.
  • Prova gli scenari di revoca dell’approvazione, disabilitazione dell’applicazione e nuova connessione.

Vai a