टीवी और सीमित इनपुट डिवाइस ऐप्लिकेशन के लिए OAuth 2.0

अहम जानकारी: यह OAuth 2.0 फ़्लो, दायरों के सीमित सेट के साथ काम करता है.

इस दस्तावेज़ में, टीवी, गेम कंसोल, और प्रिंटर जैसे डिवाइसों पर चल रहे ऐप्लिकेशन का इस्तेमाल करके, Google API को ऐक्सेस करने के लिए OAuth 2.0 ऑथराइज़ेशन को लागू करने का तरीका बताया गया है. खास तौर पर, यह फ़्लो उन डिवाइसों के लिए डिज़ाइन किया गया है जिनके पास ब्राउज़र का ऐक्सेस नहीं है या जिनमें इनपुट की सुविधाएं सीमित हैं.

OAuth 2.0 की मदद से, उपयोगकर्ता किसी ऐप्लिकेशन के साथ चुनिंदा डेटा शेयर कर सकते हैं. साथ ही, अपने उपयोगकर्ता नाम, पासवर्ड, और अन्य जानकारी को निजी रख सकते हैं. उदाहरण के लिए, टीवी ऐप्लिकेशन, Google Drive में सेव की गई किसी फ़ाइल को चुनने की अनुमति पाने के लिए, OAuth 2.0 का इस्तेमाल कर सकता है.

इस फ़्लो का इस्तेमाल करने वाले ऐप्लिकेशन, अलग-अलग डिवाइसों पर उपलब्ध कराए जाते हैं. इसलिए, यह माना जाता है कि ऐप्लिकेशन, सीक्रेट को सुरक्षित नहीं रख सकते. जब उपयोगकर्ता ऐप्लिकेशन का इस्तेमाल कर रहा हो या ऐप्लिकेशन बैकग्राउंड में चल रहा हो, तब ये Google API को ऐक्सेस कर सकते हैं.

अन्य विकल्प

अगर आपको उपयोगकर्ताओं को सिर्फ़ उनके Google खातों से साइन इन कराना है और उपयोगकर्ता की प्रोफ़ाइल की बुनियादी जानकारी पाने के लिए JWT आईडी टोकन का इस्तेमाल करना है, तो टीवी और सीमित इनपुट डिवाइसों पर साइन-इन करना लेख पढ़ें.

ज़रूरी शर्तें

अपने प्रोजेक्ट के लिए एपीआई चालू करना

Google API को कॉल करने वाले किसी भी ऐप्लिकेशन को, API Console में उन एपीआई को चालू करना होगा.

अपने प्रोजेक्ट के लिए कोई एपीआई चालू करने के लिए:

1. Google API Console में एपीआई लाइब्रेरी खोलें.
2. अगर कहा जाए, तो कोई प्रोजेक्ट चुनें या नया प्रोजेक्ट बनाएं.
3. एपीआई लाइब्रेरी में, उपलब्ध सभी एपीआई की सूची होती है. इन्हें प्रॉडक्ट फ़ैमिली और लोकप्रियता के हिसाब से ग्रुप में बांटा जाता है. अगर आपको सूची में वह एपीआई नहीं दिख रहा है जिसे आपको चालू करना है, तो उसे ढूंढने के लिए खोज सुविधा का इस्तेमाल करें. इसके अलावा, उस प्रॉडक्ट फ़ैमिली में सभी देखें पर क्लिक करें जिससे वह एपीआई जुड़ा है.
4. आपको जो एपीआई चालू करना है उसे चुनें. इसके बाद, चालू करें बटन पर क्लिक करें.
5. अगर कहा जाए, तो बिलिंग की सुविधा चालू करें.
6. अगर कहा जाए, तो एपीआई की सेवा की शर्तें पढ़ें और उन्हें स्वीकार करें.

अनुमति देने के लिए क्रेडेंशियल बनाना

Google API को ऐक्सेस करने के लिए, OAuth 2.0 का इस्तेमाल करने वाले हर ऐप्लिकेशन के पास अनुमति देने वाले क्रेडेंशियल होने चाहिए. इनसे Google के OAuth 2.0 सर्वर को ऐप्लिकेशन की पहचान करने में मदद मिलती है. अपने प्रोजेक्ट के लिए क्रेडेंशियल बनाने का तरीका यहां बताया गया है. इसके बाद, आपके ऐप्लिकेशन उन एपीआई को ऐक्सेस करने के लिए क्रेडेंशियल का इस्तेमाल कर सकते हैं जिन्हें आपने उस प्रोजेक्ट के लिए चालू किया है.

