Skip to content

OAuth 2.0 pro aplikace

OAuth 2.0 umožňuje aplikaci přistupovat k Planfixu jménem uživatele, aniž by požadovala nebo uchovávala uživatelovo heslo.

Planfix používá postup Authorization Code s povinným PKCE S256. OAuth lze použít pro připojení k REST API nebo k Planfix MCP serveru.

Pokud chcete připojit hotového AI klienta, začněte s Planfix MCP. Pokud spravujete přístupy ve svém účtu, viz OAuth and MCP applications in an account. Partneři a vývojáři integrací pro více účtů by měli vidět OAuth applications for partners.

Možnosti registrace aplikace

Možnost Kdy ji použít Kde funguje
Aplikace vlastněná účtem Integrace je určena pro jeden účet a klient potřebuje předem dané client_id. Pouze v účtu, který ji vlastní.
Aplikace vlastněná partnerem Ta samá aplikace se musí připojovat k více zákaznickým účtům. V účtech, kde je to povoleno bezpečnostní politikou nebo administrátorem.
Automatická registrace MCP klienta MCP klient podporuje Client ID Metadata Document (CIMD) nebo Dynamic Client Registration (DCR). Registrace sama o sobě nepovoluje přístup k účtu. Aplikace musí být v zvoleném účtu stále povolena.

CIMD a DCR jsou dostupné pouze pro MCP připojení. Pro REST API použijte aplikaci vlastněnou účtem nebo partnerem.

OAuth endpointy

Nové integrace by měly používat globální endpointy. Název účtu není v těchto URL zahrnut: uživatel vybere účet během autorizace.

Účel Adresa
Issuer https://auth.planfix.com
Authorization https://auth.planfix.com/oauth/authorize
Token https://auth.planfix.com/oauth/token
User information https://auth.planfix.com/oauth/userinfo
Token revocation https://auth.planfix.com/oauth/revoke
Dynamic MCP client registration https://auth.planfix.com/oauth/register

Metadata autorizačního serveru je dostupné na standardních endpointách: 

https://auth.planfix.com/.well-known/oauth-authorization-server
https://auth.planfix.com/.well-known/openid-configuration

Přesměrovací URI

Přesměrovací URI musí být registrováno v nastavení aplikace. Hodnota zaslaná v autorizačním požadavku musí přesně odpovídat registrovanému URI.

Povolené jsou:

  • https URL;
  • http URL pouze pro loopback hosty, jako localhost nebo 127.0.0.1.

Port může být dynamický pro loopback URI, ale jeho schéma, host, cesta a query musí souhlasit. URL fragmenty a uživatelské informace v URL nejsou povoleny.

Úrovně přístupu

Aplikace obdrží pouze ty úrovně přístupu, tedy scopes, které byly předem povoleny. Kompletní seznam viz REST API access levels.

Požadovaná sada musí být podmnožinou rozsahů registrovaných pro aplikaci. Aplikační scopey nerozšiřují oprávnění uživatele v Planfixu: aplikace může přistupovat pouze k datům, která jsou dostupná zaměstnanci, který ji připojil.

Spravované aplikace také obdrží servisní scopey userinfo, openid a email.

Autorizace uživatele

Vygenerujte code_verifier a jeho SHA-256 reprezentaci, code_challenge, a poté otevřete autorizační endpoint v prohlížeči.

Příklad pro 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

Pro MCP přidejte parametr resource s přesnou URL MCP serveru: 

resource=https%3A%2F%2Fmcp.planfix.com%2Fmcp
Parametr Popis
client_id Identifikátor registrované aplikace. Pro CIMD je to URL dokumentu metadat klienta.
redirect_uri Jedno z povolených přesměrovacích URI.
response_type Musí být code.
scope Požadovaná oprávnění oddělená mezerami. Tento parametr je povinný pro REST API. MCP klient ho může vynechat, v takovém případě se použijí scopey povolené pro aplikaci.
state Náhodná hodnota, která chrání požadavek před podvržením. Aplikace ji musí po přesměrování ověřit.
code_challenge Base64url bez paddingu SHA-256 hashe code_verifier.
code_challenge_method Podporováno pouze S256.
resource Pro MCP přesná URL https://mcp.planfix.com/mcp. Tento parametr neposílejte pro REST API.

Uživatel vybere účet, přihlásí se a zkontroluje požadovaná oprávnění. Aplikace vlastněná účtem otevře přímo svůj vlastní účet. Pokud bezpečnostní politika vyžaduje schválení administrátorem, Planfix zobrazí příslušný krok. Administrátor může aplikaci schválit a připojit ji jedním úkonem.

