Ühenda OAuthiga

Volita MCP-kliente ja ThunderPhone

OAuth võimaldab rakendusel luua ühenduse ühe ThunderPhone’i organisatsiooniga sinu heakskiidetud õigustega. Kataloogikliendid peaksid vaikimisi kasutama OAuthi. Organisatsiooni API võtmed on endiselt saadaval klientidele, mis vajavad käsitsi seadistatud Bearer-tokenit.

Kinnita ühendus#

Alusta ühendust oma MCP-kliendis. Logi ThunderPhone’i sisse, kontrolli rakenduse nime ja taotletud õigusi, vali organisatsioon ning vali Kinnita. Vali Keela, kui sa ei algatanud ühendust või ei usalda rakendust. Rakenduste nimed määravad nende arendajad ning need ei ole kinnitusmärgis.

Lugemisõigused võimaldavad juurdepääsu nimetatud andmetele, sealhulgas salvestistele ja transkriptsioonidele, kui taotletakse õigust calls:read. Kirjutamisõigused võivad ressursse muuta või kustutada; kõned, kampaaniad, telefoninumbrite ostud ja juurutused võivad tekitada kulusid või mõjutada tootmiskeskkonda. Sinu organisatsiooni roll kehtib endiselt.

CLI-ühenduse jaoks ava terminalis kuvatav kinnitamislink, võrdle kaheksakohalist koodi, vali oma organisatsioon ja kinnita. Ainult lingi avamine ei anna juurdepääsu. Koodid aeguvad 15 minuti pärast.

Katkesta rakenduse ühendus#

Ava juhtpaneelil Organisatsioon → API võtmed → Volitatud rakendused ja vali Tühista. See tühistab sinu valitud volituse praeguse organisatsiooni jaoks, sealhulgas selle juurdepääsu- ja värskendustokenid. Kui soovid rakendust uuesti volitada, loo ühendus rakendusest uuesti.

MCP-klientide tuvastamine#

Kasuta serveri URL-i https://api.thunderphone.com/v1/mcp. Kehtiva autentimiseta päring saab vastuseks 401 koos:

WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource"

Hangi see dokument ja seejärel autoriseerimisserveri metaandmed aadressilt https://api.thunderphone.com/.well-known/oauth-authorization-server. Ressursi metaandmed on saadaval ka aadressil /.well-known/oauth-protected-resource/v1/mcp. Kasuta tagastatud lõpp-punkte nende käsitsi koostamise asemel. Ressursi identifikaator on https://api.thunderphone.com/v1/mcp.

Server toetab autoriseerimiskoodi voogu koos S256 PKCE-ga, roteeruvaid värskendustokeneid, avalikku dünaamilist kliendi registreerimist, tühistamist ja seadme autoriseerimise voogu. Kliendisaladusi ega kaudseid vooge ei ole. OpenID tuvastamine on samuti saadaval aadressil /.well-known/openid-configuration; see sisaldab samu autoriseerimisserveri välju ning subject_types_supported: ["public"] ja userinfo lõpp-punkti. ID-tokenid ja kliendi ID metaandmedokumendid (CIMD) ei ole toetatud.

Registreeri avalik klient#

Saada JSON päringule POST /v1/oauth/register:

{
  "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"]
}

Salvesta tagastatud client_id. Ümbersuunamised peavad kasutama HTTPS-i või HTTP-d aadressil 127.0.0.1 või localhost. Registreeri täpne tagasihelistamise URI koos pordi ja teega. Fragmente ja manustatud mandaate ei aktsepteerita. Valikulised client_uri ja logo_uri peavad kasutama HTTPS-i; ThunderPhone ei hangi neid registreerimise ajal. Registreerimisel on kiirusepiirang. Registreeritud kliendid ei aegu ning jäävad registreerituks ka ühenduse tühistamisel. HTTPS-i tagasihelistamiste hulka kuuluvad https://chatgpt.com/connector/oauth/<id> ja https://chatgpt.com/connector_platform_oauth_redirect. Iga ühendus võib registreerida oma kliendi.

Autoriseerimiskood#

