--- title: "Prisijungimas naudojant OAuth" description: "Suteikite leidimą MCP klientams ir ThunderPhone CLI nesidalydami API raktu." --- OAuth leidžia programai prisijungti prie vienos ThunderPhone organizacijos su jūsų patvirtintais leidimais. Katalogų klientai pagal numatytuosius nustatymus turėtų naudoti OAuth. Organizacijos API raktai lieka prieinami klientams, kuriems reikia rankiniu būdu sukonfigūruoto Bearer prieigos rakto. ## Patvirtinkite prisijungimą Pradėkite prisijungimą savo MCP kliente. Prisijunkite prie ThunderPhone, patikrinkite programos pavadinimą ir prašomus leidimus, pasirinkite organizaciją ir spustelėkite **Patvirtinti**. Pasirinkite **Atmesti**, jei nepradėjote prisijungimo arba nepasitikite programa. Programų pavadinimus pateikia jų kūrėjai ir jie nėra patvirtinimo ženklas. Skaitymo leidimai suteikia prieigą prie nurodytų duomenų, įskaitant įrašus ir transkriptus, kai prašoma `calls:read`. Rašymo leidimai gali keisti arba ištrinti išteklius; skambučiai, kampanijos, telefono numerių pirkimai ir diegimai gali sukelti išlaidų arba paveikti produkcinę aplinką. Jūsų organizacijos vaidmuo vis tiek taikomas. Norėdami prisijungti per CLI, atidarykite terminale rodomą patvirtinimo nuorodą, palyginkite aštuonių simbolių kodą, pasirinkite organizaciją ir patvirtinkite. Vien nuorodos atidarymas nesuteikia prieigos. Kodų galiojimas baigiasi po 15 minučių. ## Atjunkite programą Atidarykite valdymo skydelyje **Organizacija → API raktai → Įgaliotos programos** ir pasirinkite **Atšaukti**. Taip atšaukiamas jūsų pasirinktas įgaliojimas dabartinei organizacijai, įskaitant jos prieigos ir atnaujinimo prieigos raktus. Jei norite vėl ją įgalioti, prisijunkite iš programos dar kartą. ## Aptikimas MCP klientams Naudokite serverio URL `https://api.thunderphone.com/v1/mcp`. Užklausa be tinkamo autentifikavimo gauna `401` su: ```http WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource" ``` Gaukite šį dokumentą, tada gaukite autorizavimo serverio metaduomenis adresu `https://api.thunderphone.com/.well-known/oauth-authorization-server`. Išteklių metaduomenys taip pat pasiekiami adresu `/.well-known/oauth-protected-resource/v1/mcp`. Naudokite grąžintus galinius taškus, užuot juos sudarę patys. Ištekliaus identifikatorius yra `https://api.thunderphone.com/v1/mcp`. Serveris palaiko autorizavimo kodą su **S256 PKCE**, keičiamus atnaujinimo prieigos raktus, viešą dinaminį kliento registravimą, atšaukimą ir įrenginio autorizavimo suteikimą. Kliento paslapčių ir numanomų suteikimų nėra. OpenID aptikimas taip pat pasiekiamas adresu `/.well-known/openid-configuration`; jame pateikiami tie patys autorizavimo serverio laukai, taip pat `subject_types_supported: ["public"]` ir userinfo galinis taškas. ID prieigos raktai ir kliento ID metaduomenų dokumentai (CIMD) nepalaikomi. ### Užregistruokite viešą klientą Siųskite JSON į `POST /v1/oauth/register`: ```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"] } ``` Išsaugokite grąžintą `client_id`. Peradresavimams būtina naudoti HTTPS arba HTTP su `127.0.0.1` ar `localhost`. Užregistruokite tikslų atgalinio iškvietimo URI, įskaitant jo prievadą ir kelią. Fragmentai ir įterpti prisijungimo duomenys atmetami. Pasirinktiniai `client_uri` ir `logo_uri` turi naudoti HTTPS; ThunderPhone registravimo metu jų negauna. Registravimui taikomas dažnio ribojimas. Užregistruotų klientų galiojimas nesibaigia ir jie lieka užregistruoti atšaukus ryšį. HTTPS atgaliniai iškvietimai apima `https://chatgpt.com/connector/oauth/` ir `https://chatgpt.com/connector_platform_oauth_redirect`. Kiekvienas ryšys gali registruoti savo klientą. ### Autorizavimo kodas Atidarykite aptiktą autorizavimo galinį tašką su `client_id`, tiksliu užregistruotu `redirect_uri`, `response_type=code`, atsitiktiniu `state`, `scope`, `code_challenge`, `code_challenge_method=S256` ir `resource=https://api.thunderphone.com/v1/mcp`. Apskaičiuokite iššūkį kaip naujo didelės entropijos PKCE tikrintojo SHA-256 santrauką base64url formatu be užpildymo. Prieš keisdami kodą patikrinkite grąžintus `state` ir `iss`. Kiekvienas autorizavimo atsakymas, įskaitant atmetimą ir protokolo klaidas, nurodo išdavėją naudodamas `iss`, tiksliai atitinkantį aptiktą `issuer`. Netinkamo kliento ar atgalinio iškvietimo klaidos grąžinamos lokaliai, neperadresuojant į tą atgalinį iškvietimą. Keiskite adresu `POST /v1/oauth/token` naudodami formos kodavimą (taip pat priimamas JSON): ```text grant_type=authorization_code client_id= code= redirect_uri= code_verifier= resource=https://api.thunderphone.com/v1/mcp ``` Pasirinktinis `resource` parametras priimamas tiek autorizavimo, tiek prieigos rakto užklausose, įskaitant atnaujinimo ir įrenginio keitimus. Jei jis nenurodytas, pagal numatytuosius nustatymus naudojamas aptiktas MCP išteklius. Jei nurodytas, jis turi tiksliai atitikti tą išteklių; kitos reikšmės grąžina `invalid_target`. Prieigos raktai turi šią auditoriją, o MCP atmeta prieigos raktus su trūkstama ar kitokia auditorija, grąžindamas `401` ir aptikimo užklausą. Autorizavimo užklausų ir kodų galiojimas baigiasi po 10 minučių. Kiekviename prieigos rakto atsakyme yra `access_token`, `token_type` (`Bearer`), `expires_in` (pagal numatytuosius nustatymus 3600 sekundžių), `refresh_token`, `scope`, `organization_id` ir `organization_name`. Siųskite prieigos raktus tik per `Authorization: Bearer` antraštę. Niekada nedėkite prieigos raktų į URL, žurnalus, šaltinio valdymą ar pokalbius. ### Atnaujinkite ir atšaukite Atnaujinkite naudodami `grant_type=refresh_token`, `client_id`, `refresh_token` ir `resource` prieigos rakto galiniame taške. Atomiškai išsaugokite naują atnaujinimo prieigos raktą ir nebevartokite senojo. Atnaujinimo prieigos raktų galiojimas baigiasi po 30 dienų be sėkmingo atnaujinimo. Pasirinktinis `scope` gali susiaurinti suteiktas teises. `offline_access` visada įtraukiamas, o atnaujinimo prieigos raktai visada išduodami. Pradinė užklausa be `scope` suteikia tik `offline_access`, todėl klientai turėtų prašyti jiems reikalingų teisių. Pakartotinis kodo naudojimas ir pakeisto atnaujinimo prieigos rakto pakartotinis naudojimas atšaukia visą autorizavimą. Viename kliente vykdomus atnaujinimus atlikite nuosekliai; sėkmingai pakeisto kredencialo pakartojimas nėra saugi pakartotinio bandymo strategija. Norėdami atjungti, siųskite `token` ir `client_id` į `POST /v1/oauth/revoke`. Atšaukus bet kurį prieigos raktą atšaukiamas jo autorizavimas, įskaitant visus iš jo išduotus prieigos raktus. Nežinomas prieigos raktas grąžina sėkmę neatskleisdamas, ar jis egzistuoja. Valdymo skydelio sesijos gali išvardyti savo autorizavimus adresu `GET /v1/oauth/grants` ir atšaukti vieną adresu `DELETE /v1/oauth/grants/`, o organizacija pasirenkama naudojant `X-ThunderPhone-Org`. ### Įrenginio autorizavimas Įrenginio autorizavimas ribojamas iš anksto užregistruotiems klientams; dinamiškai užregistruoti klientai gauna `unauthorized_client`. Iš anksto užregistruotas viešasis klientas `thunderphone-cli` palaiko įrenginio autorizavimą ir atnaujinimą. Siųskite `client_id=thunderphone-cli` ir `scope` į `POST /v1/oauth/device/code`. Rodykite naudotojui `user_code` ir `verification_uri` arba atidarykite `verification_uri_complete`. Apklauskite prieigos rakto galinį tašką naudodami `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id` ir `device_code`, laukdami bent grąžinto `interval` (5 sekundes). Tęskite gavę `authorization_pending`. Gavę `slow_down`, kiekvienai vėlesnei užklausai naudokite atsakyme grąžintą naują `interval` (padidintą 5 sekundėmis). Sustokite gavę `access_denied`, `expired_token` ar bet kokią kitą klaidą. Niekada nepatvirtinkite įrenginio kodo automatiškai. Iš anksto užregistruotas klientas `thunderphone-mcp` priima `http://127.0.0.1/callback` ir `http://localhost/callback` su bet kuriuo prievadu. Schema, pagrindinis kompiuteris, kelias ir užklausa turi sutapti; keičiant prieigos raktą būtina naudoti tikslų autorizavimo metu naudotą peradresavimo URI, įskaitant prievadą. Dinamiškai užregistruotiems klientams būtinas tikslus peradresavimo URI sutapimas, įskaitant prievadą. Jei reikia kito kelio, dinamiškai užregistruokite kitą atgalinį iškvietimą. ### Paskyros tapatybės ir darbo srities domeno patikros Prašykite abiejų `openid email` kartu su operacijos apimtimis, kurių reikia jūsų klientui. Iškvieskite aptiktą `userinfo_endpoint` (`GET /v1/oauth/userinfo`) su prieigos raktu Bearer antraštėje. Sėkmingame atsakyme pateikiama: ```json { "sub": "123", "email": "person@example.com", "email_verified": true, "name": "Example User", "org_id": 456 } ``` `sub` yra stabilus naudotojo identifikatorius; `org_id` yra sutikimo metu pasirinkta organizacija. Galiniam taškui reikalingos abi tapatybės apimtys ir jis grąžina `403`, jei kurios nors trūksta. Jei paskyra neturi patvirtinto el. pašto profilio, jis grąžina `403` su `error=access_denied`, užuot teigęs, kad nepatvirtintas el. paštas yra patikimas. Netinkami, nebegaliojantys, atšaukti arba netinkamos auditorijos prieigos raktai grąžina `401`. Žmogaus sesijos prieigos raktai ir organizacijos API raktai negali iškviesti userinfo. ID prieigos raktas neišduodamas. ## Galimos prieigos sritys | Grupė | Prieigos sritys | | --- | --- | | Agentai ir agentų importavimas | `agents:read`, `agents:write` | | Skambučiai | `calls:read`, `calls:write` | | Telefono numeriai ir VoIP | `numbers:read`, `numbers:write` | | Žinios | `knowledge:read`, `knowledge:write` | | Kampanijos | `campaigns:read`, `campaigns:write` | | Integracijos, webhook galiniai taškai, MCP serveriai | `integrations:read`, `integrations:write` | | Balsai | `voices:read` | | Testavimo scenarijai, testų vykdymai, tikrinimas | `testing:read`, `testing:write` | | Atsiskaitymas | `billing:read` | | Paskyros tapatybė ir patvirtintas el. paštas | `openid`, `email` (abu būtini naudotojo informacijai) | | Nuolatinis ryšys | `offline_access` (visada įtraukta) | GET, HEAD ir OPTIONS naudoja skaitymo prieigos sritis; kiti metodai naudoja rašymo prieigos sritis. Balso ir atsiskaitymo pakeitimai per OAuth nepasiekiami; `POST /v1/voices/preview` naudoja `voices:read`, nes peržiūri balsą nekeisdamas jo konfigūracijos. MCP įrankiai taiko pagrindinės REST operacijos prieigos sritį. Perkėlimai tarp organizacijų atmetami net tada, kai autorizuojantis naudotojas priklauso abiem organizacijoms. Kitos API grupės, įskaitant API raktų valdymą ir žmogaus paskyros nustatymus, per OAuth nepasiekiamos. Jei REST operacijai trūksta leidimo, grąžinamas `403` su `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. Netinkami arba pasibaigusio galiojimo prieigos raktai grąžina `401`. ### MCP įrankių autentifikavimo signalai Kiekvienas `tools/list` įrankis apima `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]`, su to įrankio REST operacijos prieigos sritimi. Viešieji dokumentacijos įrankiai naudoja tuščią prieigos sričių sąrašą ir vis tiek reikalauja autentifikuoto ryšio. Jei galiojančiam prieigos raktui trūksta įrankio prieigos srities, grąžinamas HTTP `200` su JSON-RPC `result`, kuriame yra `isError: true`, paaiškinamasis tekstas lauke `content` ir `_meta["mcp/www_authenticate"]`. Pastarasis yra masyvas, kuriame yra Bearer užklausa su `resource_metadata`, `error="insufficient_scope"`, `error_description` ir būtina `scope`. Įrankis nevykdomas. Naudokite šią užklausą išplėstam sutikimui gauti. Jei autentifikavimas trūksta arba yra netinkamas, toliau grąžinamas HTTP `401` su `WWW-Authenticate`; REST prieigos sričių klaidų atveju toliau grąžinamas HTTP `403`. ## Prisijungimo duomenų saugojimas API kas valandą testavimo ir gamybinėje aplinkoje vykdo `python manage.py oauth_cleanup`. Ji pašalina pasibaigusio galiojimo autorizavimo užklausas ir įrenginių kodus. Pasibaigusio galiojimo prieigos raktai, autorizavimo kodai ir atnaujinimo raktų maišos pašalinami tik po to, kai jų prieigos suteikimas atšaukiamas arba visa šeima nebegalioja. Panaudotos maišos saugomos tol, kol šeima turi tinkamą naudoti atnaujinimo raktą, autorizavimo kodą, patvirtintą įrenginio kodą arba prieigos raktą, todėl valymas negali išjungti pakartotinio panaudojimo aptikimo.