Savienojiet ar OAuth

Autorizējiet MCP klientus un ThunderPhone CLI, nekopīgojot API atslēgu.

OAuth ļauj lietotnei izveidot savienojumu ar vienu ThunderPhone organizāciju, izmantojot jūsu apstiprinātās atļaujas. Direktoriju klientiem pēc noklusējuma jāizmanto OAuth. Organizācijas API atslēgas joprojām ir pieejamas klientiem, kuriem nepieciešams manuāli konfigurēts Bearer marķieris.

Apstipriniet savienojumu#

Sāciet savienojumu savā MCP klientā. Pierakstieties ThunderPhone, pārbaudiet lietotnes nosaukumu un pieprasītās atļaujas, izvēlieties organizāciju un atlasiet Apstiprināt. Atlasiet Noraidīt, ja savienojumu neuzsācāt jūs vai neuzticaties lietotnei. Lietotņu nosaukumus norāda to izstrādātāji, un tie nav verifikācijas apliecinājums.

Lasīšanas atļaujas nodrošina piekļuvi norādītajiem datiem, tostarp ierakstiem un transkripcijām, ja tiek pieprasīta calls:read atļauja. Rakstīšanas atļaujas var mainīt vai dzēst resursus; zvani, kampaņas, tālruņa numuru iegādes un izvietošanas var radīt izmaksas vai ietekmēt produkcijas vidi. Jūsu organizācijas loma joprojām tiek piemērota.

CLI savienojumam atveriet terminālī parādīto verifikācijas saiti, salīdziniet astoņu rakstzīmju kodu, atlasiet savu organizāciju un apstipriniet. Tikai saites atvēršana nepiešķir piekļuvi. Kodu derīguma termiņš beidzas pēc 15 minūtēm.

Atvienojiet lietotni#

Informācijas panelī atveriet Organizācija → API atslēgas → Autorizētās lietotnes un izvēlieties Atsaukt. Tādējādi tiek atsaukta jūsu atlasītā autorizācija pašreizējai organizācijai, tostarp tās piekļuves un atsvaidzināšanas marķieri. Ja vēlaties lietotni autorizēt vēlreiz, atkārtoti izveidojiet savienojumu no lietotnes.

MCP klientu atklāšana#

Izmantojiet servera URL https://api.thunderphone.com/v1/mcp. Pieprasījums bez derīgas autentifikācijas saņem 401 ar:

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

Iegūstiet šo dokumentu, pēc tam iegūstiet autorizācijas servera metadatus vietnē https://api.thunderphone.com/.well-known/oauth-authorization-server. Resursa metadati ir pieejami arī vietnē /.well-known/oauth-protected-resource/v1/mcp. Izmantojiet atgrieztos galapunktus, nevis veidojiet tos manuāli. Resursa identifikators ir https://api.thunderphone.com/v1/mcp.

Serveris atbalsta autorizācijas kodu ar S256 PKCE, rotējošus atsvaidzināšanas marķierus, publisku dinamisku klientu reģistrāciju, atsaukšanu un ierīces autorizācijas piešķīrumu. Klientu noslēpumu vai netiešo piešķīrumu nav. OpenID atklāšana ir pieejama arī vietnē /.well-known/openid-configuration; tā ietver tos pašus autorizācijas servera laukus, kā arī subject_types_supported: ["public"] un lietotāja informācijas galapunktu. ID marķieri un klienta ID metadatu dokumenti (CIMD) netiek atbalstīti.

Reģistrējiet publisku klientu#

Nosūtiet JSON uz 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"]
}

Saglabājiet atgriezto client_id. Novirzīšanai jāizmanto HTTPS vai HTTP adresē 127.0.0.1 vai localhost. Reģistrējiet precīzu atzvanīšanas URI, ieskaitot tā portu un ceļu. Fragmenti un iegultas akreditācijas dati tiek noraidīti. Neobligātajiem client_uri un logo_uri jāizmanto HTTPS; ThunderPhone tos reģistrācijas laikā neiegūst. Reģistrācijai ir biežuma ierobežojums. Reģistrētajiem klientiem nav derīguma termiņa, un tie paliek reģistrēti, kad savienojums tiek atsaukts. HTTPS atzvanīšanas adreses ietver https://chatgpt.com/connector/oauth/<id> un https://chatgpt.com/connector_platform_oauth_redirect. Katrs savienojums var reģistrēt savu klientu.

Autorizācijas kods#

