टीवी और सीमित इनपुट डिवाइस ऐप्लिकेशन के लिए 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. Google API Consoleमें Open the API Library .
  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 API को ऐक्सेस करने के लिए 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, दोनों वैरिएंट को मैनेज कर सकता हो.

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

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

अनुरोध करने वाले डिवाइस को तब तक पोल के अनुरोध भेजते रहना चाहिए, जब तक उसे यह सूचना न मिले कि उपयोगकर्ता ने ऐक्सेस के अनुरोध का जवाब दे दिया है या जब तक चरण 2 में मिले 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 API को आज़माया जा सकता है और उनके दायरे देखे जा सकते हैं.

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

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 एपीआई

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