OAuth 2.0 per le applicazioni
OAuth 2.0 consente a un'applicazione di accedere a Planfix per conto di un utente senza richiedere o memorizzare la password dell'utente.
Planfix usa il flusso Authorization Code con PKCE S256 obbligatorio. OAuth può essere usato per connettersi a REST API o al server MCP di Planfix.
Se vuoi connettere un client AI già pronto, inizia da Planfix MCP. Se gestisci gli accessi nel tuo account, consulta Applicazioni OAuth e MCP in un account. I partner e gli sviluppatori di integrazioni multi-account possono consultare Applicazioni OAuth per partner.
Opzioni di registrazione dell'applicazione
| Opzione | Quando usarla | Dove funziona |
|---|---|---|
| Applicazione di proprietà dell'account | L'integrazione è destinata a un solo account e il client richiede un client_id predefinito.
|
Solo nell'account proprietario. |
| Applicazione di proprietà di un partner | La stessa applicazione deve connettersi a più account cliente. | Negli account in cui è consentito dai criteri di sicurezza o da un amministratore. |
| Registrazione automatica del client MCP | Il client MCP supporta un Client ID Metadata Document (CIMD) o la Dynamic Client Registration (DCR). | La registrazione non concede di per sé l'accesso all'account. L'applicazione deve comunque essere autorizzata nell'account selezionato. |
CIMD e DCR sono disponibili solo per le connessioni MCP. Per la REST API, usa un'applicazione di proprietà dell'account o di un partner.
Endpoint OAuth
Le nuove integrazioni dovrebbero usare gli endpoint globali. Il nome dell'account non è incluso in questi URL: l'utente seleziona un account durante l'autorizzazione.
| Scopo | Indirizzo |
|---|---|
| Issuer | https://auth.planfix.com
|
| Autorizzazione | https://auth.planfix.com/oauth/authorize
|
| Token | https://auth.planfix.com/oauth/token
|
| Informazioni utente | https://auth.planfix.com/oauth/userinfo
|
| Revoca del token | https://auth.planfix.com/oauth/revoke
|
| Registrazione dinamica del client MCP | https://auth.planfix.com/oauth/register
|
I metadati del server di autorizzazione sono disponibili agli endpoint standard:
https://auth.planfix.com/.well-known/oauth-authorization-server https://auth.planfix.com/.well-known/openid-configuration
URI di reindirizzamento
Un URI di reindirizzamento deve essere registrato nelle impostazioni dell'applicazione. Il valore inviato nella richiesta di autorizzazione deve corrispondere a un URI registrato.
Sono consentiti:
- URL
https; - URL
httpsolo per host loopback, comelocalhosto127.0.0.1.
La porta può essere dinamica per un URI loopback, ma lo schema, l'host, il percorso e la query devono corrispondere. Non sono consentiti frammenti URL né informazioni utente nell'URL.
Livelli di accesso
Un'applicazione riceve solo i livelli di accesso, o scopes, autorizzati in anticipo. Consulta Livelli di accesso REST API per l'elenco completo.
L'insieme richiesto deve essere un sottoinsieme degli scope registrati per l'applicazione. Gli scope dell'applicazione non estendono le autorizzazioni dell'utente in Planfix: l'applicazione può accedere solo ai dati disponibili al Dipendente che l'ha connessa.
Le applicazioni gestite hanno accesso anche agli scope di servizio userinfo, openid e email.
Autorizzazione utente
Genera un code_verifier e la sua rappresentazione SHA-256, code_challenge, quindi apri l'endpoint di autorizzazione in un browser.
Esempio per la REST API:
GET https://auth.planfix.com/oauth/authorize
?client_id=CLIENT_ID
&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
&response_type=code
&scope=openid%20email%20task_readonly
&state=RANDOM_STATE
&code_challenge=CODE_CHALLENGE
&code_challenge_method=S256
Per MCP, aggiungi il parametro resource con l'URL esatto del server MCP:
resource=https%3A%2F%2Fmcp.planfix.com%2Fmcp
| Parametro | Descrizione |
|---|---|
client_id
|
Identificativo di un'applicazione registrata. Per CIMD, è l'URL del documento dei metadati del client. |
redirect_uri
|
Uno degli URI di reindirizzamento consentiti. |
response_type
|
Deve essere code.
|
scope
|
Le autorizzazioni richieste, separate da spazi. Questo parametro è obbligatorio per la REST API. Un client MCP può ometterlo; in tal caso vengono usati gli scope consentiti per l'applicazione. |
state
|
Un valore casuale che protegge la richiesta dalla sostituzione. L'applicazione deve convalidarlo dopo il reindirizzamento. |
code_challenge
|
Hash SHA-256 di code_verifier codificato in Base64url senza padding.
|
code_challenge_method
|
È supportato solo S256.
|
resource
|
Per MCP, l'URL esatto del server MCP. Non inviare questo parametro per la REST API. |
Per MCP, usa resource=https://mcp.planfix.com/mcp.
L'utente seleziona un account, accede e controlla le autorizzazioni richieste. Un'applicazione di proprietà dell'account apre direttamente l'account proprietario. Se i criteri di sicurezza richiedono l'approvazione di un amministratore, Planfix mostra il passaggio corrispondente. Un amministratore può approvare l'applicazione e connetterla con un'unica operazione.
Dopo l'autorizzazione, Planfix reindirizza il browser a redirect_uri:
https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fauth.planfix.com
Un codice di autorizzazione può essere usato una sola volta ed è valido per 10 minuti.
Ottenere i token
Invia una richiesta POST a /oauth/token usando application/x-www-form-urlencoded:
grant_type=authorization_code &client_id=CLIENT_ID &code=AUTHORIZATION_CODE &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback &code_verifier=CODE_VERIFIER
Per MCP, ripeti il parametro resource con lo stesso valore usato nella richiesta di autorizzazione.
Un client pubblico invia la richiesta senza un segreto. Un client riservato esegue anche l'autenticazione usando client_secret_basic oppure i parametri client_id e client_secret nel corpo della richiesta.
Esempio di risposta:
{
"access_token": "ACCESS_TOKEN",
"token_type": "bearer",
"expires_in": 86400,
"refresh_token": "REFRESH_TOKEN",
"scope": "openid email task_readonly"
}
Per la REST API, la risposta contiene anche account_name, account_domain e account_url. Memorizza questi valori e usa l'URL dell'account selezionato per le richieste REST API.
Un token di accesso è valido per 24 ore. È associato all'utente, all'account, all'applicazione, agli scope e alla risorsa. Un token rilasciato per MCP non può essere usato direttamente con la REST API e un token REST API non può essere usato con MCP.
Usare un token con la REST API
Invia il token nell'intestazione Authorization:
GET https://account_name.planfix.com/rest/task/123 Authorization: Bearer ACCESS_TOKEN
Usa il dominio dell'account restituito quando il codice di autorizzazione è stato scambiato con un token. Sono disponibili solo i metodi coperti dagli scope concessi. I token OAuth sono soggetti al piano dell'account e ai limiti standard della REST API.
Informazioni utente
La richiesta userinfo richiede lo scope openid:
GET https://auth.planfix.com/oauth/userinfo Authorization: Bearer ACCESS_TOKEN
Esempio di risposta quando è presente lo scope email:
{
"sub": "123:user:456",
"email": "user@example.com",
"email_verified": true
}
L'autorizzazione OAuth globale è disponibile ai Dipendenti dell'account. Planfix non rilascia un id_token; richiedi invece i dati dell'utente tramite userinfo.
Aggiornare i token
POST https://auth.planfix.com/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token &client_id=CLIENT_ID &refresh_token=REFRESH_TOKEN
Per MCP, invia di nuovo lo stesso resource. Un client riservato deve autenticarsi usando il proprio segreto.
Planfix restituisce un nuovo token di accesso e un nuovo token di aggiornamento. Il token di aggiornamento precedente diventa subito non valido, quindi l'applicazione deve sostituire atomicamente il valore memorizzato.
Revocare un token
Un client può revocare un token di aggiornamento tramite /oauth/revoke:
POST https://auth.planfix.com/oauth/revoke Content-Type: application/x-www-form-urlencoded token=REFRESH_TOKEN &client_id=CLIENT_ID
Un utente può anche rimuovere una connessione dalla sezione Gestione sessioni della propria scheda utente. Un amministratore può revocare l'approvazione di un'applicazione di terze parti per l'intero account. Consulta Applicazioni OAuth e MCP in un account.
Compatibilità con le integrazioni esistenti
Gli endpoint specifici del tenant, come https://account.planfix.com/api/v2/oauth/authorize, /token e /userinfo, continuano a funzionare per le integrazioni esistenti associate a un account specifico.
Usa gli endpoint globali per le nuove integrazioni. Supportano l'individuazione standard dei metadati, la selezione dell'account e MCP. Non combinare endpoint globali e specifici del tenant nella stessa sessione OAuth.
Raccomandazioni di sicurezza
- Usa sempre PKCE S256 e convalida
state. - Usa un client pubblico senza segreto per le applicazioni mobili, desktop e browser.
- Usa un client riservato solo se il segreto può essere memorizzato in modo sicuro su un server.
- Richiedi il numero minimo necessario di scope.
- Non registrare nei log token di accesso, token di aggiornamento, codici di autorizzazione,
code_verifiero segreti client. - Memorizza i token di aggiornamento e i segreti client in un archivio crittografato.
- Convalida
issnella risposta e accetta solo l'issuer Planfix previsto.
Possibili errori
| Errore | Causa |
|---|---|
invalid_client
|
Il client è sconosciuto o disabilitato, il segreto client non è corretto oppure l'applicazione non è disponibile nell'account selezionato. |
invalid_grant
|
Il codice di autorizzazione o il token di aggiornamento non è valido, è scaduto, è già stato usato oppure non corrisponde al client, all'URI di reindirizzamento, ai dati PKCE o alla risorsa. |
invalid_scope
|
La richiesta contiene uno scope non consentito per l'applicazione. |
invalid_target
|
La resource non è supportata oppure è stata modificata tra una richiesta e l'altra.
|
access_denied
|
L'utente ha rifiutato la connessione oppure i criteri dell'account non consentono l'applicazione. |
HTTP 401, invalid_token
|
Il token di accesso è sconosciuto, è scaduto o è stato revocato. |
HTTP 403, insufficient_scope
|
Il token non contiene lo scope richiesto per l'operazione. |