Atveriet atklāto autorizācijas galapunktu ar client_id, precīzu reģistrēto redirect_uri, response_type=code, nejaušu state, scope, code_challenge, code_challenge_method=S256 un resource=https://api.thunderphone.com/v1/mcp. Aprēķiniet pārbaudes vērtību kā jauna augstas entropijas PKCE verificētāja SHA-256 jaucējvērtību base64url formātā bez polsterējuma. Pirms koda apmaiņas pārbaudiet atgrieztos state un iss. Katra autorizācijas atbilde, tostarp atteikumi un protokola kļūdas, identificē izdevēju ar iss, kas precīzi atbilst atklātajam issuer. Kļūdas nederīgam klientam vai atzvanīšanai tiek atgrieztas lokāli, nenovirzot uz šo atzvanīšanu.

Veiciet apmaiņu vietnē POST /v1/oauth/token, izmantojot formas kodējumu (tiek pieņemts arī 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

Neobligātais parametrs resource tiek pieņemts gan autorizācijas, gan marķieru pieprasījumos, tostarp atsvaidzināšanas un ierīces apmaiņās. Ja tas nav norādīts, pēc noklusējuma tiek izmantots atklātais MCP resurss. Ja tas ir norādīts, tam precīzi jāatbilst šim resursam; citas vērtības atgriež invalid_target. Piekļuves marķieros ir šī auditorija, un MCP noraida marķierus ar trūkstošu vai atšķirīgu auditoriju, atgriežot 401 un atklāšanas pārbaudi.

Autorizācijas pieprasījumu un kodu derīguma termiņš beidzas pēc 10 minūtēm. Katrā marķiera atbildē ir access_token, token_type (Bearer), expires_in (pēc noklusējuma 3600 sekundes), refresh_token, scope, organization_id un organization_name. Sūtiet piekļuves marķierus tikai ar galveni Authorization: Bearer. Nekad neievietojiet marķierus URL adresēs, žurnālos, pirmkoda versiju pārvaldībā vai tērzēšanā.

Atsvaidziniet un atsauciet#

Atsvaidziniet ar grant_type=refresh_token, client_id, refresh_token un resource marķieru galapunktā. Saglabājiet jauno atsvaidzināšanas marķieri atomāri un pārtrauciet izmantot veco. Atsvaidzināšanas marķieru derīguma termiņš beidzas pēc 30 dienām bez veiksmīgas atsvaidzināšanas. Neobligāts scope var sašaurināt piešķirtās atļaujas. offline_access vienmēr tiek iekļauts, un atsvaidzināšanas marķieri vienmēr tiek izsniegti. Sākotnējais pieprasījums bez scope piešķir tikai offline_access, tāpēc klientiem jāpieprasa nepieciešamās atļaujas.

Koda atkārtota izmantošana un rotēta atsvaidzināšanas marķiera atkārtota izmantošana atsauc visu autorizāciju. Serializējiet atsvaidzināšanu viena klienta ietvaros; veiksmīgi apmainītu akreditācijas datu atkārtota izmantošana nav droša atkārtošanas stratēģija.

Lai atvienotos, nosūtiet token un client_id uz POST /v1/oauth/revoke. Jebkura marķiera atsaukšana atsauc tā autorizāciju, tostarp visus no tā izsniegtos marķierus. Nezināms marķieris atgriež veiksmīgu rezultātu, neatklājot, vai tas pastāv. Informācijas paneļa sesijas var uzskaitīt savas autorizācijas vietnē GET /v1/oauth/grants un atsaukt vienu vietnē DELETE /v1/oauth/grants/<id>, kur X-ThunderPhone-Org atlasa organizāciju.

Ierīces autorizācija#

Ierīces autorizācija ir ierobežota ar iepriekš reģistrētiem klientiem; dinamiski reģistrēti klienti saņem unauthorized_client. Iepriekš reģistrētais publiskais klients thunderphone-cli atbalsta ierīces autorizāciju un atsvaidzināšanu. Nosūtiet client_id=thunderphone-cli un scope uz POST /v1/oauth/device/code. Parādiet lietotājam user_code un verification_uri vai atveriet verification_uri_complete.

Aptaujājiet marķieru galapunktu ar grant_type=urn:ietf:params:oauth:grant-type:device_code, client_id un device_code, gaidot vismaz atgriezto interval (5 sekundes). Turpiniet, saņemot authorization_pending. Saņemot slow_down, katram turpmākajam pieprasījumam izmantojiet atbildē atgriezto jauno interval (palielinātu par 5 sekundēm). Apturiet darbību, saņemot access_denied, expired_token vai jebkuru citu kļūdu. Nekad neapstipriniet ierīces kodu automātiski.

Iepriekš reģistrētais klients thunderphone-mcp pieņem http://127.0.0.1/callback un http://localhost/callback jebkurā portā. Shēmai, resursdatoram, ceļam un vaicājumam jāatbilst; marķiera apmaiņā jāizmanto precīzs autorizācijas novirzīšanas URI, tostarp ports. Dinamiski reģistrētiem klientiem ir nepieciešama precīza novirzīšanas URI atbilstība, tostarp ports. Ja nepieciešams cits ceļš, dinamiski reģistrējiet citu atzvanīšanu.

Konta identitātes un darbvietas domēna pārbaudes#

Pieprasiet gan openid email, gan darbības tvērumus, kas nepieciešami jūsu klientam. Izsauciet atklāto userinfo_endpoint (GET /v1/oauth/userinfo) ar piekļuves marķieri Bearer galvenē. Veiksmīgā atbildē ir:

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

sub ir stabils lietotāja identifikators; org_id ir piekrišanas laikā atlasītā organizācija. Galapunktam ir nepieciešami abi identitātes tvērumi, un, ja kāda trūkst, tas atgriež 403. Ja kontam nav verificēta e-pasta profila, tas atgriež 403 ar error=access_denied, nevis apgalvo, ka neverificēts e-pasts ir uzticams. Nederīgi, beigušies, atsaukti vai nepareizai auditorijai paredzēti marķieri atgriež 401. Cilvēku sesiju marķieri un organizācijas API atslēgas nevar izsaukt userinfo. ID marķieris netiek izsniegts.

Pieejamās atļaujas#

GET, HEAD un OPTIONS izmanto lasīšanas tvērumus; citas metodes izmanto rakstīšanas tvērumus. Balss un norēķinu modificēšanas darbības nav pieejamas, izmantojot OAuth; POST /v1/voices/preview izmanto voices:read, jo tas ļauj priekšskatīt balsi, nemainot tās konfigurāciju. MCP rīki ievēro pamatā esošās REST darbības tvērumu. Pārsūtījumi starp organizācijām tiek noraidīti pat tad, ja autorizējošais lietotājs pieder abām organizācijām. Citas API kategorijas, tostarp API atslēgu pārvaldība un cilvēku kontu iestatījumi, nav pieejamas, izmantojot OAuth. Ja REST darbībai trūkst atļaujas, tiek atgriezts 403 ar WWW-Authenticate: Bearer error="insufficient_scope", scope="...". Nederīgi vai beigušies piekļuves marķieri atgriež 401.

MCP rīku autentifikācijas signāli#

Katrs rīks pakotnē tools/list ietver securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}] ar šī rīka REST darbības tvērumu. Publiskie dokumentācijas rīki izmanto tukšu tvērumu sarakstu un joprojām pieprasa autentificētu savienojumu.

