OAuth 2.1 लागू करने के बारे में जानकारी

इस गाइड में बताया गया है कि कनेक्ट किए गए ऐप्लिकेशन के प्लैटफ़ॉर्म को अपनी सेवाओं को ऐक्सेस करने की अनुमति सुरक्षित तरीके से कैसे दी जा सकती है. कनेक्ट किए गए ऐप्लिकेशन के एमसीपी इंटिग्रेशन के लिए, हमारा सुझाव है कि आप OAuth 2.1 का इस्तेमाल करें. यह डेलिगेट की गई अनुमति के लिए इंडस्ट्री स्टैंडर्ड है. साथ ही, Proof Key for Code Exchange (PKCE) का इस्तेमाल करें. इससे उपयोगकर्ता के डेटा की सुरक्षा और "एजेंटिक" फ़्लो में विश्वसनीयता को बेहतर बनाया जा सकता है. कनेक्ट किए गए ऐप्लिकेशन का प्लैटफ़ॉर्म, OAuth के इस्तेमाल की अनुमति का टाइप के साथ काम करता है. इसमें Proof Key for Code Exchange (PKCE) पैरामीटर शामिल होते हैं.

सभी OAuth 2.1 के लिए पीकेसीई ज़रूरी है. हालांकि, OAuth 2.0 के लिए यह ज़रूरी नहीं है.

अपने-आप खोज होने की सुविधा चालू करने और शामिल होने की प्रोसेस को आसान बनाने के लिए, अनुमति देने वाले आपके सर्वर पर अनुमति देने वाले सर्वर के मेटाडेटा एक्सटेंशन की सुविधा काम करनी चाहिए. इसे OAuth डिस्कवरी भी कहा जाता है.

सलाह: उपयोगकर्ता को खराब अनुभव से बचाने और खातों को फिर से लिंक करने की ज़रूरत को खत्म करने के लिए, सबसे ज़रूरी बात यह है कि हमेशा लिंक रहने की सुविधा का इस्तेमाल करके, रीफ़्रेश टोकन की समयसीमा को मैनेज किया जाए.

Gemini MCP, कॉन्फ़िगरेशन JSON को कैसे फ़ेच करता है

Gemini MCP console, यहां दिए गए यूआरएल से आपके कॉन्फ़िगरेशन JSON को फ़ेच करने की कोशिश करता है. इसके लिए, वह इस सेक्शन में दिखाए गए क्रम का इस्तेमाल करता है.

चेतावनी: Gemini MCP console, जवाब देने वाले पहले यूआरएल का इस्तेमाल करता है. इसमें गड़बड़ी वाला यूआरएल भी शामिल है. पक्का करें कि आपके पसंदीदा एंडपॉइंट को ऐक्सेस किया जा सकता हो और वह एचटीटीपी 200 दिखाता हो.