1. क्लाइंट पेज पर जाएं.
2. क्लाइंट बनाएं पर क्लिक करें.
3. ऐप्लिकेशन टाइप के तौर पर, टीवी और सीमित इनपुट डिवाइस चुनें.
4. अपने OAuth 2.0 क्लाइंट को नाम दें और बनाएं पर क्लिक करें.

ऐक्सेस के स्कोप की पहचान करना

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

OAuth 2.0 ऑथराइज़ेशन लागू करने से पहले, हमारा सुझाव है कि आप उन स्कोप की पहचान करें जिन्हें ऐक्सेस करने के लिए, आपके ऐप्लिकेशन को अनुमति की ज़रूरत होगी.

ध्यान दें: इंस्टॉल किए गए ऐप्लिकेशन या डिवाइसों के लिए, इंक्रीमेंटल ऑथराइज़ेशन की सुविधा काम नहीं करती.

इंस्टॉल किए गए ऐप्लिकेशन या डिवाइसों के लिए, अनुमति वाले स्कोप की सूची देखें.

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

OAuth 2.0 ऐक्सेस टोकन पाना

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

1. आपका ऐप्लिकेशन, Google के अनुमति देने वाले सर्वर को एक अनुरोध भेजता है. इससे उन स्कोप की पहचान होती है जिन्हें ऐक्सेस करने की अनुमति के लिए आपका ऐप्लिकेशन अनुरोध करेगा.
2. सर्वर, बाद के चरणों में इस्तेमाल की जाने वाली जानकारी के कई हिस्सों के साथ जवाब देता है. जैसे, डिवाइस कोड और उपयोगकर्ता कोड.
3. ऐसी जानकारी दिखाई जाती है जिसे उपयोगकर्ता किसी दूसरे डिवाइस पर डालकर, आपके ऐप्लिकेशन को अनुमति दे सकता है.
4. आपका ऐप्लिकेशन, Google के अनुमति देने वाले सर्वर को पोल करना शुरू करता है, ताकि यह पता लगाया जा सके कि उपयोगकर्ता ने आपके ऐप्लिकेशन को अनुमति दी है या नहीं.
5. उपयोगकर्ता, इनपुट की बेहतर सुविधाओं वाले डिवाइस पर स्विच करता है और वेब ब्राउज़र लॉन्च करता है. इसके बाद, वह तीसरे चरण में दिखाए गए यूआरएल पर जाता है और तीसरे चरण में दिखाया गया कोड डालता है. इसके बाद, उपयोगकर्ता आपके ऐप्लिकेशन को ऐक्सेस करने की अनुमति दे सकता है या उसे अस्वीकार कर सकता है.
6. आपके पोलिंग अनुरोध के अगले जवाब में वे टोकन शामिल होते हैं जिनकी ज़रूरत आपके ऐप्लिकेशन को उपयोगकर्ता की ओर से अनुरोधों को अनुमति देने के लिए होती है. (अगर उपयोगकर्ता ने आपके ऐप्लिकेशन को ऐक्सेस देने से मना कर दिया है, तो जवाब में टोकन शामिल नहीं होते.)

इस इमेज में, इस प्रोसेस के बारे में बताया गया है:

यहां दिए गए सेक्शन में, इन चरणों के बारे में ज़्यादा जानकारी दी गई है. डिवाइसों में कई तरह की सुविधाएं और रनटाइम एनवायरमेंट हो सकते हैं. इसलिए, इस दस्तावेज़ में दिए गए उदाहरणों में curl कमांड लाइन यूटिलिटी का इस्तेमाल किया गया है. इन उदाहरणों को अलग-अलग भाषाओं और रनटाइम में पोर्ट किया जा सकता है.

पहला चरण: डिवाइस और उपयोगकर्ता कोड का अनुरोध करना

इस चरण में, आपका डिवाइस Google के अनुमति देने वाले सर्वर https://oauth2.googleapis.com/device/code पर एचटीटीपी पोस्ट अनुरोध भेजता है. इससे आपके ऐप्लिकेशन की पहचान होती है. साथ ही, यह भी पता चलता है कि उपयोगकर्ता की ओर से, आपके ऐप्लिकेशन को किस तरह के ऐक्सेस की ज़रूरत है. आपको device_authorization_endpoint मेटाडेटा वैल्यू का इस्तेमाल करके, खोज से जुड़े दस्तावेज़ से यह यूआरएल वापस पाना चाहिए. एचटीटीपी अनुरोध के ये पैरामीटर शामिल करें:

