Prisijungimas naudojant OAuth

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:

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:

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

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

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/<id>, 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:

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

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.