Ja derīgam marķierim trūkst rīka tvēruma, tiek saņemta HTTP 200 atbilde ar JSON-RPC result, kas satur isError: true, paskaidrojošu tekstu laukā content un _meta["mcp/www_authenticate"]. Pēdējais ir masīvs ar Bearer autentifikācijas izaicinājumu, kurā ietverti resource_metadata, error="insufficient_scope", error_description un nepieciešamais scope. Rīks netiek izpildīts. Izmantojiet šo izaicinājumu, lai pieprasītu paplašinātu piekrišanu. Ja autentifikācija nav pieejama vai nav derīga, joprojām tiek atgriezts HTTP 401 ar WWW-Authenticate; REST tvēruma kļūmes joprojām atgriež HTTP 403.

Akreditācijas datu glabāšana#

API starpvidē un produkcijas vidē katru stundu izpilda python manage.py oauth_cleanup. Tas noņem autorizācijas pieprasījumus un ierīču kodus, kuriem beidzies derīguma termiņš. Piekļuves marķieri, autorizācijas kodi un atsvaidzināšanas marķieru jaucējvērtības, kuriem beidzies derīguma termiņš, tiek dzēsti tikai pēc tam, kad to piešķīrums ir atsaukts vai visa saime vairs nav aktīva. Izmantotās jaucējvērtības tiek saglabātas, kamēr saimei ir izmantojams atsvaidzināšanas marķieris, autorizācijas kods, apstiprināts ierīces kods vai piekļuves marķieris, lai tīrīšana nevarētu atspējot atkārtotas izmantošanas noteikšanu.