Aplicații OAuth pentru parteneri

De la Planfix

O aplicație OAuth deținută de un partener este destinată unei integrări care se conectează la mai multe conturi Planfix. Aceeași acreditare a aplicației se folosește pentru toate conturile clienților, în timp ce fiecare cont controlează admiterea separat și fiecare utilizator își dă consimțământul pentru conexiunea proprie.

Dacă o integrare este destinată unui singur cont, este mai simplu să creați o account-owned application.

Crearea unei aplicații

  1. Deschideți contul de partener.
  2. Mergereți la OAuth applications.
  3. Selectați Create application.
  4. Introduceți numele și descrierea pe care le vor vedea utilizatorii și administratorii.
  5. Selectați tipul de client OAuth.
  6. Adăugați URI-urile de redirect.
  7. Selectați scope-urile REST API minime necesare.
  8. Salvați aplicația și copiați acreditările ei.

O aplicație nouă este privată și necesită aprobarea explicită în fiecare cont la care se conectează.

Tip client OAuth

Tip Aplicații destinate Acreditări
Public Aplicații mobile, desktop și de browser, și clienți MCP locali. Un client_id doar. Nu există client secret; PKCE S256 este obligatoriu.
Confidential Aplicații server-side în care secretul poate fi stocat în afara dispozitivului utilizatorului și cod client-side. Un client_id și client_secret.

Tipul de client OAuth este separat de faptul dacă o aplicație este publicată. De exemplu, o aplicație mobilă privată este un client OAuth public fără secret.

Redirect URIs

Specificați fiecare URL către care Planfix poate returna un utilizator după autentificare.

  • Folosiți https pentru un serviciu web.
  • http este permis doar pentru adrese loopback, cum ar fi localhost și 127.0.0.1.
  • Un client poate folosi un port dinamic pentru o adresă loopback, dar schemele, gazda, calea și query-ul trebuie să coincidă.
  • Nu folosiți wildcard-uri, fragmente URL sau redirect URIs pe care nu le controlați.

Scope-uri

Scope-urile definesc permisiunile maxime ale aplicației. Solicitați doar nivelurile de acces necesare din REST API scope list.

Scope-urile aplicației nu înlocuiesc permisiunile normale ale utilizatorului. Chiar și atunci când un scope este acordat, aplicația poate lucra doar cu datele disponibile acelui utilizator.

Schimbarea redirect URIs sau a scope-urilor creează o nouă versiune ce necesită aprobare. Conturile conectate anterior trebuie să revizuiască și să aprobe noua versiune, iar utilizatorii trebuie să se reconecteze.

Conectarea unui cont client

O aplicație privată deținută de un partener trebuie aprobată explicit de un administrator în fiecare cont.

  1. Deschideți aplicația în contul dumneavoastră de partener.
  2. În zona linkului de aprobare, introduceți numele contului client.
  3. Copiați linkul generat și trimiteți-l unui administrator al acelui cont.
  4. Rugați administratorul să verifice proprietarul, redirect URIs și scope-urile, apoi să aprobe aplicația.
  5. După aprobare, utilizatorii din cont pot finaliza autorizarea OAuth. Fiecare utilizator își dă consimțământul separat în nume propriu.

Linkul deschide Account management → API → OAuth and MCP applications și afișează aplicația solicitată.

Un administrator care conectează și el aplicația poate selecta Approve and connect.

Aplicații private și publicate

Stare Cum este admisă într-un cont
Private Necesită întotdeauna aprobarea explicită a unui administrator din fiecare cont.
Published Disponibilă fără aprobare separată când politica contului este Allow published applications. În continuare necesită aprobare când politica este Approved applications only.

Publicarea este o revizuire separată Planfix. Înainte de a trimite o aplicație pentru publicare, pregătiți un nume și o descriere clare, un set minim de scope-uri, redirect URIs funcționale și documentație pentru utilizator despre conectare și eliminare a integrării. Contactați Planfix Support pentru procedura de publicare.

Adrese de conectare

Folosiți endpoint-urile globale OAuth:

Scop Adresă
Authorization https://auth.planfix.com/oauth/authorize
Token https://auth.planfix.com/oauth/token
Userinfo https://auth.planfix.com/oauth/userinfo
MCP https://mcp.planfix.com/mcp

Nu adăugați numele contului la un URL global. Utilizatorul selectează contul pe o pagină Planfix. Protocolul complet, inclusiv resource, PKCE, reîmprospătarea token-urilor și revocarea este descris în OAuth 2.0 pentru aplicații.

Administrarea unei aplicații

Un partener poate:

  • edita numele și descrierea;
  • schimba redirect URIs și scope-urile;
  • dezactiva și reactiva aplicația;
  • roti client secret-ul unei aplicații confidential;
  • genera un link de aprobare a aplicației pentru un cont specific.

După rotația secretului, vechiul client secret încetează să mai funcționeze imediat. Actualizați secretul pe serverul de integrare și nu îl trimiteți niciodată utilizatorilor.

Dezactivarea unei aplicații blochează autorizarea OAuth și token-urile emise în fiecare cont. Această acțiune afectează toți clienții care folosesc aplicația.

Recomandări înainte de lansare

  • Folosiți Authorization Code cu PKCE S256 și validați state.
  • Solicitați doar scope-urile de care aveți nevoie.
  • Afișați contul selectat utilizatorului după autentificare.
  • Gestionați rotația refresh token-urilor: după un refresh reușit, refresh token-ul anterior nu mai este valid.
  • Nu scrieți token-urile, codurile de autorizare, code_verifier sau client secret-urile în loguri.
  • Documentați cum pot utilizatorii deconecta integrarea și solicita ștergerea datelor lor.
  • Testați scenarii de revocare a aprobării, dezactivare a aplicației și reconectare.

Mergeți la