Po úspěšné autorizaci Planfix přesměruje prohlížeč na redirect_uri: 

https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fauth.planfix.com

Autorizační kód lze použít pouze jednou a je platný 10 minut.

Získání tokenů

Pošlete POST požadavek na /oauth/token s typem obsahu 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

Pro MCP zopakujte parametr resource se stejnou hodnotou jako v autorizačním požadavku.

Veřejný klient posílá požadavek bez tajemství. Důvěrný klient se navíc autentizuje pomocí client_secret_basic nebo parametry client_id a client_secret v těle požadavku.

Příklad odpovědi: 

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid email task_readonly"
}

Pro REST API odpověď také obsahuje account_name, account_domain a account_url. Uložte tyto hodnoty a použijte URL vybraného účtu pro REST API požadavky.

Přístupový token je platný 24 hodin. Je vázán na uživatele, účet, aplikaci, scopey a resource. Token vydaný pro MCP nelze použít přímo s REST API a REST API token nelze použít s MCP.

Použití tokenu s REST API

Token pošlete v hlavičce Authorization: 

GET https://account.planfix.com/rest/task/123
Authorization: Bearer ACCESS_TOKEN

Použijte URL účtu vrácenou při výměně autorizačního kódu za tokeny. Jsou dostupné pouze metody pokryté udělenými scopey. OAuth tokeny podléhají tarifu účtu a standardním REST API limits.

Informace o uživateli

Požadavek userinfo vyžaduje scope openid: 

GET https://auth.planfix.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Příklad odpovědi pokud je přítomen scope email: 

{
  "sub": "123:user:456",
  "email": "user@example.com",
  "email_verified": true
}

Globální OAuth autorizace je dostupná zaměstnancům účtu. Planfix nevydává id_token; uživatelská data místo toho požádejte přes userinfo.

Obnova 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

Pro MCP znovu pošlete stejný resource. Důvěrný klient se musí autentizovat pomocí svého tajemství.

Planfix vrátí nový access token a nový refresh token. Předchozí refresh token se stane okamžitě neplatným, proto musí aplikace uloženou hodnotu atomicky nahradit.

Odvolání tokenu

Klient může odvolat refresh token pomocí /oauth/revoke: 

POST https://auth.planfix.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN
&client_id=CLIENT_ID

Uživatel může také odebrat připojení v sekci „Správa relací“ na své uživatelské kartě. Administrátor může odvolat schválení třetí strany pro celý účet. Viz OAuth and MCP applications in an account.

Kompatibilita se stávajícími integracemi

Tenant endpointy jako https://account.planfix.com/api/v2/oauth/authorize, /token a /userinfo nadále fungují pro stávající integrace vázané na konkrétní účet.

Pro nové integrace používejte globální endpointy. Podporují standardní discovery metadat, výběr účtu a MCP. Nemíchejte globální a tenant endpointy v jedné OAuth relaci.

Doporučení pro bezpečnost

  • Vždy používejte PKCE S256 a validujte state.
  • Pro mobilní, desktopové a webové aplikace bez serveru použijte veřejného klienta bez tajemství.
  • Důvěrného klienta používejte pouze tehdy, lze-li tajemství bezpečně uložit na serveru.
  • Požadujte minimální nezbytnou sadu scopeů.
  • Nezapisujte access tokeny, refresh tokeny, autorizační kódy, code_verifier ani client secret do logů.
  • Ukládejte refresh tokeny a client secret v šifrovaném úložišti.
  • Validujte iss v odpovědi a akceptujte pouze očekávaného Planfix issueru.

Možné chyby

Chyba Příčina
invalid_client Klient je neznámý nebo zakázaný, client secret je nesprávný, nebo aplikace není dostupná ve vybraném účtu.
invalid_grant Autorizační kód nebo refresh token je neplatný, expirovaný, již použitý, nebo neodpovídá klientovi, redirect URI, PKCE datům či resource.
invalid_scope Požadavek obsahuje scope, který není pro aplikaci povolen.
invalid_target resource není podporováno nebo se mezi požadavky změnilo.
access_denied Uživatel odmítl připojení nebo politika účtu aplikaci nedovoluje.
HTTP 401, invalid_token Access token je neznámý, expirovaný nebo odvolaný.
HTTP 403, insufficient_scope Token neobsahuje scope požadovaný pro operaci.

Přejít na

Citováno z „http://planfix.com/cs/help/index.php?title=OAuth_2.0_pro_aplikace&oldid=6278“