Applicazioni OAuth e MCP in un account
La sezione Applicazioni OAuth e MCP contiene le impostazioni per collegare applicazioni esterne a un account Planfix.
Apri Gestione account → API → Applicazioni OAuth e MCP. Questa sezione è disponibile per gli amministratori dell'account e gli amministratori tecnici.
Contiene tre aree:
- MCP — l'indirizzo del server MCP e brevi istruzioni per la connessione;
- Applicazioni di proprietà di questo account — applicazioni OAuth create appositamente per l'account corrente;
- Applicazioni di terze parti — il criterio generale e le applicazioni approvate esplicitamente nell'account.
MCP
In quest'area viene visualizzato l'URL MCP di Planfix:
https://mcp.planfix.com/mcp
Di norma, basta aggiungere questo URL a un client MCP compatibile e completare l'accesso OAuth. Il nome dell'account viene selezionato nella pagina Planfix e non è incluso nell'URL. Consulta Planfix MCP per le istruzioni dettagliate.
Applicazioni di proprietà di questo account
Crea un'applicazione di proprietà dell'account quando l'integrazione è destinata esclusivamente all'account corrente e il client esterno necessita di un client_id predefinito.
Un'applicazione di proprietà dell'account:
- non può connettersi ad altri account;
- è disponibile nell'account proprietario indipendentemente dal criterio per le applicazioni di terze parti;
- utilizza gli endpoint OAuth globali;
- può funzionare con l'API REST o MCP negli ambiti selezionati.
Creazione di un'applicazione
- Seleziona Crea applicazione.
- Inserisci un nome e una descrizione chiari.
- Seleziona il tipo di client OAuth.
- Aggiungi gli URI di reindirizzamento del client.
- Seleziona i livelli di accesso minimi necessari.
- Salva l'applicazione e copia le credenziali generate.
| Tipo di client | Quando utilizzarlo |
|---|---|
| Pubblico | Un'applicazione per dispositivi mobili, desktop o browser oppure un client MCP locale. Non viene generato alcun segreto; PKCE protegge il flusso di autorizzazione. |
| Riservato | Un'applicazione lato server in grado di archiviare in sicurezza un segreto client. Non includere mai il segreto nel codice lato client, in un'applicazione per dispositivi mobili o in un file di configurazione distribuito. |
Il segreto client viene visualizzato dopo la creazione di un'applicazione riservata. Conservalo in un gestore di segreti sicuro.
URI di reindirizzamento e autorizzazioni
Utilizza https per le normali applicazioni web. http è consentito solo per gli host di loopback, come localhost e 127.0.0.1.
Seleziona solo gli ambiti necessari all'integrazione. Gli ambiti limitano l'accesso dell'applicazione, ma non ampliano le autorizzazioni dell'utente che la connette.
La modifica degli URI di reindirizzamento o degli ambiti modifica la versione approvata dell'applicazione e i token emessi in precedenza non saranno più compatibili con essa. Gli utenti dovranno connettersi di nuovo.
Gestione di un'applicazione
Dalla scheda dell'applicazione puoi:
- modificare il nome, la descrizione, gli URI di reindirizzamento e gli ambiti;
- disabilitare e riabilitare l'applicazione;
- cambiare il segreto client di un client riservato.
Dopo aver cambiato il segreto, quello precedente smette immediatamente di funzionare. Copia il nuovo segreto e aggiorna la configurazione del server dell'integrazione.
La disabilitazione di un'applicazione blocca l'autorizzazione e l'utilizzo dei token emessi. Prima di disabilitarla, assicurati che nessun processo aziendale dipenda da essa.
Applicazioni di terze parti
Le applicazioni di terze parti includono applicazioni di proprietà di partner, applicazioni pubblicate e client MCP registrati tramite CIMD o DCR.
Criterio per le applicazioni di terze parti
| Criterio | Risultato |
|---|---|
| Consenti applicazioni pubblicate | Le applicazioni pubblicate da Planfix sono disponibili senza approvazione separata. Le applicazioni private dei partner e i client MCP registrati automaticamente richiedono comunque l'approvazione esplicita di un amministratore. |
| Consenti solo applicazioni approvate | Ogni applicazione di terze parti richiede l'approvazione esplicita di un amministratore. |
| Blocca le applicazioni di terze parti | Le applicazioni OAuth e MCP di terze parti vengono bloccate. Le applicazioni di proprietà dell'account continuano a funzionare. |
L'opzione Consenti solo applicazioni approvate è consigliata per gli account in cui ogni integrazione deve essere esaminata singolarmente.
Approvazione di un'applicazione
Una richiesta di approvazione può essere visualizzata in due modi:
- un utente avvia una connessione OAuth e Planfix segnala che è necessaria un'approvazione;
- un partner invia a un amministratore un link diretto all'applicazione.
Prima di approvare un'applicazione, verifica:
- il nome, la descrizione e il proprietario;
- il suo URI di reindirizzamento o l'host di callback;
- gli ambiti richiesti;
- se i dipendenti hanno bisogno dell'integrazione.
L'approvazione dell'amministratore si applica all'account, ma non connette automaticamente tutti gli utenti. Ogni dipendente accede separatamente e presta il proprio consenso. Se è un amministratore a connettere l'applicazione, Approva e connetti completa entrambe le operazioni.
Se lo sviluppatore modifica gli URI di reindirizzamento o gli ambiti di un'applicazione di terze parti, la nuova versione deve essere approvata.
Revoca dell'approvazione
Per bloccare un'applicazione nell'account, trovala nell'elenco delle applicazioni approvate e revoca l'accesso. I token OAuth associati agli utenti di questo account vengono revocati.
Quando è attivo il criterio Consenti applicazioni pubblicate, la revoca di un'approvazione esplicita non blocca un'applicazione pubblicata, perché il criterio generale continua a consentirla. Seleziona Consenti solo applicazioni approvate o Blocca le applicazioni di terze parti per bloccarla.
Connessioni personali degli utenti
L'approvazione dell'account e la connessione del singolo utente sono livelli di controllo separati.
Un dipendente può visualizzare e revocare le proprie connessioni OAuth:
- Apri la tua scheda utente.
- Vai a Gestione sessioni.
- Trova l'applicazione; le connessioni MCP sono contrassegnate con MCP.
- Elimina la sessione.
L'eliminazione della sessione revoca i token associati. Per ripristinare l'accesso, l'utente deve completare nuovamente l'autorizzazione OAuth.
Raccomandazioni per gli amministratori
- Usa Consenti solo applicazioni approvate se ogni integrazione deve essere esaminata separatamente.
- Verifica il proprietario dell'applicazione e l'URI di reindirizzamento, non solo il nome.
- Approva gli ambiti minimi necessari, soprattutto per modificare ed eliminare i dati.
- Esamina periodicamente l'elenco delle applicazioni di terze parti e rimuovi quelle non utilizzate.
- Usa il tipo di client pubblico per i client locali e desktop e il tipo riservato per le integrazioni lato server.
- Se le credenziali di un'applicazione riservata potrebbero essere state compromesse, cambia immediatamente il segreto e, se necessario, connetti di nuovo l'integrazione.