पैरामीटर
client_id	ज़रूरी है आपके ऐप्लिकेशन का क्लाइंट आईडी. यह वैल्यू, Cloud Console के क्लाइंट पेज में देखी जा सकती है.
scope	ज़रूरी है स्कोप की ऐसी सूची जिसमें हर स्कोप को स्पेस से अलग किया गया हो. इससे उन संसाधनों की पहचान की जाती है जिन्हें आपका ऐप्लिकेशन, उपयोगकर्ता की ओर से ऐक्सेस कर सकता है. इन वैल्यू से, सहमति वाली स्क्रीन को जानकारी मिलती है. Google इस स्क्रीन को उपयोगकर्ता को दिखाता है. इंस्टॉल किए गए ऐप्लिकेशन या डिवाइसों के लिए, अनुमति वाले स्कोप की सूची देखें. स्कोप की मदद से, आपका ऐप्लिकेशन सिर्फ़ उन संसाधनों को ऐक्सेस करने का अनुरोध कर सकता है जिनकी उसे ज़रूरत है. साथ ही, उपयोगकर्ता यह कंट्रोल कर सकते हैं कि वे आपके ऐप्लिकेशन को कितना ऐक्सेस दें. इसलिए, अनुरोध किए गए स्कोप की संख्या और उपयोगकर्ता की सहमति मिलने की संभावना के बीच, इन्वर्स रिलेशनशिप होता है.

उदाहरण

यहां दिए गए स्निपेट में, अनुरोध का एक सैंपल दिखाया गया है:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=email%20profile

इस उदाहरण में, वही अनुरोध भेजने के लिए curl कमांड दिखाया गया है:

curl -d "client_id=client_id&scope=email%20profile" \
     https://oauth2.googleapis.com/device/code

दूसरा चरण: अनुमति देने वाले सर्वर से मिले रिस्पॉन्स को मैनेज करना

ऑथराइज़ेशन सर्वर, इनमें से कोई एक जवाब देगा:

सफलता का जवाब

अगर अनुरोध मान्य है, तो आपको जवाब के तौर पर एक JSON ऑब्जेक्ट मिलेगा. इसमें ये प्रॉपर्टी शामिल होंगी:

प्रॉपर्टी
device_code	यह एक ऐसी वैल्यू है जिसे Google, उस डिवाइस की पहचान करने के लिए असाइन करता है जिस पर अनुमति का अनुरोध करने वाला ऐप्लिकेशन चल रहा है. उपयोगकर्ता को उस डिवाइस को किसी दूसरे डिवाइस से अनुमति देनी होगी, जिसमें इनपुट की बेहतर सुविधाएं हों. उदाहरण के लिए, कोई उपयोगकर्ता टीवी पर चल रहे किसी ऐप्लिकेशन को अनुमति देने के लिए, लैपटॉप या मोबाइल फ़ोन का इस्तेमाल कर सकता है. इस मामले में, device_code से टीवी की पहचान होती है. इस कोड की मदद से, ऐप्लिकेशन को चलाने वाला डिवाइस सुरक्षित तरीके से यह तय कर पाता है कि उपयोगकर्ता ने ऐक्सेस दिया है या नहीं.
expires_in	device_code और user_code की समयसीमा सेकंड में. अगर इस दौरान उपयोगकर्ता, अनुमति देने की प्रोसेस पूरी नहीं करता है और आपका डिवाइस भी उपयोगकर्ता के फ़ैसले की जानकारी पाने के लिए पोल नहीं करता है, तो आपको पहले चरण से इस प्रोसेस को फिर से शुरू करना पड़ सकता है.
interval	पोलिंग अनुरोधों के बीच, आपके डिवाइस को कितने सेकंड तक इंतज़ार करना चाहिए. उदाहरण के लिए, अगर वैल्यू 5 है, तो आपके डिवाइस को हर पांच सेकंड में Google के ऑथराइज़ेशन सर्वर को पोलिंग का अनुरोध भेजना चाहिए. ज़्यादा जानकारी के लिए, तीसरा चरण देखें.
user_code	यह केस-सेंसिटिव वैल्यू होती है. इससे Google को उन स्कोप की जानकारी मिलती है जिनका ऐक्सेस ऐप्लिकेशन मांग रहा है. आपका यूज़र इंटरफ़ेस, उपयोगकर्ता को इस वैल्यू को किसी ऐसे डिवाइस पर डालने के लिए कहेगा जिसमें इनपुट की बेहतर सुविधाएं हों. इसके बाद, Google इस वैल्यू का इस्तेमाल करके, स्कोप का सही सेट दिखाता है. ऐसा तब होता है, जब उपयोगकर्ता से आपके ऐप्लिकेशन को ऐक्सेस देने के लिए कहा जाता है.
verification_url	एक ऐसा यूआरएल जिस पर उपयोगकर्ता को किसी दूसरे डिवाइस पर जाना होगा, ताकि वह user_code डाल सके और आपके ऐप्लिकेशन को ऐक्सेस करने की अनुमति दे सके या उसे अस्वीकार कर सके. आपके यूज़र इंटरफ़ेस पर भी यह वैल्यू दिखेगी.