Ava tuvastatud autoriseerimise lõpp-punkt parameetritega client_id, täpselt registreeritud redirect_uri, response_type=code, juhuslik state, scope, code_challenge, code_challenge_method=S256 ja resource=https://api.thunderphone.com/v1/mcp. Arvuta prooviväärtus värske suure entroopiaga PKCE kontrollväärtuse polsterdamata base64url-vormingus SHA-256 räsi põhjal. Kontrolli tagastatud state ja iss enne koodi vahetamist. Iga autoriseerimisvastus, sealhulgas keeldumine ja protokollivead, tuvastab väljaandja väljal iss, mis vastab täpselt tuvastatud issuer väärtusele. Kehtetu kliendi või tagasihelistamise vead tagastatakse kohalikult, ilma sellele tagasihelistamise aadressile ümber suunamata.

Vaheta kood päringuga POST /v1/oauth/token, kasutades vormingut form encoding (aktsepteeritakse ka JSON-i):

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

Valikuline parameeter resource on aktsepteeritud nii autoriseerimis- kui ka tokenipäringutes, sealhulgas värskendamise ja seadmevahetuse korral. Kui see on välja jäetud, kasutatakse vaikimisi tuvastatud MCP ressurssi. Kui see on olemas, peab see vastama sellele ressursile täpselt; muud väärtused tagastavad invalid_target. Juurdepääsutokenid sisaldavad seda sihtrühma ning MCP lükkab puuduva või erineva sihtrühmaga tokenid tagasi vastusega 401 ja tuvastamiskutsega.

Autoriseerimispäringud ja koodid aeguvad 10 minuti pärast. Iga tokenivastus sisaldab access_token, token_type (Bearer), expires_in (vaikimisi 3600 sekundit), refresh_token, scope, organization_id ja organization_name. Saada juurdepääsutokenid ainult päise Authorization: Bearer kaudu. Ära kunagi lisa tokeneid URL-idesse, logidesse, lähtekoodi versioonihaldusse ega vestlustesse.

Värskenda ja tühista#

Värskenda tokeni lõpp-punktis parameetritega grant_type=refresh_token, client_id, refresh_token ja resource. Salvesta uus värskendustoken atomaarse toiminguna ning lõpeta vana kasutamine. Värskendustokenid aeguvad pärast 30 päeva ilma eduka värskendamiseta. Valikuline scope võib antud õigusi kitsendada. offline_access on alati kaasatud ja värskendustokenid väljastatakse alati. Esialgne päring ilma scope-ita annab ainult offline_access, seega peaksid kliendid taotlema vajalikke õigusi.

Koodi taaskasutamine ja roteeritud värskendustokeni taaskasutamine tühistavad kogu autoriseerimise. Serialiseeri värskendamised kliendi sees; edukalt vahetatud mandaadi uuesti esitamine ei ole turvaline uuestiproovimise strateegia.

Ühenduse katkestamiseks saada token ja client_id päringule POST /v1/oauth/revoke. Kummagi tokeni tühistamine tühistab selle autoriseerimise, sealhulgas kõik sellest väljastatud tokenid. Tundmatu token tagastab edu, avaldamata, kas see eksisteerib. Töölaua seansid saavad loetleda oma autoriseerimisi päringuga GET /v1/oauth/grants ja tühistada ühe päringuga DELETE /v1/oauth/grants/<id>, kus X-ThunderPhone-Org valib organisatsiooni.

Seadme autoriseerimine#

Seadme autoriseerimine on piiratud eelregistreeritud klientidega; dünaamiliselt registreeritud kliendid saavad vastuseks unauthorized_client. Eelregistreeritud avalik klient thunderphone-cli toetab seadme autoriseerimist ja värskendamist. Saada client_id=thunderphone-cli ja scope päringule POST /v1/oauth/device/code. Kuvage kasutajale user_code ja verification_uri või ava verification_uri_complete.

Küsitle tokeni lõpp-punkti parameetritega grant_type=urn:ietf:params:oauth:grant-type:device_code, client_id ja device_code, oodates vähemalt tagastatud interval väärtuse (5 sekundit). Jätka väärtuse authorization_pending korral. Väärtuse slow_down korral kasuta iga järgmise päringu jaoks vastuses tagastatud uut interval väärtust, mida suurendatakse 5 sekundi võrra. Peatu väärtuste access_denied, expired_token või mis tahes muu vea korral. Ära kunagi kinnita seadmekoodi automaatselt.

