इस दस्तावेज़ में, टीवी, गेम कंसोल, और प्रिंटर जैसे डिवाइसों पर चलने वाले ऐप्लिकेशन के ज़रिए 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 को कॉल करने वाले किसी भी ऐप्लिकेशन को, उन एपीआई को में चालू करना होगा.
अपने प्रोजेक्ट के लिए एपीआई चालू करने के लिए:
- में .
- में, प्रॉडक्ट फ़ैमिली और लोकप्रियता के हिसाब से व्यवस्थित किए गए सभी उपलब्ध एपीआई की सूची होती है. अगर आपको जो एपीआई चालू करना है वह सूची में नहीं दिख रहा है, तो उसे खोजने के लिए खोज बार का इस्तेमाल करें या उस प्रॉडक्ट फ़ैमिली में सभी देखें पर क्लिक करें जिससे वह एपीआई जुड़ा है.
- वह एपीआई चुनें जिसे आपको चालू करना है. इसके बाद, चालू करें बटन पर क्लिक करें.
अनुमति देने वाले क्रेडेंशियल बनाना
Google के एपीआई को ऐक्सेस करने के लिए OAuth 2.0 का इस्तेमाल करने वाले किसी भी ऐप्लिकेशन के पास, अनुमति देने वाले ऐसे क्रेडेंशियल होने चाहिए जिनसे Google के OAuth 2.0 सर्वर को ऐप्लिकेशन की पहचान की जा सके. यहां अपने प्रोजेक्ट के लिए क्रेडेंशियल बनाने का तरीका बताया गया है. इसके बाद, आपके ऐप्लिकेशन उन एपीआई को ऐक्सेस करने के लिए क्रेडेंशियल का इस्तेमाल कर सकते हैं जिन्हें आपने उस प्रोजेक्ट के लिए चालू किया है.
- क्रेडेंशियल बनाएं > OAuth क्लाइंट आईडी पर क्लिक करें.
- टीवी और सीमित इनपुट डिवाइस के लिए ऐप्लिकेशन टाइप चुनें.
- अपने OAuth 2.0 क्लाइंट को नाम दें और बनाएं पर क्लिक करें.
ऐक्सेस के स्कोप की पहचान करना
स्कोप की मदद से, आपके ऐप्लिकेशन को सिर्फ़ उन संसाधनों का ऐक्सेस पाने का अनुरोध करने की सुविधा मिलती है जिनकी उसे ज़रूरत होती है. साथ ही, इससे उपयोगकर्ताओं को यह कंट्रोल करने की सुविधा भी मिलती है कि वे आपके ऐप्लिकेशन को कितना ऐक्सेस दें. इसलिए, अनुरोध किए गए स्कोप की संख्या और उपयोगकर्ता की सहमति पाने की संभावना के बीच उलटा संबंध हो सकता है.
हमारा सुझाव है कि OAuth 2.0 ऑथराइज़ेशन लागू करने से पहले, उन स्कोप की पहचान करें जिन्हें ऐक्सेस करने के लिए आपके ऐप्लिकेशन को अनुमति की ज़रूरत होगी.
इंस्टॉल किए गए ऐप्लिकेशन या डिवाइसों के लिए, अनुमति वाले स्कोप की सूची देखें.
OAuth 2.0 ऐक्सेस टोकन पाना
भले ही, आपका ऐप्लिकेशन सीमित इनपुट सुविधाओं वाले डिवाइस पर चलता हो, लेकिन अनुमति देने का यह फ़्लो पूरा करने के लिए, उपयोगकर्ताओं के पास बेहतर इनपुट सुविधाओं वाले डिवाइस का अलग ऐक्सेस होना चाहिए. इस फ़्लो में ये चरण शामिल हैं:
- आपका ऐप्लिकेशन, Google के अनुमति देने वाले सर्वर को एक अनुरोध भेजता है. इससे उन स्कोप की पहचान होती है जिन्हें ऐक्सेस करने के लिए आपका ऐप्लिकेशन अनुमति का अनुरोध करेगा.
- सर्वर, डिवाइस कोड और उपयोगकर्ता कोड जैसी कई जानकारी के साथ जवाब देता है. इस जानकारी का इस्तेमाल अगले चरणों में किया जाता है.
- आपने ऐसी जानकारी दिखाई है जिसे उपयोगकर्ता किसी दूसरे डिवाइस पर डालकर, आपके ऐप्लिकेशन को अनुमति दे सकता है.
- आपका ऐप्लिकेशन, Google के अनुमति देने वाले सर्वर से अनुरोध करना शुरू कर देता है. इससे यह पता चलता है कि उपयोगकर्ता ने आपके ऐप्लिकेशन को अनुमति दी है या नहीं.
- उपयोगकर्ता, बेहतर इनपुट सुविधाओं वाले डिवाइस पर स्विच करता है, वेब ब्राउज़र लॉन्च करता है, और तीसरे चरण में दिखाए गए यूआरएल पर जाता है. इसके बाद, वह तीसरे चरण में दिखाया गया कोड डालता है. इसके बाद, उपयोगकर्ता आपके ऐप्लिकेशन को ऐक्सेस करने की अनुमति दे सकता है या उसे अस्वीकार कर सकता है.
- पोलिंग के अनुरोध के अगले जवाब में वे टोकन शामिल होते हैं जिनकी ज़रूरत आपके ऐप्लिकेशन को, उपयोगकर्ता की ओर से अनुरोधों को अनुमति देने के लिए होती है. (अगर उपयोगकर्ता ने आपके ऐप्लिकेशन का ऐक्सेस देने से मना कर दिया है, तो रिस्पॉन्स में टोकन शामिल नहीं होते.)
इस प्रोसेस के बारे में नीचे दी गई इमेज में बताया गया है:
इन चरणों के बारे में ज़्यादा जानकारी, नीचे दिए गए सेक्शन में दी गई है. डिवाइसों में मौजूद सुविधाओं और रनटाइम के कई तरह के एनवायरमेंट को ध्यान में रखते हुए, इस दस्तावेज़ में दिए गए उदाहरणों में curl
कमांड लाइन की सुविधा का इस्तेमाल किया गया है. इन उदाहरणों को अलग-अलग भाषाओं और रनटाइम में आसानी से पोर्ट किया जा सकता है.
पहला चरण: डिवाइस और उपयोगकर्ता कोड का अनुरोध करना
इस चरण में, आपका डिवाइस https://oauth2.googleapis.com/device/code
पर, Google के अनुमति देने वाले सर्वर को एचटीटीपी पोस्ट अनुरोध भेजता है. इससे आपके ऐप्लिकेशन के साथ-साथ, उन ऐक्सेस स्कोप की पहचान होती है जिन्हें आपका ऐप्लिकेशन उपयोगकर्ता की ओर से ऐक्सेस करना चाहता है.
आपको device_authorization_endpoint
मेटाडेटा वैल्यू का इस्तेमाल करके,
डिस्कवरी दस्तावेज़ से यह यूआरएल पाना चाहिए. एचटीटीपी अनुरोध के इन पैरामीटर को शामिल करें:
पैरामीटर | |
---|---|
client_id |
ज़रूरी है
आपके ऐप्लिकेशन का क्लाइंट आईडी. यह वैल्यू आपको में दिखेगी. |
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 के अनुमति देने वाले सर्वर से पूछना होगा कि उपयोगकर्ता ने अनुरोध का जवाब कब दिया.
अनुरोध करने वाले डिवाइस को तब तक पोलिंग अनुरोध भेजते रहना चाहिए, जब तक उसे ऐसा रिस्पॉन्स न मिल जाए जिससे पता चलता हो कि उपयोगकर्ता ने ऐक्सेस के अनुरोध का जवाब दिया है या
दूसरे चरण में मिले device_code
और user_code
की समयसीमा खत्म हो गई हो. दूसरे चरण में दिखाया गया interval
, अनुरोधों के बीच इंतज़ार करने के लिए, सेकंड में समय बताता है.
पोल के लिए एंडपॉइंट का यूआरएल https://oauth2.googleapis.com/token
है. पोलिंग अनुरोध में ये पैरामीटर शामिल होते हैं:
पैरामीटर | |
---|---|
client_id |
आपके ऐप्लिकेशन का क्लाइंट आईडी. यह वैल्यू आपको में दिखेगी. |
client_secret |
दिए गए client_id के लिए क्लाइंट सीक्रेट. यह वैल्यू आपको
में दिखेगी. |
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 क्लाइंट नहीं मिला. उदाहरण के लिए, यह गड़बड़ी तब होती है, जब
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 |
से मिला क्लाइंट आईडी. |
client_secret |
से मिला क्लाइंट सीक्रेट. |
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 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 फ़्लो, सिर्फ़ इन स्कोप के लिए काम करता है:
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
सभी खातों की सुरक्षा की सुविधा को लागू करने के तरीके और उपलब्ध इवेंट की पूरी सूची के बारे में ज़्यादा जानने के लिए, सभी खातों की सुरक्षा की सुविधा की मदद से उपयोगकर्ता खातों को सुरक्षित रखें पेज पर जाएं .