यहां दिए गए स्निपेट में, जवाब का एक सैंपल दिखाया गया है:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

कोटा खत्म होने पर मिलने वाला जवाब

अगर आपके डिवाइस कोड के अनुरोध, आपके क्लाइंट आईडी से जुड़े कोटे से ज़्यादा हो गए हैं, तो आपको 403 रिस्पॉन्स मिलेगा. इसमें यह गड़बड़ी शामिल होगी:

{
  "error_code": "rate_limit_exceeded"
}

ऐसे में, अनुरोधों की दर को कम करने के लिए, बैकऑफ़ रणनीति का इस्तेमाल करें.

तीसरा चरण: उपयोगकर्ता कोड दिखाना

उपयोगकर्ता को दूसरे चरण में मिले verification_url और user_code दिखाएं. दोनों वैल्यू में, US-ASCII वर्ण सेट का कोई भी प्रिंटेबल वर्ण शामिल हो सकता है. उपयोगकर्ता को जो कॉन्टेंट दिखाया जाए उसमें उसे किसी दूसरे डिवाइस पर verification_url पर जाने और user_code डालने का निर्देश दिया जाना चाहिए.

अपने यूज़र इंटरफ़ेस (यूआई) को इन नियमों को ध्यान में रखकर डिज़ाइन करें:

• user_code
  • user_code को ऐसे फ़ील्ड में दिखाया जाना चाहिए जिसमें 15 'W' साइज़ के वर्ण शामिल किए जा सकें. दूसरे शब्दों में, अगर कोड WWWWWWWWWWWWWWW को सही तरीके से दिखाया जा सकता है, तो आपका यूज़र इंटरफ़ेस (यूआई) मान्य है. हमारा सुझाव है कि यूज़र इंटरफ़ेस (यूआई) में user_code को दिखाने के तरीके की जांच करते समय, उस स्ट्रिंग वैल्यू का इस्तेमाल करें.
  • user_code केस-सेंसिटिव होता है. इसलिए, इसमें किसी भी तरह का बदलाव नहीं किया जाना चाहिए. जैसे, केस बदलना या फ़ॉर्मैटिंग के लिए इस्तेमाल होने वाले अन्य वर्ण शामिल करना.