Eelregistreeritud klient thunderphone-mcp aktsepteerib aadresse http://127.0.0.1/callback ja http://localhost/callback mis tahes pordil. Skeem, host, tee ja päring peavad vastama; tokenivahetus peab kasutama autoriseerimisest saadud täpset ümbersuunamise URI-d, sealhulgas porti. Dünaamiliselt registreeritud kliendid nõuavad ümbersuunamise URI täpset vastavust, sealhulgas porti. Registreeri dünaamiliselt teine tagasihelistamine, kui vajad muud teed.

Konto identiteedi ja tööruumi domeeni kontrollid#

Taotle nii openid email kui ka toimingu ulatusi, mida sinu klient vajab. Kutsu tuvastatud userinfo_endpoint (GET /v1/oauth/userinfo) juurdepääsutokeniga Bearer-päises. Edukas vastus sisaldab:

{
  "sub": "123",
  "email": "person@example.com",
  "email_verified": true,
  "name": "Example User",
  "org_id": 456
}

sub on stabiilne kasutajaidentifikaator; org_id on nõusoleku ajal valitud organisatsioon. Lõpp-punkt nõuab mõlemat identiteedi ulatust ja tagastab 403, kui kumbki puudub. Kui kontol puudub kinnitatud e-posti profiil, tagastab see 403 koos väärtusega error=access_denied, selle asemel et väita, et kinnitamata e-post on usaldusväärne. Kehtetud, aegunud, tühistatud või vale sihtrühmaga tokenid tagastavad 401. Inimseansi tokenid ja organisatsiooni API-võtmed ei saa userinfo lõpp-punkti kutsuda. ID-tokenit ei väljastata.

Saadaolevad õigused#

GET, HEAD ja OPTIONS kasutavad lugemisõigusi; muud meetodid kasutavad kirjutamisõigusi. Häälte ja arveldamise muutmistoimingud pole OAuthi kaudu saadaval; POST /v1/voices/preview kasutab õigust voices:read, sest see eelvaatab häält selle konfiguratsiooni muutmata. MCP-tööriistad jõustavad nende aluseks oleva REST-toimingu õigust. Organisatsioonidevahelised ülekanded keelatakse isegi siis, kui volitav kasutaja kuulub mõlemasse organisatsiooni. Muud API-rühmad, sealhulgas API-võtmete haldus ja kasutajakonto seaded, pole OAuthi kaudu saadaval. Puuduv õigus REST-toimingu jaoks tagastab 403 koos väärtusega WWW-Authenticate: Bearer error="insufficient_scope", scope="...". Kehtetud või aegunud juurdepääsuload tagastavad 401.

MCP-tööriistade autentimissignaalid#

Iga tööriist asukohas tools/list sisaldab väärtust securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}] koos selle tööriista REST-toimingu õigusega. Avalikud dokumentatsioonitööriistad kasutavad tühja õiguste loendit ja nõuavad siiski autentitud ühendust.

Kehtiv luba, millel puudub tööriista õigus, saab HTTP 200 koos JSON-RPC result-iga, mis sisaldab väärtust isError: true, selgitavat teksti väljal content ning _meta["mcp/www_authenticate"]. Viimane on massiiv, mis sisaldab Beareri väljakutset väärtustega resource_metadata, error="insufficient_scope", error_description ja nõutud scope. Tööriista ei käivitata. Kasuta seda väljakutset laiendatud nõusoleku taotlemiseks. Puuduv või kehtetu autentimine tagastab jätkuvalt HTTP 401 koos WWW-Authenticate-iga; RESTi õiguste tõrked tagastavad jätkuvalt HTTP 403.

Mandaatide säilitamine#

API käivitab python manage.py oauth_cleanup iga tunni järel eeltootmises ja tootmises. See eemaldab aegunud autoriseerimistaotlused ja seadmekoodid. Aegunud juurdepääsulube, autoriseerimiskoode ja värskendusloa räsi eemaldatakse alles pärast nende volituse tühistamist või kogu perekonna kehtetuks muutumist. Kasutatud räsid säilitatakse seni, kuni perekonnal on kasutatav värskendusluba, autoriseerimiskood, heakskiidetud seadmekood või juurdepääsuluba, et puhastamine ei saaks korduskasutuse tuvastamist keelata.