अगर आपके ऑथराइज़ेशन सर्वर का यूआरएल आपके डोमेन के टॉप लेवल पर मौजूद है (उदाहरण के लिए, https://auth.example.com), तो Gemini आपके डोमेन में स्टैंडर्ड "well-known" डायरेक्ट्री जोड़ता है. इसके बाद, वह इस क्रम में सर्वर को खोजता है:

1. https://auth.example.com/.well-known/oauth-authorization-server
2. https://auth.example.com/.well-known/openid-configuration

अगर आपके ऑथराइज़ेशन सर्वर का यूआरएल, आपके डोमेन की किसी सबडायरेक्ट्री या पाथ में मौजूद है, जैसे कि https://auth.example.com/realms/master, तो Gemini उसी "well-known" पाथ को सीधे उस सबडायरेक्ट्री में जोड़ देता है. इसके लिए, वह इस क्रम का इस्तेमाल करता है.

1. .../realms/master/.well-known/oauth-authorization-server
2. .../realms/master/.well-known/openid-configuration
3. .../realms/master/.well-known/openid-configuration (नेस्ट किए गए पाथ के लिए सहायता)

JSON की ज़रूरी सुविधाएं

मेटाडेटा के जवाब में ये फ़ील्ड शामिल होने चाहिए. अगर ज़रूरी फ़ील्ड मौजूद नहीं हैं या मान्य टाइप नहीं मिलते हैं, तो इंटिग्रेशन नहीं हो पाता है.

authorization_endpoint

यह एक मान्य स्ट्रिंग यूआरएल होना चाहिए.

token_endpoint

यह एक मान्य स्ट्रिंग यूआरएल होना चाहिए.

response_types_supported

इसमें code स्ट्रिंग होनी चाहिए.

registration_endpoint

फ़िलहाल, Play Console, डाइनैमिक क्लाइंट पर निर्भर है.

रजिस्ट्रेशन (आरएफ़सी 7591). आपको अपने मेटाडेटा में रजिस्ट्रेशन एंडपॉइंट की जानकारी देनी होगी या Play Console के यूज़र इंटरफ़ेस (यूआई) में सीधे तौर पर क्लाइंट आईडी/सीक्रेट डालना होगा.

अगर आपका ऑथराइज़ेशन सर्वर, डाइनैमिक क्लाइंट रजिस्ट्रेशन (डीसीआर) के साथ काम नहीं करता है, तो आपको इंटिग्रेशन पूरा करने के लिए, Play Console के यूज़र इंटरफ़ेस (यूआई) में क्लाइंट आईडी और क्लाइंट सीक्रेट फ़ील्ड को मैन्युअल तरीके से लागू करना होगा और भरना होगा.

अगर आपके सिस्टम में, Proof Key for Code Exchange (PKCE) या स्थायी सेशन की सुविधा काम करती है, तो आपको अपने डिस्कवरी JSON में, काम करने वाले फ़ील्ड (जैसे, चैलेंज के तरीके और OAuth के इस्तेमाल की अनुमति के टाइप) शामिल करने होंगे. इससे यह पक्का करने में मदद मिलती है कि Gemini के सुरक्षा और कनेक्टिविटी स्टैंडर्ड का पालन किया जा रहा है. अगर आपको स्कोप की सुविधा देनी है, तो आपको scopes_supported फ़ील्ड शामिल करना होगा.

कॉन्फ़िगरेशन का उदाहरण

यहां एक मान्य JSON रिस्पॉन्स दिया गया है, जो हमारे क्लाइंट की ज़रूरतों को पूरा करता है.

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

अगर आपने PKCE को शामिल किया है, तो यहां दिए गए स्निपेट में एक उदाहरण दिया गया है. इससे पता चलता है कि JSON ब्लॉक में क्या शामिल किया जा सकता है.

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

अगर आपने scopes_supported फ़ील्ड शामिल किया है, तो यहां दिया गया स्निपेट दिखाता है कि JSON ब्लॉक में क्या शामिल किया जा सकता है.

"scopes_supported": ["mcp", "cart.order"],

ऑथराइज़ेशन कोड फ़्लो (आसान वर्शन)

यहां स्टैंडर्ड ऑथराइज़ेशन कोड फ़्लो के बारे में बताया गया है. इस सीक्वेंस से पता चलता है कि Connected Apps Platform, उपयोगकर्ता की ओर से कार्रवाई करने के लिए, आपके सर्वर से ज़रूरी ऐक्सेस टोकन सुरक्षित तरीके से कैसे हासिल करता है.

1. अनुमति का अनुरोध: Google के प्लैटफ़ॉर्म को आपके फ़ंक्शन को कॉल करने की ज़रूरत होती है, लेकिन उपयोगकर्ता को अब तक अनुमति नहीं मिली है. चैटबॉट, उपयोगकर्ता के ब्राउज़र को आपके अनुमति देने वाले एंडपॉइंट पर रीडायरेक्ट करके या लिंक दिखाकर, फ़्लो शुरू करता है.

   इस अनुरोध में आपका क्लाइंट आईडी (या डीसीआर की मदद से अपने-आप जनरेट हुआ आईडी), Gemini का रीडायरेक्ट यूआरआई, और ज़रूरी पीकेसीई पैरामीटर (code_challenge और code_challenge_method) शामिल होते हैं.

   OAuth सेटअप के लिए, इन यूआरएल को अनुमति वाली सूची में जोड़ें:

   • https://oauth-redirect.googleusercontent.com/r/*
   • https://oauth-redirect-sandbox.googleusercontent.com/r/*
   • https://oauth-redirect-test.googleusercontent.com/r/*
   • https://oauth-redirect.googleusercontent.com/a/*
   • https://oauth-redirect-sandbox.googleusercontent.com/a/*
   • https://oauth-redirect-test.googleusercontent.com/a/*

2. उपयोगकर्ता की सहमति: आपका ऑथराइज़ेशन सर्वर, अनुरोध की पुष्टि करता है. साथ ही, उपयोगकर्ता की पुष्टि (लॉगिन) करता है. इसके बाद, उपयोगकर्ता से Google प्लैटफ़ॉर्म को उसका डेटा या सेवा ऐक्सेस करने की अनुमति देने के लिए कहता है.

3. कोड देना: उपयोगकर्ता की सहमति मिलने के बाद, आपका सर्वर उपयोगकर्ता के ब्राउज़र को Gemini के RedirectURI पर वापस रीडायरेक्ट करता है. साथ ही, यूआरएल में अनुमति देने वाला एक अस्थायी कोड जोड़ता है.

4. टोकन एक्सचेंज: Gemini का बैकएंड, आपके टोकन एंडपॉइंट पर POST अनुरोध भेजता है. इससे ऑथराइज़ेशन कोड को ऐक्सेस टोकन से बदल दिया जाता है.

   ध्यान दें: इस अनुरोध में PKCE पैरामीटर (code_verifier) शामिल होना चाहिए, ताकि यह साबित किया जा सके कि यह वही क्लाइंट है जिसने फ़्लो शुरू किया था.

5. ऐक्सेस दिया गया: आपका टोकन एंडपॉइंट, कोड और PKCE पैरामीटर की पुष्टि करता है. इसके बाद, वह ऐक्सेस टोकन और ज़रूरत पड़ने पर रीफ़्रेश टोकन जारी करता है. साथ ही, उन्हें Gemini को वापस भेजता है.

   अहम जानकारी: रीफ़्रेश टोकन ज़रूरी नहीं हैं. हालांकि, हमारा सुझाव है कि आप अपने ऑथराइज़ेशन सर्वर को कॉन्फ़िगर करें, ताकि वह रीफ़्रेश टोकन जारी कर सके. रिफ़्रेश टोकन की मदद से, Connected Apps Platform को उपयोगकर्ता की फिर से पुष्टि किए बिना ऐक्सेस बनाए रखने की सुविधा मिलती है.

PKCE से जुड़ी ज़रूरी शर्तें

PKCE, सुरक्षा की एक लेयर जोड़ता है, ताकि अनुमति देने वाले कोड को बिना अनुमति के इंटरसेप्ट न किया जा सके.

चेतावनी: ऐक्सेस और रीफ़्रेश टोकन को सही तरीके से मैनेज करने के लिए, पीकेसीई की इन ज़रूरी शर्तों को पूरा करना ज़रूरी है. इससे उपयोगकर्ता के डेटा को सुरक्षित रखने और नेटवर्क की सुरक्षा को बनाए रखने में मदद मिलती है.

• code_verifier: क्रिप्टोग्राफ़िक तौर पर रैंडम स्ट्रिंग, जिसे Gemini ने फ़्लो की शुरुआत में जनरेट किया है. इसे निजी रखा जाता है.
• code_challenge: code_verifier का ट्रांसफ़ॉर्मेशन, आम तौर पर SHA256 हैशिंग. इसे सार्वजनिक तौर पर भेजा जाता है, जैसा कि ऑथराइज़ेशन कोड फ़्लो के पहले चरण में बताया गया है.
• पुष्टि करना: आपके टोकन एंडपॉइंट (ऑथराइज़ेशन कोड फ़्लो के चौथे चरण में बताया गया है) को यह पुष्टि करनी होगी कि ट्रांसफ़ॉर्म किया गया code_verifier, ओरिजनल code_challenge से मैच करता है.

डीबग करना

लिंक करने से जुड़ी गड़बड़ी की ज़्यादा जानकारी, लॉग एक्सप्लोरर में उपलब्ध होती है. गड़बड़ियों को चालू करने और देखने के लिए, अपने Google Console प्रोजेक्ट में, खाता लिंक करने से जुड़ी गड़बड़ियों को मॉनिटर करना में दिए गए निर्देशों का पालन करें.

Google खाते को लिंक करने के कॉन्फ़िगरेशन से जुड़ी ज़रूरी शर्तें

Google खाते को लिंक करने के कॉन्फ़िगरेशन के बारे में जानकारी पाने के लिए, एपीआई से जुड़े ये दिशा-निर्देश पढ़ें.

• OAuth की मदद से Google खाते को किसी दूसरे खाते से लिंक करने की सुविधा
• Your Account Linking API
• Google Account Linking API

OAuth इंटिग्रेशन को रजिस्टर करने के लिए, आपको अपने ऑथराइज़ेशन सर्वर के बारे में कुछ खास जानकारी कॉन्फ़िगर करनी होगी. पक्का करें कि आपके पास ये एंडपॉइंट, क्रेडेंशियल, और ऐसेट तैयार हों.

कॉन्फ़िगरेशन फ़ील्ड	ब्यौरा	डेवलपर की ज़िम्मेदारी
क्लाइंट आईडी और सीक्रेट	यूनीक क्रेडेंशियल, जिन्हें आपका ऑथराइज़ेशन सर्वर खास तौर पर Connected Apps Platform के लिए जनरेट करता है. क्लाइंट सीक्रेट, क्लाइंट आईडी से जुड़ा सुरक्षित क्रेडेंशियल (पासवर्ड) होता है. ध्यान दें: अगर डेवलपर ने क्लाइंट आईडी जारी किया है, तो उसे यह आईडी देना होगा. अगर Google ने क्लाइंट आईडी जारी किया है, तो हो सकता है कि डेवलपर को कोई सीक्रेट रजिस्टर करना पड़े या किसी सीक्रेट की पुष्टि करनी पड़े.	अनुमति के सभी अनुरोधों में, प्लैटफ़ॉर्म से मिले आईडी का इस्तेमाल करें.
ऑथराइज़ेशन एंडपॉइंट	उपयोगकर्ताओं को पुष्टि करने और सहमति देने के लिए रीडायरेक्ट करने वाला यूआरएल	एंडपॉइंट को होस्ट करें—उदाहरण के लिए, https://yourdomain.com/oauth/authorize
टोकन एंडपॉइंट	बैकएंड एंडपॉइंट, ऑथराइज़ेशन कोड को ऐक्सेस/रीफ़्रेश टोकन से बदलने और समयसीमा खत्म हो चुके टोकन को रीफ़्रेश करने के लिए होता है.	इस एंडपॉइंट को होस्ट करें—उदाहरण के लिए, https://yourdomain.com/oauth/token
Revocation Endpoint ज़रूरी नहीं	जब कोई उपयोगकर्ता डिसकनेक्ट करता है, तो आपके सिस्टम को टोकन अमान्य करने की सूचना देने वाला यूआरएल. जब कोई उपयोगकर्ता, कनेक्ट किए गए ऐप्लिकेशन के प्लैटफ़ॉर्म से आपके इंटिग्रेशन को अनलिंक या डिसकनेक्ट करता है, तो हम /revoke एंडपॉइंट पर POST अनुरोध भेजेंगे. इसमें ऐक्सेस या रीफ़्रेश टोकन शामिल होगा. ज़्यादा जानकारी के लिए, खातों को अनलिंक करना लेख पढ़ें.	एंडपॉइंट को होस्ट करें—उदाहरण के लिए, https://yourdomain.com/oauth/revoke आपके सर्वर को इस अनुरोध को पूरा करना होगा. इसके लिए, उसे दिए गए टोकन को हमेशा के लिए अमान्य करना होगा. इससे यह पक्का होता है कि कनेक्ट किए गए ऐप्लिकेशन का प्लैटफ़ॉर्म, उस टोकन का इस्तेमाल नहीं कर पाएगा. इससे, डिसकनेक्ट होने के बाद उपयोगकर्ता का डेटा सुरक्षित रहता है.
रीडायरेक्ट यूआरआई	प्लैटफ़ॉर्म से मिला कॉलबैक यूआरएल, जहां अनुमति देने वाला सर्वर, सहमति मिलने के बाद कोड वापस भेजता है.	अपने ऑथराइज़ेशन सर्वर को इस तरह कॉन्फ़िगर करें कि वह प्लैटफ़ॉर्म से सिर्फ़ आधिकारिक और रजिस्टर किए गए रीडायरेक्ट यूआरआई को स्वीकार करे.
रीफ़्रेश करना	grant_type=refresh_token के साथ /token एक ऐसा तरीका जिससे Connected Apps Platform को मौजूदा ऐक्सेस टोकन की समयसीमा खत्म होने पर, नया ऐक्सेस टोकन मिल जाता है. इससे इंटिग्रेशन आसानी से कनेक्ट रहता है और उपयोगकर्ता को बार-बार लॉग इन करने की ज़रूरत नहीं पड़ती. जब मौजूदा ऐक्सेस टोकन की समयसीमा खत्म हो जाती है, तो कनेक्टेड ऐप्लिकेशन प्लैटफ़ॉर्म आपके /token एंडपॉइंट पर अपने-आप POST अनुरोध करेगा. अनुरोध के पेलोड में grant_type=refresh_token के साथ-साथ, वह रीफ़्रेश टोकन भी शामिल होगा जो आपके सर्वर ने पहले जारी किया था.	आपके सर्वर को, दिए गए रीफ़्रेश टोकन की पुष्टि करनी होगी. साथ ही, JSON रिस्पॉन्स में एक नया ऐक्सेस टोकन दिखाना होगा. इसके अलावा, पर्ज़िस्टेंट लिंकिंग को लागू करने के लिए, आपको इस एक्सचेंज के दौरान रीफ़्रेश टोकन को रोटेट करने से बचना चाहिए. नया टोकन जारी करने के बजाय, JSON रिस्पॉन्स में वही रीफ़्रेश टोकन दिखाएं और अपने बैकएंड पर इसकी समयसीमा खत्म होने की तारीख बढ़ाएं.
जवाब का टाइप	ऑथराइज़ेशन कोड फ़्लो के साथ काम करने के लिए, इसे CODE पर कॉन्फ़िगर किया जाना चाहिए.
स्कोप	अनुमतियों और ऐक्सेस लेवल का सेट, जिससे यह तय होता है कि टोकन को क्या करने की अनुमति है. इन्हें आपके कॉन्फ़िगरेशन में पहले से तय किया जाना चाहिए, ताकि Google शुरुआती अनुमति के हैंडशेक के दौरान इनका अनुरोध कर सके.	आपको डिफ़ॉल्ट स्कोप की सूची देनी होगी. उदाहरण के लिए, openid, profile, email. फ़्लो शुरू करते समय, कनेक्ट किए गए ऐप्लिकेशन के प्लैटफ़ॉर्म को इस सूची का अनुरोध करना चाहिए. अनुरोध किए गए स्कोप कम से कम होने चाहिए (कम से कम अधिकारों का सिद्धांत). हालांकि, ये स्कोप उन क्रिटिकल यूज़र जर्नी (सीयूजे) के लिए काफ़ी होने चाहिए जो आपके एमसीपी इंटिग्रेशन के साथ काम करती हैं.
यूज़र इंटरफ़ेस (यूआई) ऐसेट: लोगो	डेवलपर का लोगो, जो खाते को लिंक करने और ऐसी स्क्रीन जहां OAuth के लिए सहमति दी जाती है, पर दिखता है.	यह एक स्क्वेयर वेक्टर इमेज (एसवीजी) होनी चाहिए, जो गोल आकार में दिखे. साथ ही, इसका साइज़ कम से कम 500 x 500 पिक्सल होना चाहिए. उदाहरण के लिए, https://[partner-domain]/assets/logo.svg या रॉ SVG फ़ाइल देखें.
खास ऐप्लिकेशन को लिंक करना (ऐप्लिकेशन फ़्लिप)	हमारा सुझाव है कि अपने नेटिव Android या iOS ऐप्लिकेशन से सीधे तौर पर खाते को लिंक करने के लिए, स्टैंडर्ड वेबव्यू का इस्तेमाल न करें. इसके बजाय, हमारा सुझाव है कि आप ऐप्लिकेशन फ़्लिप को लागू करें, ताकि उपयोगकर्ताओं को बेहतर अनुभव मिल सके. ज़्यादा जानकारी के लिए, OAuth पर आधारित ऐप्लिकेशन फ़्लिप की मदद से, Google खाते को लिंक करना लेख पढ़ें.	Play Store और App Store पर पुष्टि की प्रक्रिया पूरी करें. साथ ही, Google के रीडायरेक्ट यूआरआई को सीधे अपने नेटिव ऐप्लिकेशन में एम्बेड करें. इससे, एक ऐप्लिकेशन से दूसरे ऐप्लिकेशन पर सुरक्षित तरीके से अनुमति देने की सुविधा मिलती है.
टोकन की समयसीमा	(ज़रूरी नहीं) वह अवधि जिसके लिए ऐक्सेस टोकन मान्य होता है. इसके बाद, टोकन को रीफ़्रेश करना ज़रूरी होता है. यह GAL में टाइम आउट की नीतियों को कॉन्फ़िगर करने के लिए काम का है.	सुरक्षा से जुड़ी ज़रूरतों के हिसाब से, समयसीमा खत्म होने का समय मिनट, घंटे, और दिनों में हो सकता है. उदाहरण के लिए, 30 days)

