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
- Apri il tuo account partner.
- Vai a Applicazioni OAuth.
- Seleziona Crea applicazione.
- Inserisci il nome e la descrizione che verranno mostrati agli utenti e agli amministratori.
- Seleziona il tipo di client OAuth.
- Aggiungi gli URI di reindirizzamento.
- Seleziona gli ambiti REST API minimi necessari.
- 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
httpsper un servizio web. httpè consentito solo per indirizzi di loopback comelocalhoste127.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.
- Apri l’applicazione nel tuo account partner.
- Nell’area del link di approvazione, inserisci il nome dell’account cliente.
- Copia il link generato e invialo a un amministratore di quell’account.
- Chiedi all’amministratore di verificare il proprietario, gli URI di reindirizzamento e gli ambiti, quindi di approvare l’applicazione.
- 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:
| Finalità | Indirizzo |
|---|---|
| Autorizzazione | https://auth.planfix.com/oauth/authorize
|
| Token | https://auth.planfix.com/oauth/token
|
| Informazioni utente | https://auth.planfix.com/oauth/userinfo
|
| MCP | https://mcp.planfix.com/mcp
|
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_verifiero 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.