Unganisha kwa OAuth

Idhinisha wateja wa MCP na CLI ya ThunderPhone bila kushiriki ufunguo wa API.

OAuth huruhusu programu kuunganishwa na shirika moja la ThunderPhone kwa ruhusa unazoidhinisha. Wateja wa saraka wanapaswa kutumia OAuth kwa chaguomsingi. Funguo za API za shirika zinaendelea kupatikana kwa wateja wanaohitaji tokeni ya Bearer iliyosanidiwa mwenyewe.

Idhinisha muunganisho#

Anzisha muunganisho katika mteja wako wa MCP. Ingia kwenye ThunderPhone, angalia jina la programu na ruhusa zilizoombwa, chagua shirika, kisha uchague Idhinisha. Chagua Kataa ikiwa hukuanzisha muunganisho au huiamini programu. Majina ya programu hutolewa na wasanidi wake na si uthibitisho wa uaminifu.

Ruhusa za kusoma hutoa ufikiaji wa data iliyotajwa, ikijumuisha rekodi na nakala za mazungumzo wakati calls:read inapoombwa. Ruhusa za kuandika zinaweza kubadilisha au kufuta rasilimali; simu, kampeni, ununuzi wa namba za simu, na utumaji zinaweza kusababisha gharama au kuathiri mazingira ya uzalishaji. Jukumu lako katika shirika bado linatumika.

Kwa muunganisho wa CLI, fungua kiungo cha uthibitishaji kinachoonyeshwa kwenye terminal yako, linganisha msimbo wa herufi nane, chagua shirika lako, kisha idhinisha. Kufungua kiungo pekee hakutoi ufikiaji. Misimbo inaisha muda baada ya dakika 15.

Ondoa muunganisho wa programu#

Fungua Shirika → Funguo za API → Programu zilizoidhinishwa katika dashibodi na uchague Batilisha. Hii inabatilisha idhini uliyochagua kwa shirika la sasa, ikijumuisha tokeni zake za ufikiaji na za kuhuisha. Unganisha tena kutoka kwenye programu ikiwa unataka kuiidhinisha tena.

Ugunduzi kwa wateja wa MCP#

Tumia URL ya seva https://api.thunderphone.com/v1/mcp. Ombi lisilo na uthibitishaji halali hupokea 401 yenye:

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

Chukua hati hiyo, kisha chukua metadata ya seva ya uidhinishaji kwenye https://api.thunderphone.com/.well-known/oauth-authorization-server. Metadata ya rasilimali pia inapatikana kwenye /.well-known/oauth-protected-resource/v1/mcp. Tumia vituo vilivyorejeshwa badala ya kuviunda. Kitambulisho cha rasilimali ni https://api.thunderphone.com/v1/mcp.

Seva inasaidia msimbo wa uidhinishaji wenye S256 PKCE, tokeni za uonyeshaji upya zinazozungushwa, usajili wa umma unaobadilika wa mteja, ubatilishaji, na ruzuku ya uidhinishaji wa kifaa. Hakuna siri za mteja au ruzuku dhahania. Ugunduzi wa OpenID pia unapatikana kwenye /.well-known/openid-configuration; unajumuisha sehemu zilezile za seva ya uidhinishaji pamoja na subject_types_supported: ["public"] na kituo cha userinfo. Tokeni za ID na Nyaraka za Metadata za Kitambulisho cha Mteja (CIMD) hazisaidiki.

Sajili mteja wa umma#

Tuma JSON kwa 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"]
}

Hifadhi client_id iliyorejeshwa. Uelekezaji upya lazima utumie HTTPS, au HTTP kwenye 127.0.0.1 au localhost. Sajili URI sahihi ya mwito-rejea, ikijumuisha mlango na njia yake. Vipande na vitambulisho vilivyopachikwa vinakataliwa. client_uri na logo_uri za hiari lazima zitumie HTTPS; ThunderPhone haichukui hizo wakati wa usajili. Usajili una kikomo cha kiwango cha maombi. Wateja waliosajiliwa hawaishi muda wake na husalia wamesajiliwa muunganisho unapobatilishwa. Mito-rejea ya HTTPS inajumuisha https://chatgpt.com/connector/oauth/<id> na https://chatgpt.com/connector_platform_oauth_redirect. Kila muunganisho unaweza kusajili mteja wake mwenyewe.

Msimbo wa uidhinishaji#