• verification_url
  • verification_url दिखाने के लिए, आपके पास इतनी जगह होनी चाहिए कि 40 वर्णों वाली यूआरएल स्ट्रिंग को दिखाया जा सके.
  • आपको verification_url में किसी भी तरह का बदलाव नहीं करना चाहिए. हालांकि, आपके पास डिसप्ले के लिए स्कीम को हटाने का विकल्प होता है. अगर आपको यूआरएल से स्कीम (जैसे, https://) को हटाना है, तो पक्का करें कि आपका ऐप्लिकेशन, http और https, दोनों वैरिएंट को हैंडल कर सकता हो.

चेतावनी: इन दोनों वैल्यू में बदलाव हो सकता है. इसलिए, आपको अपने कोड में किसी भी वैल्यू को हार्डकोड नहीं करना चाहिए. इसी तरह, आपको verification_url से स्कीम को हटाने के अलावा, किसी भी अन्य तरीके से वैल्यू में बदलाव नहीं करना चाहिए.

चौथा चरण: Google के ऑथराइज़ेशन सर्वर को पोल करना

उपयोगकर्ता, verification_url पर जाने और ऐक्सेस देने (या अस्वीकार करने) के लिए किसी दूसरे डिवाइस का इस्तेमाल करेगा. इसलिए, जब उपयोगकर्ता ऐक्सेस के अनुरोध का जवाब देता है, तो अनुरोध करने वाले डिवाइस को अपने-आप सूचना नहीं मिलती. इस वजह से, अनुरोध करने वाले डिवाइस को Google के अनुमति देने वाले सर्वर को पोल करना होगा, ताकि यह पता चल सके कि उपयोगकर्ता ने अनुरोध का जवाब कब दिया.

अनुरोध करने वाले डिवाइस को तब तक पोलिंग अनुरोध भेजते रहना चाहिए, जब तक उसे कोई ऐसा जवाब न मिल जाए जिससे पता चले कि उपयोगकर्ता ने ऐक्सेस के अनुरोध का जवाब दे दिया है. इसके अलावा, तब तक पोलिंग अनुरोध भेजते रहना चाहिए, जब तक दूसरे चरण में मिले device_code और user_code की समयसीमा खत्म न हो जाए. दूसरे चरण में मिले interval से पता चलता है कि अनुरोधों के बीच कितने सेकंड इंतज़ार करना है.

पोल करने के लिए एंडपॉइंट का यूआरएल https://oauth2.googleapis.com/token है. पोलिंग के अनुरोध में ये पैरामीटर शामिल होते हैं:

पैरामीटर
client_id	आपके ऐप्लिकेशन का क्लाइंट आईडी. यह वैल्यू, Cloud Console के क्लाइंट पेज पर देखी जा सकती है.
client_secret	दिए गए client_id के लिए क्लाइंट सीक्रेट. यह वैल्यू, Cloud Console के क्लाइंट पेज पर देखी जा सकती है.
device_code	दूसरे चरण में, ऑथराइज़ेशन सर्वर से मिला device_code.
grant_type	इस वैल्यू को urn:ietf:params:oauth:grant-type:device_code पर सेट करें.

उदाहरण

यहां दिए गए स्निपेट में, अनुरोध का एक सैंपल दिखाया गया है:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

इस उदाहरण में, वही अनुरोध भेजने के लिए curl कमांड दिखाया गया है:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

पांचवां चरण: उपयोगकर्ता, ऐक्सेस के अनुरोध का जवाब देता है

ध्यान दें: इस चरण में, आपके ऐप्लिकेशन को कुछ करने की ज़रूरत नहीं है. बस, उसे अनुमति देने वाले सर्वर को पोल करना होगा. इसके बारे में पिछले चरण में बताया गया है.

यहां दी गई इमेज में, तीसरे चरण में दिखाए गए verification_url पर जाने के बाद, उपयोगकर्ताओं को दिखने वाले पेज जैसा पेज दिखाया गया है:

user_code डालने के बाद, अगर उपयोगकर्ता ने पहले से लॉग इन नहीं किया है, तो उसे Google में लॉग इन करना होगा. इसके बाद, उसे सहमति देने वाली स्क्रीन दिखेगी:

छठा चरण: पोलिंग के अनुरोधों के जवाब मैनेज करना

Google का ऑथराइज़ेशन सर्वर, पोलिंग के हर अनुरोध का जवाब इनमें से किसी एक तरीके से देता है:

ऐक्सेस दिया गया

अगर उपयोगकर्ता ने डिवाइस को ऐक्सेस करने की अनुमति दी है (ऐसी स्क्रीन जहां OAuth के लिए सहमति दी जाती है पर Allow पर क्लिक करके), तो रिस्पॉन्स में एक ऐक्सेस टोकन और एक रीफ़्रेश टोकन शामिल होता है. इन टोकन की मदद से, आपका डिवाइस उपयोगकर्ता की ओर से Google API को ऐक्सेस कर पाता है. scope प्रॉपर्टी से यह तय होता है कि डिवाइस किन एपीआई को ऐक्सेस कर सकता है.

इस मामले में, एपीआई से मिली जानकारी में ये फ़ील्ड शामिल होते हैं:

फ़ील्ड
access_token	वह टोकन जिसे आपका ऐप्लिकेशन, Google API के अनुरोध को अनुमति देने के लिए भेजता है.
expires_in	ऐक्सेस टोकन की समयसीमा खत्म होने में बचे सेकंड.
refresh_token	एक ऐसा टोकन जिसका इस्तेमाल करके, नया ऐक्सेस टोकन हासिल किया जा सकता है. रीफ़्रेश टोकन तब तक मान्य रहते हैं, जब तक उपयोगकर्ता ऐक्सेस वापस नहीं ले लेता या रीफ़्रेश टोकन की समयसीमा खत्म नहीं हो जाती. ध्यान दें कि डिवाइसों के लिए, रीफ़्रेश टोकन हमेशा दिखाए जाते हैं.
scope	access_token से मिले ऐक्सेस के स्कोप. इन्हें स्पेस से अलग की गई, केस-सेंसिटिव स्ट्रिंग की सूची के तौर पर दिखाया जाता है.
token_type	लौटाए गए टोकन का टाइप. यह वैल्यू हमेशा Bearer होती है.

यहां दिए गए स्निपेट में, जवाब का एक सैंपल दिखाया गया है:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

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

ऐक्सेस करने की अनुमति नहीं मिली

अगर उपयोगकर्ता डिवाइस का ऐक्सेस देने से मना कर देता है, तो सर्वर से मिलने वाले जवाब में 403 एचटीटीपी रिस्पॉन्स स्टेटस कोड (Forbidden) होता है. जवाब में यह गड़बड़ी शामिल होती है:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

अनुमति मिलना बाकी है

अगर उपयोगकर्ता ने अब तक अनुमति देने की प्रोसेस पूरी नहीं की है, तो सर्वर 428 एचटीटीपी रिस्पॉन्स स्टेटस कोड (Precondition Required) दिखाता है. रिस्पॉन्स में यह गड़बड़ी शामिल होती है:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

बहुत ज़्यादा बार पोल करना

अगर डिवाइस बहुत ज़्यादा पोलिंग अनुरोध भेजता है, तो सर्वर 403 एचटीटीपी रिस्पॉन्स स्टेटस कोड (Forbidden) दिखाता है. रिस्पॉन्स में यह गड़बड़ी शामिल होती है:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

दूसरी गड़बड़ियां

अगर पोलिंग के अनुरोध में कोई ज़रूरी पैरामीटर मौजूद नहीं है या पैरामीटर की वैल्यू गलत है, तो अनुमति देने वाला सर्वर भी गड़बड़ियां दिखाता है. आम तौर पर, इन अनुरोधों में 400 (Bad Request) या 401 (Unauthorized) एचटीटीपी रिस्पॉन्स स्टेटस कोड होता है. इन गड़बड़ियों में ये शामिल हैं:

गड़बड़ी	एचटीटीपी स्टेटस कोड	ब्यौरा
admin_policy_enforced	400	Google Workspace एडमिन की नीतियों की वजह से, Google खाता अनुरोध किए गए एक या उससे ज़्यादा स्कोप को अनुमति नहीं दे सकता. Google Workspace एडमिन के सहायता लेख तीसरे पक्ष और आपके डोमेन के मालिकाना हक वाले किन ऐप्लिकेशन से, Google Workspace का डेटा ऐक्सेस किया जा सकता है, इसे कंट्रोल करें को पढ़ें. इससे आपको इस बारे में ज़्यादा जानकारी मिलेगी कि कोई एडमिन, दायरों के ऐक्सेस पर तब तक पाबंदी कैसे लगा सकता है, जब तक आपके OAuth क्लाइंट आईडी को ऐक्सेस नहीं दिया जाता.
invalid_client	401	OAuth क्लाइंट नहीं मिला. उदाहरण के लिए, अगर client_id पैरामीटर की वैल्यू अमान्य है, तो यह गड़बड़ी होती है. OAuth क्लाइंट टाइप गलत है. पक्का करें कि क्लाइंट आईडी के लिए ऐप्लिकेशन टाइप, टीवी और सीमित इनपुट वाले डिवाइसों पर सेट हो.
invalid_grant	400	code पैरामीटर की वैल्यू अमान्य है, इस पर पहले ही दावा किया जा चुका है या इसे पार्स नहीं किया जा सकता.
unsupported_grant_type	400	grant_type पैरामीटर की वैल्यू अमान्य है.
org_internal	403	अनुरोध में मौजूद OAuth क्लाइंट आईडी, किसी ऐसे प्रोजेक्ट का हिस्सा है जो किसी खास Google Cloud संगठन में मौजूद Google खातों के ऐक्सेस को सीमित करता है. अपने OAuth ऐप्लिकेशन के लिए, उपयोगकर्ता टाइप के कॉन्फ़िगरेशन की पुष्टि करें.

Google API को कॉल करना

ऐप्लिकेशन को ऐक्सेस टोकन मिलने के बाद, टोकन का इस्तेमाल करके किसी उपयोगकर्ता खाते की ओर से Google API को कॉल किया जा सकता है. हालांकि, इसके लिए ज़रूरी है कि एपीआई को ऐक्सेस करने के लिए ज़रूरी स्कोप को अनुमति दी गई हो. इसके लिए, एपीआई को भेजे जाने वाले अनुरोध में ऐक्सेस टोकन शामिल करें. इसके लिए, access_token क्वेरी पैरामीटर या Authorization एचटीटीपी हेडर Bearer वैल्यू शामिल करें. जब भी संभव हो, एचटीटीपी हेडर का इस्तेमाल करना बेहतर होता है. ऐसा इसलिए, क्योंकि क्वेरी स्ट्रिंग, सर्वर लॉग में दिखती हैं. ज़्यादातर मामलों में, Google API को कॉल सेट अप करने के लिए क्लाइंट लाइब्रेरी का इस्तेमाल किया जा सकता है. उदाहरण के लिए, Drive Files API को कॉल करते समय.

OAuth 2.0 Playground पर जाकर, Google के सभी एपीआई आज़माए जा सकते हैं और उनके दायरे देखे जा सकते हैं.

एचटीटीपी GET के उदाहरण

Authorization: Bearer एचटीटीपी हेडर का इस्तेमाल करके, drive.files एंडपॉइंट (Drive Files API) को किया गया कॉल कुछ ऐसा दिख सकता है. ध्यान दें कि आपको अपना ऐक्सेस टोकन डालना होगा:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

यहां access_token क्वेरी स्ट्रिंग पैरामीटर का इस्तेमाल करके, पुष्टि किए गए उपयोगकर्ता के लिए उसी एपीआई को कॉल किया गया है:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl के उदाहरण

curl कमांड-लाइन ऐप्लिकेशन की मदद से, इन कमांड को टेस्ट किया जा सकता है. यहां एक उदाहरण दिया गया है, जिसमें एचटीटीपी हेडर विकल्प का इस्तेमाल किया गया है. हमारा सुझाव है कि आप भी इसी विकल्प का इस्तेमाल करें:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

इसके अलावा, क्वेरी स्ट्रिंग पैरामीटर का विकल्प:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

ऐक्सेस टोकन को रीफ़्रेश करना

ऐक्सेस टोकन समय-समय पर खत्म हो जाते हैं और किसी एपीआई अनुरोध के लिए अमान्य क्रेडेंशियल बन जाते हैं. अगर आपने टोकन से जुड़े स्कोप के लिए ऑफ़लाइन ऐक्सेस का अनुरोध किया है, तो उपयोगकर्ता से अनुमति मांगे बिना ऐक्सेस टोकन को रीफ़्रेश किया जा सकता है. भले ही, उपयोगकर्ता मौजूद न हो.

ऐक्सेस टोकन को रीफ़्रेश करने के लिए, आपका ऐप्लिकेशन Google के ऑथराइज़ेशन सर्वर (https://oauth2.googleapis.com/token) को एचटीटीपीएस POST अनुरोध भेजता है. इस अनुरोध के मुख्य हिस्से में ये पैरामीटर शामिल होते हैं:

नाम	वैल्यू
client_id	API Console से मिला क्लाइंट आईडी.
client_secret	ज़रूरी नहीं API Console से मिला क्लाइंट सीक्रेट.
grant_type	OAuth 2.0 की खास जानकारी में बताए गए तरीके के मुताबिक, इस फ़ील्ड की वैल्यू refresh_token पर सेट होनी चाहिए.
refresh_token	ऑथराइज़ेशन कोड एक्सचेंज से मिला रीफ़्रेश टोकन.

यहां दिए गए स्निपेट में, अनुरोध का एक सैंपल दिखाया गया है:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

जब तक उपयोगकर्ता, ऐप्लिकेशन को दिया गया ऐक्सेस वापस नहीं लेता, तब तक टोकन सर्वर एक JSON ऑब्जेक्ट दिखाता है. इसमें एक नया ऐक्सेस टोकन होता है. यहां दिए गए स्निपेट में, जवाब का एक सैंपल दिखाया गया है:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

ध्यान दें कि जारी किए जाने वाले रीफ़्रेश टोकन की संख्या सीमित होती है. हर क्लाइंट/उपयोगकर्ता के कॉम्बिनेशन के लिए एक सीमा होती है. साथ ही, सभी क्लाइंट के लिए हर उपयोगकर्ता के हिसाब से एक सीमा होती है. आपको रीफ़्रेश टोकन को लंबे समय तक सेव करके रखना चाहिए. साथ ही, जब तक वे मान्य हैं, तब तक उनका इस्तेमाल करना चाहिए. अगर आपका ऐप्लिकेशन बहुत ज़्यादा रीफ़्रेश टोकन का अनुरोध करता है, तो हो सकता है कि वह इन सीमाओं को पार कर जाए. ऐसे में, पुराने रीफ़्रेश टोकन काम करना बंद कर देंगे.

टोकन रद्द करना

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

ऐसा भी हो सकता है कि कोई ऐप्लिकेशन, प्रोग्राम के हिसाब से उसे दिए गए ऐक्सेस को रद्द कर दे. प्रोग्राम के हिसाब से टोकन रद्द करना उन मामलों में ज़रूरी है जहां कोई उपयोगकर्ता सदस्यता छोड़ देता है, किसी ऐप्लिकेशन को हटा देता है या किसी ऐप्लिकेशन के लिए ज़रूरी एपीआई संसाधनों में काफ़ी बदलाव हो गया है. दूसरे शब्दों में, ऐप्लिकेशन हटाने की प्रोसेस के तहत, एपीआई अनुरोध भी किया जा सकता है. इससे यह पक्का किया जा सकता है कि ऐप्लिकेशन को पहले दी गई अनुमतियां हटा दी गई हैं.

प्रोग्राम के हिसाब से टोकन रद्द करने के लिए, आपका ऐप्लिकेशन https://oauth2.googleapis.com/revoke को अनुरोध भेजता है और टोकन को पैरामीटर के तौर पर शामिल करता है:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

टोकन, ऐक्सेस टोकन या रीफ़्रेश टोकन हो सकता है. अगर टोकन एक ऐक्सेस टोकन है और उससे जुड़ा कोई रीफ़्रेश टोकन है, तो रीफ़्रेश टोकन भी रद्द कर दिया जाएगा.

अगर टोकन रद्द करने की प्रोसेस पूरी हो जाती है, तो जवाब का एचटीटीपी स्टेटस कोड 200 होता है. गड़बड़ी की स्थितियों के लिए, गड़बड़ी के कोड के साथ एचटीटीपी स्टेटस कोड 400 दिखाया जाता है.

अहम जानकारी: ऐक्सेस वापस लेने पर, किसी प्रोजेक्ट को पहले दिए गए सभी OAuth 2.0 स्कोप हटा दिए जाते हैं. इससे उस प्रोजेक्ट के तहत रजिस्टर किए गए सभी क्लाइंट के लिए, जारी किए गए ऐक्सेस या रीफ़्रेश टोकन अमान्य हो जाते हैं.

ध्यान दें: टोकन रद्द करने का अनुरोध स्वीकार होने के बाद, उसे पूरी तरह से रद्द होने में कुछ समय लग सकता है.

अनुमति वाले स्कोप

डिवाइसों के लिए OAuth 2.0 फ़्लो, सिर्फ़ इन स्कोप के लिए काम करता है:

OpenID Connect, Google साइन-इन

• email
• openid
• profile

Drive API

• https://www.googleapis.com/auth/drive.appdata
• https://www.googleapis.com/auth/drive.file

YouTube API

• https://www.googleapis.com/auth/youtube
• https://www.googleapis.com/auth/youtube.readonly

समय के हिसाब से ऐक्सेस

समय के हिसाब से ऐक्सेस देने की सुविधा से, उपयोगकर्ता आपके ऐप्लिकेशन को सीमित समय के लिए अपने डेटा का ऐक्सेस दे सकता है, ताकि कोई कार्रवाई पूरी की जा सके. सहमति देने की प्रोसेस के दौरान, Google के चुनिंदा प्रॉडक्ट में समय के हिसाब से ऐक्सेस देने की सुविधा उपलब्ध है. इससे उपयोगकर्ताओं को सीमित समय के लिए ऐक्सेस देने का विकल्प मिलता है. इसका एक उदाहरण Data Portability API है. इसकी मदद से, डेटा को एक बार ट्रांसफ़र किया जा सकता है.

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

'सभी खातों की सुरक्षा' सुविधा को लागू करना

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

Google की सभी खातों की सुरक्षा सेवा, आपके ऐप्लिकेशन को कुछ इवेंट भेजती है. इनके कुछ उदाहरण यहां दिए गए हैं:

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

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