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

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

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

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

विकल्प

अगर आपको Android, iOS, macOS, Linux या Windows (इसमें Universal Windows Platform भी शामिल है) जैसे किसी ऐसे प्लैटफ़ॉर्म के लिए ऐप्लिकेशन बनाना है जिसके पास ब्राउज़र और पूरी इनपुट सुविधाओं का ऐक्सेस है, तो मोबाइल और डेस्कटॉप ऐप्लिकेशन के लिए OAuth 2.0 फ़्लो का इस्तेमाल करें. (आपको उस फ़्लो का इस्तेमाल तब भी करना चाहिए, जब आपका ऐप्लिकेशन ग्राफ़िकल इंटरफ़ेस के बिना, कमांड-लाइन वाला टूल हो.)

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

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

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

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

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

1. Open the API Library में Google API Console.
2. If prompted, select a project, or create a new one.
3. API Library में, प्रॉडक्ट फ़ैमिली और लोकप्रियता के हिसाब से व्यवस्थित किए गए सभी उपलब्ध एपीआई की सूची होती है. आपको जिस एपीआई को चालू करना है अगर वह सूची में नहीं दिख रहा है, तो उसे ढूंढने के लिए खोजें का इस्तेमाल करें या इसके प्रॉडक्ट फ़ैमिली में सभी देखें पर क्लिक करें.
4. वह एपीआई चुनें जिसे आपको चालू करना है. इसके बाद, चालू करें बटन पर क्लिक करें.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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

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

1. Go to the Credentials page.
2. क्रेडेंशियल बनाएं > OAuth क्लाइंट आईडी पर क्लिक करें.
3. टीवी और सीमित इनपुट डिवाइस के लिए ऐप्लिकेशन टाइप चुनें.
4. अपने OAuth 2.0 क्लाइंट को कोई नाम दें और बनाएं पर क्लिक करें.

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

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

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

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

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

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

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

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

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

इस प्रोसेस के बारे में नीचे दी गई इमेज में बताया गया है:

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

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

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

पैरामीटर
client_id	ज़रूरी है आपके ऐप्लिकेशन का क्लाइंट आईडी. यह वैल्यू आपको API Console Credentials pageमें दिखेगी.
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	आपके ऐप्लिकेशन का क्लाइंट आईडी. यह वैल्यू आपको API Console Credentials pageमें दिखेगी.
client_secret	दिए गए client_id के लिए क्लाइंट सीक्रेट. यह वैल्यू, आपको API Console Credentials pageमें मिलेगी.
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 का अनुमति देने वाला सर्वर, हर पोलिंग अनुरोध का जवाब इनमें से किसी एक के साथ देता है:

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

अगर उपयोगकर्ता ने सहमति वाली स्क्रीन पर 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 खाता, अनुरोध किए गए एक या उससे ज़्यादा स्कोप को अनुमति नहीं दे पा रहा है. ऐसा, Google Workspace एडमिन की नीतियों की वजह से हो रहा है. 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&
client_secret=your_client_secret&
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",
  "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 फ़्लो, सिर्फ़ इन स्कोप के लिए काम करता है:

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 की क्रॉस-खाता सुरक्षा सेवा का इस्तेमाल करके, क्रॉस-खाता सुरक्षा लागू करें. इस सेवा की मदद से, आपके पास सुरक्षा से जुड़े इवेंट की सूचनाएं पाने की सदस्यता लेने का विकल्प होता है. इन सूचनाओं से, आपके ऐप्लिकेशन को उपयोगकर्ता खाते में हुए बड़े बदलावों के बारे में जानकारी मिलती है. इसके बाद, इस जानकारी का इस्तेमाल करके कार्रवाई की जा सकती है. यह इस बात पर निर्भर करता है कि आपने इवेंट के जवाब में क्या किया है.

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

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