Csatlakozás OAuth segítségével

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:

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:

{
  "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/<id> é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):

grant_type=authorization_code
client_id=<your client id>
code=<single-use authorization code>
redirect_uri=<exact registered redirect URI>
code_verifier=<original PKCE 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/<id> 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:

{
  "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#

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.