Fungua kituo cha uidhinishaji kilichogunduliwa kwa client_id, redirect_uri sahihi iliyosajiliwa, response_type=code, state ya nasibu, scope, code_challenge, code_challenge_method=S256, na resource=https://api.thunderphone.com/v1/mcp. Hesabu changamoto kama muhtasari wa SHA-256 wa base64url usiojazwa wa kithibitishaji kipya cha PKCE chenye entropia ya juu. Thibitisha state na iss zilizorejeshwa kabla ya kubadilisha msimbo. Kila jibu la uidhinishaji, ikijumuisha kunyimwa na hitilafu za itifaki, humtambua mtoaji kwa iss, inayolingana kabisa na issuer iliyogunduliwa. Hitilafu za mteja au mwito-rejea usio halali hurejeshwa moja kwa moja bila kuelekeza upya kwenye mwito-rejea huo.

Badilisha kwenye POST /v1/oauth/token ukitumia usimbaji wa fomu (JSON pia inakubaliwa):

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

Kigezo cha hiari cha resource kinakubaliwa kwenye maombi yote ya uidhinishaji na tokeni (ikijumuisha ubadilishanaji wa uonyeshaji upya na kifaa). Kisipotolewa, hutumia rasilimali ya MCP iliyogunduliwa kama chaguo-msingi. Kikikuwepo, lazima kilingane kabisa na rasilimali hiyo; thamani nyingine hurejesha invalid_target. Tokeni za ufikiaji hubeba walengwa hao, na MCP hukataa tokeni zisizo na walengwa au zenye walengwa tofauti kwa 401 na changamoto ya ugunduzi.

Maombi ya uidhinishaji na misimbo huisha baada ya dakika 10. Kila jibu la tokeni lina access_token, token_type (Bearer), expires_in (sekunde 3600 kwa chaguo-msingi), refresh_token, scope, organization_id, na organization_name. Tuma tokeni za ufikiaji kupitia kichwa cha Authorization: Bearer pekee. Usiweke tokeni kamwe kwenye URL, kumbukumbu, udhibiti wa toleo la chanzo, au mazungumzo.

Onyesha upya na batilisha#

Onyesha upya kwa grant_type=refresh_token, client_id, refresh_token, na resource kwenye kituo cha tokeni. Hifadhi tokeni mpya ya uonyeshaji upya kwa utaratibu wa atomiki na acha kutumia ya zamani. Tokeni za uonyeshaji upya huisha baada ya siku 30 bila uonyeshaji upya uliofanikiwa. scope ya hiari inaweza kupunguza ruhusa zilizotolewa. offline_access hujumuishwa kila wakati na tokeni za uonyeshaji upya hutolewa kila wakati. Ombi la awali lisilo na scope hutoa offline_access pekee, kwa hivyo wateja wanapaswa kuomba ruhusa wanazohitaji.

Kutumia tena msimbo na kutumia tena tokeni ya uonyeshaji upya iliyozungushwa hubatilisha uidhinishaji wote. Tekeleza uonyeshaji upya mmoja baada ya mwingine ndani ya mteja; kurudia kutuma kitambulisho kilichobadilishwa kwa mafanikio si mkakati salama wa kujaribu tena.

Ili kukata muunganisho, tuma token na client_id kwa POST /v1/oauth/revoke. Kubatilisha tokeni yoyote hubatilisha uidhinishaji wake, ikijumuisha tokeni zote zilizotolewa kutokana nayo. Tokeni isiyojulikana hurejesha mafanikio bila kufichua kama ipo. Vipindi vya dashibodi vinaweza kuorodhesha uidhinishaji wake kwenye GET /v1/oauth/grants na kubatilisha mmoja kwenye DELETE /v1/oauth/grants/<id>, huku X-ThunderPhone-Org ikichagua shirika.

Uidhinishaji wa kifaa#

Uidhinishaji wa kifaa unaruhusiwa kwa wateja waliosajiliwa mapema pekee; wateja waliosajiliwa kwa njia inayobadilika hupokea unauthorized_client. Mteja wa umma aliyesajiliwa mapema thunderphone-cli anasaidia uidhinishaji wa kifaa na uonyeshaji upya. Tuma client_id=thunderphone-cli na scope kwa POST /v1/oauth/device/code. Mwonyeshe mtumiaji user_code na verification_uri, au fungua verification_uri_complete.

Hoji kituo cha tokeni mara kwa mara kwa grant_type=urn:ietf:params:oauth:grant-type:device_code, client_id, na device_code, ukisubiri angalau interval iliyorejeshwa (sekunde 5). Endelea unapopokea authorization_pending. Kwenye slow_down, tumia interval mpya iliyorejeshwa kwenye jibu (iliyoongezwa kwa sekunde 5) kwa kila ombi linalofuata. Simama kwenye access_denied, expired_token, au hitilafu nyingine yoyote. Usiidhinishe kamwe msimbo wa kifaa kiotomatiki.

