Applicazioni OAuth e MCP in un account
La sezione OAuth e applicazioni MCP contiene le impostazioni per la connessione di applicazioni esterne a un account Planfix.
Apri Gestione account → API → Applicazioni OAuth e MCP. Questa sezione è disponibile agli amministratori dell'account e agli amministratori tecnici.
Contiene tre aree:
- MCP — l'indirizzo del server MCP e brevi istruzioni di connessione;
- Applicazioni di proprietà di questo account — applicazioni OAuth create specificamente per l'account corrente;
- Applicazioni di terze parti — la policy generale e le applicazioni esplicitamente approvate nell'account.
MCP
Questa area mostra l'URL MCP di Planfix:
https://mcp.planfix.com/mcp
Di solito a un utente 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. Vedi Planfix MCP per istruzioni passo passo.
Applicazioni di proprietà di questo account
Crea un'applicazione di proprietà dell'account quando l'integrazione è destinata soltanto 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 nel suo account proprietario indipendentemente dalla policy per applicazioni di terze parti;
- utilizza gli endpoint OAuth globali;
- può funzionare con la REST API o MCP nei soli ambiti (scopes) 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 redirect del client.
- Seleziona i livelli di accesso minimi richiesti.
- Salva l'applicazione e copia le credenziali generate.
| Tipo di client | Quando usarlo |
|---|---|
| Pubblico | Un'applicazione mobile, desktop o browser, o un client MCP locale. Non viene rilasciato alcun secret; PKCE protegge il flusso di autorizzazione. |
| Confidenziale | Un'applicazione lato server che può memorizzare in modo sicuro un client secret. Non includere mai il secret nel codice client, in un'app mobile o in un file di configurazione distribuito. |
Il client secret viene mostrato dopo la creazione di un'applicazione confidenziale. Conservalo in un gestore di segreti sicuro.
Redirect URI e autorizzazioni
Usa https per applicazioni web normali. http è consentito solo per host loopback come localhost e 127.0.0.1.
Seleziona soltanto gli scopes necessari all'integrazione. Gli scopes limitano l'accesso dell'applicazione ma non estendono i permessi dell'utente che la connette.
La modifica degli URI di redirect o degli scopes cambia la versione di approvazione dell'applicazione e i token emessi in precedenza non corrispondono più all'applicazione. Gli utenti dovranno connettersi nuovamente.
Gestione di un'applicazione
Dalla scheda dell'applicazione puoi:
- modificare nome, descrizione, URI di redirect e scopes;
- disabilitare e riabilitare l'applicazione;
- ruotare il client secret di un client confidenziale.
Dopo la rotazione del secret, il precedente client secret smette di funzionare immediatamente. Copia il nuovo secret e aggiorna la configurazione del server dell'integrazione.
Disabilitare un'applicazione blocca l'autorizzazione e l'uso dei token emessi. Prima di disabilitarla, assicurati che nessun processo aziendale ne dipenda.
Applicazioni di terze parti
Le applicazioni di terze parti includono applicazioni di partner, applicazioni pubblicate e client MCP registrati tramite CIMD o DCR.
Policy per applicazioni di terze parti
| Policy | 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 ancora l'approvazione esplicita dell'amministratore. |
| Solo applicazioni approvate | Ogni applicazione di terze parti richiede l'approvazione esplicita dell'amministratore. |
| Blocca applicazioni di terze parti | Le applicazioni OAuth e MCP di terze parti sono bloccate. Le applicazioni di proprietà dell'account continuano a funzionare. |
Si consiglia Solo applicazioni approvate per account in cui ogni integrazione deve essere valutata singolarmente.
Approvazione di un'applicazione
Una richiesta di approvazione può apparire in due modi:
- un utente avvia una connessione OAuth e Planfix segnala che è necessaria l'approvazione;
- un partner invia all'amministratore un link diretto all'applicazione.
Prima di approvare un'applicazione verifica:
- il suo nome, la descrizione e il proprietario;
- il suo URI di redirect o l'host di callback;
- gli scopes richiesti;
- se i dipendenti necessitano dell'integrazione.
L'approvazione da parte dell'amministratore si applica all'account ma non collega automaticamente ogni utente. Ogni dipendente accede separatamente e acconsente per conto proprio. Se un amministratore sta collegando l'applicazione, Approva e connetti completa entrambe le azioni.
Se lo sviluppatore modifica gli URI di redirect o gli scopes di un'applicazione di terze parti, la nuova versione deve essere approvata.
Revoca dell'approvazione
Per bloccare un'applicazione per l'account, cercala nell'elenco approvati e revoca l'accesso. I token OAuth associati agli utenti di questo account vengono revocati.
Quando la policy è Consenti applicazioni pubblicate, revocare un'approvazione esplicita non blocca un'applicazione pubblicata poiché la policy generale la consente ancora. Seleziona Solo applicazioni approvate o Blocca applicazioni di terze parti per bloccarla.
Connessioni personali degli utenti
L'approvazione dell'account e la connessione individuale dell'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 MCP.
- Elimina la sessione.
Eliminare la sessione revoca i token associati. Per ripristinare l'accesso, l'utente deve completare nuovamente l'autorizzazione OAuth.
Raccomandazioni per gli amministratori
- Usa Solo applicazioni approvate se ogni integrazione deve essere valutata separatamente.
- Verifica il proprietario dell'applicazione e l'URI di redirect, non solo il nome.
- Approva gli scopes minimi necessari, specialmente per la modifica e la cancellazione dei dati.
- Controlla periodicamente l'elenco delle applicazioni di terze parti e rimuovi quelle non utilizzate.
- Usa il tipo di client pubblico per client locali e desktop e il tipo confidenziale per integrazioni lato server.
- Se le credenziali di un'applicazione confidenziale potrebbero essere compromesse, ruota immediatamente il suo secret e riconnetti l'integrazione se necessario.