इंटिग्रेशन से जुड़ी सामान्य गड़बड़ियां

यहां इंटिग्रेशन की प्रोसेस के दौरान होने वाली सामान्य गड़बड़ियों और उन्हें ठीक करने के संभावित तरीकों की सूची दी गई है.

• "कोड" ग्रांट मौजूद नहीं है: Gemini प्लैटफ़ॉर्म का ऑटोमेटेड सिस्टम (कार्रवाइयों को अपने-आप पूरा करने वाला सिस्टम), response_types_supported में "कोड" वैल्यू को साफ़ तौर पर खोजता है.
• रजिस्ट्रेशन एंडपॉइंट मौजूद नहीं है: भले ही आपका सर्वर, क्लाइंट आईडी मेटाडेटा दस्तावेज़ों के साथ काम करता हो, लेकिन Gemini ऐप्लिकेशन (आपके सर्वर से कनेक्ट होने वाले OAuth क्लाइंट के तौर पर काम करता है) को फ़िलहाल, डिस्कवरी JSON में एक खास registration_endpoint की ज़रूरत होती है.
• 200 के अलावा कोई अन्य गड़बड़ी: अगर Gemini का ऑटोमेटेड मेटाडेटा डिस्कवरी मैकेनिज़्म, well-known पाथ प्रीफ़िक्स वाले आपके यूआरएल को हिट करता है और उसे 404 या 500 गड़बड़ी मिलती है, तो वह अन्य यूआरएल का अनुमान लगाने की कोशिश नहीं करेगा. कृपया पक्का करें कि डिस्कवरी यूआरएल को सार्वजनिक तौर पर ऐक्सेस किया जा सके.