--- title: "Csatlakozás OAuth segítségével" description: "Engedélyezze az MCP-klienseket és a ThunderPhone CLI-t API-kulcs megosztása nélkül." --- Az OAuth lehetővé teszi, hogy egy alkalmazás az Ön által jóváhagyott jogosultságokkal csatlakozzon egy ThunderPhone-szervezethez. A könyvtárklienseknek alapértelmezés szerint OAuthot kell használniuk. A szervezeti API-kulcsok továbbra is elérhetők azokhoz a kliensekhez, amelyek manuálisan konfigurált Bearer tokent igényelnek. ## Kapcsolat jóváhagyása Indítsa el a kapcsolatot az MCP-kliensben. Jelentkezzen be a ThunderPhone-ba, ellenőrizze az alkalmazás nevét és a kért jogosultságokat, válasszon egy szervezetet, majd válassza a **Jóváhagyás** lehetőséget. Válassza az **Elutasítás** lehetőséget, ha nem Ön indította el a kapcsolatot, vagy nem bízik az alkalmazásban. Az alkalmazásneveket a fejlesztőik adják meg, és nem minősülnek hitelesítési jelvénynek. Az olvasási jogosultságok hozzáférést adnak a megnevezett adatokhoz, beleértve a felvételeket és az átiratokat is, amikor a `calls:read` jogosultságot kérik. Az írási jogosultságok módosíthatnak vagy törölhetnek erőforrásokat; a hívások, kampányok, telefonszám-vásárlások és üzembe helyezések költségeket okozhatnak, vagy hatással lehetnek az éles környezetre. Az Ön szervezeti szerepköre továbbra is érvényes. CLI-kapcsolathoz nyissa meg a terminálban megjelenő ellenőrzési hivatkozást, hasonlítsa össze a nyolc karakterből álló kódot, válassza ki a szervezetét, majd hagyja jóvá. A hivatkozás puszta megnyitása nem ad hozzáférést. A kódok 15 perc után lejárnak. ## Alkalmazás leválasztása Nyissa meg az irányítópulton a **Szervezet → API-kulcsok → Engedélyezett alkalmazások** menüt, majd válassza a **Visszavonás** lehetőséget. Ez visszavonja az aktuális szervezethez kiválasztott engedélyezését, beleértve a hozzáférési és frissítési tokeneket is. Ha újra engedélyezni szeretné, csatlakozzon újra az alkalmazásból. ## MCP-kliensek felderítése Használja a `https://api.thunderphone.com/v1/mcp` szerver URL-jét. Az érvényes hitelesítés nélküli kérés `401` választ kap a következővel: ```http WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource" ``` Kérje le ezt a dokumentumot, majd kérje le az engedélyezési szerver metaadatait a `https://api.thunderphone.com/.well-known/oauth-authorization-server` címen. Az erőforrás-metaadatok a `/.well-known/oauth-protected-resource/v1/mcp` címen is elérhetők. A visszaadott végpontokat használja azok összeállítása helyett. Az erőforrás-azonosító: `https://api.thunderphone.com/v1/mcp`. A szerver támogatja az engedélyezési kódos folyamatot **S256 PKCE**-vel, a forgó frissítési tokeneket, a nyilvános dinamikus kliensregisztrációt, a visszavonást és az eszközengedélyezési jogosultságot. Nincsenek kliens titkos kulcsok vagy implicit jogosultságok. Az OpenID-felderítés a `/.well-known/openid-configuration` címen is elérhető; ugyanazokat az engedélyezési szervermezőket tartalmazza, kiegészítve a `subject_types_supported: ["public"]` mezővel és a userinfo végponttal. Az ID tokenek és a Client ID Metadata Documents (CIMD) nem támogatottak. ### Nyilvános kliens regisztrálása Küldjön JSON-t a `POST /v1/oauth/register` végpontnak: ```json { "client_name": "My MCP client", "redirect_uris": ["http://127.0.0.1:8765/callback"], "token_endpoint_auth_method": "none", "grant_types": ["authorization_code", "refresh_token"], "response_types": ["code"] } ``` Mentse el a visszaadott `client_id` értéket. Az átirányításoknak HTTPS-t kell használniuk, vagy HTTP-t a `127.0.0.1` illetve `localhost` címen. Regisztrálja a pontos visszahívási URI-t, beleértve a portot és az útvonalat is. A fragmentumokat és a beágyazott hitelesítő adatokat a rendszer elutasítja. Az opcionális `client_uri` és `logo_uri` értékeknek HTTPS-t kell használniuk; a ThunderPhone ezeket nem kéri le a regisztráció során. A regisztráció sebességkorlátozott. A regisztrált kliensek nem járnak le, és kapcsolat visszavonásakor is regisztráltak maradnak. A HTTPS-visszahívások közé tartozik a `https://chatgpt.com/connector/oauth/` és a `https://chatgpt.com/connector_platform_oauth_redirect`. Minden kapcsolat saját klienst regisztrálhat. ### Engedélyezési kód Nyissa meg a felderített engedélyezési végpontot a `client_id`, a pontosan regisztrált `redirect_uri`, a `response_type=code`, egy véletlenszerű `state`, a `scope`, a `code_challenge`, a `code_challenge_method=S256` és a `resource=https://api.thunderphone.com/v1/mcp` paraméterekkel. A kihívást egy új, nagy entrópiájú PKCE-hitelesítő nem kitöltött base64url SHA-256 kivonataként számítsa ki. A kód cseréje előtt ellenőrizze a visszaadott `state` és `iss` értékeket. Minden engedélyezési válasz, beleértve az elutasítást és a protokollhibákat is, az `iss` értékkel azonosítja a kibocsátót, amelynek pontosan meg kell egyeznie a felderített `issuer` értékkel. Az érvénytelen kliensre vagy visszahívásra vonatkozó hibák helyben, az adott visszahívásra történő átirányítás nélkül érkeznek vissza. Cserélje be a kódot a `POST /v1/oauth/token` végponton űrlapkódolással (a JSON is elfogadott): ```text grant_type=authorization_code client_id= code= redirect_uri= code_verifier= resource=https://api.thunderphone.com/v1/mcp ``` Az opcionális `resource` paraméter mind az engedélyezési, mind a tokenkéréseknél elfogadott, beleértve a frissítési és eszközcseréket is. Ha nincs megadva, alapértelmezés szerint a felderített MCP-erőforrást használja. Ha meg van adva, pontosan meg kell egyeznie ezzel az erőforrással; más értékek `invalid_target` választ adnak. A hozzáférési tokenek ezt a célközönséget hordozzák, és az MCP `401` válasszal és felderítési kihívással elutasítja a hiányzó vagy eltérő célközönségű tokeneket. Az engedélyezési kérések és kódok 10 perc után lejárnak. Minden tokenválasz tartalmaz `access_token`, `token_type` (`Bearer`), `expires_in` (alapértelmezés szerint 3600 másodperc), `refresh_token`, `scope`, `organization_id` és `organization_name` értéket. Hozzáférési tokeneket kizárólag az `Authorization: Bearer` fejlécen keresztül küldjön. Soha ne helyezzen tokeneket URL-ekbe, naplókba, forráskód-kezelőbe vagy csevegésbe. ### Frissítés és visszavonás Frissítsen a token végponton a `grant_type=refresh_token`, `client_id`, `refresh_token` és `resource` paraméterekkel. Az új frissítési tokent atomikusan mentse el, és ne használja tovább a régit. A frissítési tokenek sikeres frissítés nélkül 30 nap után lejárnak. Az opcionális `scope` leszűkítheti a megadott jogosultságokat. Az `offline_access` mindig szerepel, és frissítési token mindig kiadásra kerül. Egy `scope` nélküli kezdeti kérés csak `offline_access` jogosultságot ad, ezért a klienseknek kérniük kell a szükséges jogosultságokat. A kód újrafelhasználása és a forgatott frissítési token újrafelhasználása visszavonja a teljes engedélyezést. Egy kliensen belül sorosítsa a frissítéseket; egy sikeresen kicserélt hitelesítő adat ismételt elküldése nem biztonságos újrapróbálási stratégia. A kapcsolat bontásához küldje el a `token` és `client_id` értékeket a `POST /v1/oauth/revoke` végpontnak. Bármelyik token visszavonása visszavonja annak engedélyezését, beleértve az abból kiadott összes tokent is. Egy ismeretlen token sikeres választ ad anélkül, hogy felfedné annak létezését. A dashboard-munkamenetek a `GET /v1/oauth/grants` végponton listázhatják saját engedélyezéseiket, és egyet a `DELETE /v1/oauth/grants/` végponton vonhatnak vissza; az `X-ThunderPhone-Org` választja ki a szervezetet. ### Eszközengedélyezés Az eszközengedélyezés csak előre regisztrált kliensek számára érhető el; a dinamikusan regisztrált kliensek `unauthorized_client` választ kapnak. Az előre regisztrált nyilvános `thunderphone-cli` kliens támogatja az eszközengedélyezést és a frissítést. Küldje el a `client_id=thunderphone-cli` és `scope` paramétereket a `POST /v1/oauth/device/code` végpontnak. Jelenítse meg a felhasználónak a `user_code` és `verification_uri` értékeket, vagy nyissa meg a `verification_uri_complete` címet. Kérdezze le a token végpontot a `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id` és `device_code` paraméterekkel, legalább a visszaadott `interval` idejét várva (5 másodperc). `authorization_pending` esetén folytassa. `slow_down` esetén minden további kéréshez használja a válaszban visszaadott új `interval` értéket, amely 5 másodperccel nőtt. `access_denied`, `expired_token` vagy bármely más hiba esetén álljon le. Soha ne hagyjon jóvá automatikusan eszközkódot. Az előre regisztrált `thunderphone-mcp` kliens bármely porton elfogadja a `http://127.0.0.1/callback` és `http://localhost/callback` címeket. A sémának, a gépnévnek, az útvonalnak és a lekérdezésnek egyeznie kell; a tokencserének az engedélyezésből származó pontos átirányítási URI-t kell használnia, beleértve a portot is. A dinamikusan regisztrált kliensek pontos átirányítási URI-egyezést igényelnek, beleértve a portot is. Ha másik útvonalra van szüksége, regisztráljon dinamikusan másik visszahívást. ### Fiókazonosság és munkaterületi tartomány ellenőrzése Kérje az `openid email` hatóköröket is a kliensének szükséges műveleti hatókörök mellett. Hívja meg a felderített `userinfo_endpoint` végpontot (`GET /v1/oauth/userinfo`) a hozzáférési tokennel a Bearer fejlécben. A sikeres válasz a következőket tartalmazza: ```json { "sub": "123", "email": "person@example.com", "email_verified": true, "name": "Example User", "org_id": 456 } ``` A `sub` a stabil felhasználóazonosító; az `org_id` a hozzájárulás során kiválasztott szervezet. A végpont mindkét azonossági hatókört megköveteli, és `403` választ ad, ha bármelyik hiányzik. `403` választ ad `error=access_denied` értékkel, ha a fióknak nincs ellenőrzött e-mail-profilja, ahelyett hogy egy ellenőrizetlen e-mail-címet megbízhatónak tekintene. Az érvénytelen, lejárt, visszavont vagy hibás célközönségű tokenek `401` választ adnak. Emberi munkamenet-tokenek és szervezeti API-kulcsok nem hívhatják a userinfo végpontot. ID token nem kerül kiadásra. ## Elérhető engedélyek | Terület | Hatókörök | | --- | --- | | AI-ügynökök és ügynökimportálások | `agents:read`, `agents:write` | | Hívások | `calls:read`, `calls:write` | | Telefonszámok, blokkolt hívók és VoIP | `numbers:read`, `numbers:write` | | Tudás | `knowledge:read`, `knowledge:write` | | Kampányok | `campaigns:read`, `campaigns:write` | | Integrációk, webhook-végpontok, MCP-kiszolgálók | `integrations:read`, `integrations:write` | | Hangok | `voices:read` | | Tesztforgatókönyvek, tesztfuttatások, validálás | `testing:read`, `testing:write` | | Számlázás | `billing:read` | | Fiókazonosság és ellenőrzött e-mail-cím | `openid`, `email` (mindkettő szükséges a userinfo használatához) | | Állandó kapcsolat | `offline_access` (mindig szerepel) | A GET, HEAD és OPTIONS olvasási hatóköröket használ; a többi metódus írási hatóköröket. Hang- és számlázási módosítások OAuthon keresztül nem érhetők el; a `POST /v1/voices/preview` a `voices:read` hatókört használja, mert konfigurációmódosítás nélkül tekint elő egy hangot. Az MCP-eszközök az alapul szolgáló REST-műveletük hatókörét érvényesítik. A szervezetek közötti átvitelek akkor is elutasításra kerülnek, ha az engedélyező felhasználó mindkét szervezethez tartozik. Más API-családok, beleértve az API-kulcsok kezelését és a felhasználói fiókbeállításokat, OAuthon keresztül nem érhetők el. Egy REST-művelethez hiányzó engedély `403` választ ad `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."` értékkel. Az érvénytelen vagy lejárt hozzáférési tokenek `401` választ adnak. ### MCP-eszközök hitelesítési jelzései A `tools/list` minden eszköze tartalmazza a `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]` értéket, az adott eszköz REST-műveletének hatókörével. A nyilvános dokumentációs eszközök üres hatókörlistát használnak, és továbbra is hitelesített kapcsolatot igényelnek. Egy érvényes token, amelyből hiányzik egy eszköz hatóköre, HTTP `200` választ kap egy olyan JSON-RPC `result` értékkel, amely `isError: true` értéket, magyarázó szöveget a `content` mezőben és `_meta["mcp/www_authenticate"]` értéket tartalmaz. Ez utóbbi egy tömb, amely egy Bearer kihívást tartalmaz `resource_metadata`, `error="insufficient_scope"`, `error_description` és a szükséges `scope` értékkel. Az eszköz nem fut le. Ezzel a kihívással kérjen kibővített hozzájárulást. A hiányzó vagy érvénytelen hitelesítés továbbra is HTTP `401` választ ad `WWW-Authenticate` értékkel; a REST-hatókör hibái továbbra is HTTP `403` választ adnak. ## Hitelesítő adatok megőrzése Az API óránként futtatja a `python manage.py oauth_cleanup` parancsot előkészítő és éles környezetben. Eltávolítja a lejárt engedélyezési kéréseket és eszközkódokat. A lejárt hozzáférési tokenek, engedélyezési kódok és frissítésitoken-hashek csak azután kerülnek törlésre, hogy az engedélyezésüket visszavonták, vagy a teljes család inaktívvá vált. A felhasznált hashek megmaradnak, amíg a család rendelkezik használható frissítési tokennel, engedélyezési kóddal, jóváhagyott eszközkóddal vagy hozzáférési tokennel, így a tisztítás nem kapcsolhatja ki a visszajátszásészlelést.