Mteja aliyesajiliwa mapema thunderphone-mcp anakubali http://127.0.0.1/callback na http://localhost/callback kwenye mlango wowote. Itifaki, seva pangishi, njia na kigezo cha utafutaji lazima vilingane; ubadilishanaji wa tokeni lazima utumie URI sahihi ya uelekezaji upya (ikijumuisha mlango) kutoka kwenye uidhinishaji. Wateja waliosajiliwa kwa njia inayobadilika wanahitaji ulinganishaji sahihi wa URI ya uelekezaji upya, ikijumuisha mlango. Sajili mwito-rejea tofauti kwa njia inayobadilika ikiwa unahitaji njia nyingine.

Utambulisho wa akaunti na ukaguzi wa kikoa cha nafasi ya kazi#

Omba openid email pamoja na vigo vya ruhusa za operesheni ambavyo mteja wako anahitaji. Piga userinfo_endpoint iliyogunduliwa (GET /v1/oauth/userinfo) kwa tokeni ya ufikiaji kwenye kichwa cha Bearer. Jibu lililofanikiwa lina:

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

sub ni kitambulisho thabiti cha mtumiaji; org_id ni shirika lililochaguliwa wakati wa idhini. Kituo hiki kinahitaji vigo vyote viwili vya utambulisho na hurejesha 403 iwapo kimoja kinakosekana. Hurejesha 403 yenye error=access_denied ikiwa akaunti haina wasifu wa barua pepe uliothibitishwa, badala ya kudai kuwa barua pepe isiyothibitishwa inaaminika. Tokeni zisizo halali, zilizoisha muda wake, zilizobatilishwa, au zenye walengwa wasio sahihi hurejesha 401. Tokeni za vipindi vya watumiaji na funguo za API za shirika haziwezi kupiga userinfo. Hakuna tokeni ya ID inayotolewa.

Ruhusa zinazopatikana#

GET, HEAD na OPTIONS hutumia scope za kusoma; mbinu nyingine hutumia scope za kuandika. Mabadiliko ya sauti na malipo hayapatikani kupitia OAuth; POST /v1/voices/preview hutumia voices:read kwa sababu huhakiki sauti bila kubadilisha usanidi wake. Zana za MCP zinatekeleza scope ya operesheni yao ya msingi ya REST. Uhamishaji kati ya mashirika hukataliwa hata wakati mtumiaji anayeidhinisha ni mwanachama wa mashirika yote mawili. Familia nyingine za API, ikiwemo usimamizi wa API key na mipangilio ya akaunti za watumiaji, hazipatikani kupitia OAuth. Ruhusa inayokosekana kwenye operesheni ya REST hurejesha 403 pamoja na WWW-Authenticate: Bearer error="insufficient_scope", scope="...". Tokeni za ufikiaji zisizo halali au zilizoisha muda wake hurejesha 401.

Ishara za uthibitishaji wa zana za MCP#

Kila zana katika tools/list inajumuisha securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}], pamoja na scope ya operesheni ya REST ya zana hiyo. Zana za nyaraka za umma hutumia orodha tupu ya scope na bado zinahitaji muunganisho uliothibitishwa.

Tokeni halali inayokosa scope ya zana hupokea HTTP 200 pamoja na result ya JSON-RPC iliyo na isError: true, maelezo katika content, na _meta["mcp/www_authenticate"]. Kipengele cha mwisho ni mkusanyiko unaojumuisha changamoto ya Bearer yenye resource_metadata, error="insufficient_scope", error_description, na scope inayohitajika. Zana haitekelezwi. Tumia changamoto hii kuomba idhini iliyopanuliwa. Uthibitishaji unaokosekana au usio halali unaendelea kurejesha HTTP 401 pamoja na WWW-Authenticate; hitilafu za scope za REST zinaendelea kurejesha HTTP 403.

Uhifadhi wa vitambulisho#

API huendesha python manage.py oauth_cleanup kila saa katika staging na production. Huondoa maombi ya uidhinishaji na misimbo ya kifaa iliyoisha muda wake. Tokeni za ufikiaji zilizoisha muda wake, misimbo ya uidhinishaji na hash za refresh token hupunguzwa tu baada ya idhini yake kufutwa au familia nzima kutotumika tena. Hash zilizotumika huhifadhiwa wakati familia ina refresh token, msimbo wa uidhinishaji, msimbo wa kifaa ulioidhinishwa au tokeni ya ufikiaji inayoweza kutumika, hivyo usafishaji hauwezi kuzima utambuzi wa matumizi ya kurudia.