डेस्कटॉप ऐप्लिकेशन के लिए OAuth 2.0

इस दस्तावेज़ में बताया गया है कि डेस्कटॉप ऐप्लिकेशन (जैसे, Windows, macOS या Linux पर चलने वाले ऐप्लिकेशन या कमांड-लाइन इंटरफ़ेस (सीएलआई) टूल), Google के एपीआई को ऐक्सेस करने की अनुमति देने के लिए, Google के OAuth 2.0 एंडपॉइंट का इस्तेमाल कैसे करते हैं.

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

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

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

लाइब्रेरी और सैंपल

डेस्कटॉप ऐप्लिकेशन के लिए OAuth 2.0 लागू करते समय, हमारा सुझाव है कि आप अपनी प्रोग्रामिंग भाषा (जैसे, Python, Java, Node.js, Go, .NET) के लिए, Google API क्लाइंट लाइब्रेरी का इस्तेमाल करें. क्लाइंट लाइब्रेरी, उपयोगकर्ता की अनुमति और टोकन मैनेजमेंट को हैंडल करती हैं. इससे, सीधे तौर पर लोअर-लेवल एचटीटीपी/आरईएसटी एंडपॉइंट का इस्तेमाल करने के मुकाबले, लागू करना आसान हो जाता है और गड़बड़ी होने की संभावना कम हो जाती है.

मोबाइल ऐप्लिकेशन के लिए, Android और iOS की अनुमति से जुड़ी गाइड देखें.

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

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

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

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. Name फ़ील्ड में, OAuth क्लाइंट का नाम डालें. यह नाम, आपके प्रोजेक्ट के क्लाइंट पेज पर दिखता है, ताकि क्लाइंट की पहचान की जा सके.
5. बनाएं पर क्लिक करें.

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

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

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

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

OAuth 2.0 API के दायरे वाले दस्तावेज़ में, उन सभी दायरों की सूची होती है जिनका इस्तेमाल Google API को ऐक्सेस करने के लिए किया जा सकता है.

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

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

पहला चरण: कोड वेरिफ़ायर और चैलेंज जनरेट करना

Google, प्रूफ़ की फ़ॉर कोड एक्सचेंज (पीकेसीई) प्रोटोकॉल के साथ काम करता है. इससे इंस्टॉल किए गए ऐप्लिकेशन के फ़्लो को ज़्यादा सुरक्षित बनाया जा सकता है. अनुमति देने के हर अनुरोध के लिए, एक यूनीक कोड वेरिफ़ायर बनाया जाता है. साथ ही, इसकी बदली हुई वैल्यू को "code_challenge" कहा जाता है. इसे अनुमति देने वाले सर्वर को भेजा जाता है, ताकि अनुमति देने वाला कोड मिल सके.

कोड वेरिफ़ायर बनाना

code_verifier, हाई-एंट्रॉपी क्रिप्टोग्राफ़िक रैंडम स्ट्रिंग होती है. इसमें [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~" जैसे वर्णों का इस्तेमाल किया जाता है. इसमें कम से कम 43 और ज़्यादा से ज़्यादा 128 वर्ण होने चाहिए.

कोड की पुष्टि करने वाले टूल में काफ़ी एंट्रॉपी होनी चाहिए, ताकि वैल्यू का अनुमान लगाना मुश्किल हो.

कोड चैलेंज बनाना

कोड चैलेंज बनाने के दो तरीके इस्तेमाल किए जा सकते हैं.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

दूसरा चरण: Google के OAuth 2.0 सर्वर को अनुरोध भेजना

उपयोगकर्ता की अनुमति पाने के लिए, Google के ऑथराइज़ेशन सर्वर https://accounts.google.com/o/oauth2/v2/auth पर अनुरोध भेजें. यह एंडपॉइंट, चालू सेशन को खोजने, उपयोगकर्ता की पुष्टि करने, और उपयोगकर्ता की सहमति लेने का काम करता है. एंडपॉइंट को सिर्फ़ एसएसएल के ज़रिए ऐक्सेस किया जा सकता है. साथ ही, यह एचटीटीपी (बिना एसएसएल वाले) कनेक्शन को अस्वीकार कर देता है.

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

अनुमति देने वाले यूआरएल के सैंपल

यहां दिए गए टैब में, अलग-अलग रीडायरेक्ट यूआरआई विकल्पों के लिए, अनुमति देने वाले यूआरएल के सैंपल दिखाए गए हैं.

redirect_uri पैरामीटर की वैल्यू को छोड़कर, यूआरएल एक जैसे हैं. यूआरएल में ज़रूरी response_type और client_id पैरामीटर के साथ-साथ, वैकल्पिक state पैरामीटर भी शामिल होता है. हर यूआरएल में लाइन ब्रेक और स्पेस होते हैं, ताकि उसे आसानी से पढ़ा जा सके.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

तीसरा चरण: Google, उपयोगकर्ता से सहमति मांगता है

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

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

चौथा चरण: OAuth 2.0 सर्वर से मिले जवाब को मैनेज करना

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

अगर उपयोगकर्ता आपके ऐप्लिकेशन को ऐक्सेस देता है, तो ऑथराइज़ेशन कोड को ऐक्सेस टोकन और रीफ़्रेश टोकन से बदला जा सकता है. इसके बारे में अगले चरण में बताया गया है.

पांचवां चरण: रीफ़्रेश और ऐक्सेस टोकन के लिए, ऑथराइज़ेशन कोड को एक्सचेंज करना

ऐक्सेस टोकन के लिए ऑथराइज़ेशन कोड को एक्सचेंज करने के लिए, https://oauth2.googleapis.com/token एंडपॉइंट को कॉल करें और ये पैरामीटर सेट करें:

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

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

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\
 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\
 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\
 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

DPoP प्रूफ़ बनाना

यहां बताया गया है कि कमांड लाइन से OpenSSL का इस्तेमाल करके, डीपीओपी प्रूफ़ कैसे बनाया जाता है:

1. ईसी P-256 कुंजी का जोड़ा जनरेट करें:

   openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
   openssl ec -in dpop_private.pem -pubout -out dpop_public.pem

2. डीपीओपी हेडर बनाएं:

   हेडर में typ, alg, और jwk (सार्वजनिक पासकोड) के दावे शामिल होने चाहिए. x और y वैल्यू, आपकी ईसी सार्वजनिक कुंजी के Base64Url-कोड में बदले गए निर्देशांक हैं. इस JSON को Base64Url कोड में बदलें:

   {
     "typ":"dpop+jwt",
     "alg":"ES256",
     "jwk": {
       "kty":"EC",
       "x":"YOUR_PUBLIC_KEY_X",
       "y":"YOUR_PUBLIC_KEY_Y",
       "crv":"P-256"
     }
   }

3. डीपीओपी पेलोड बनाएं:

   पेलोड में jti (अनुरोध के लिए यूनीक आइडेंटिफ़ायर), htm (एचटीटीपी तरीका, जैसे कि POST), htu (एचटीटीपी यूआरआई, जैसे कि https://oauth2.googleapis.com/token), और iat (जारी करने का समय) शामिल होना चाहिए. अगर आपको पिछले अनुरोध के जवाब में, DPoP-Nonce हेडर में सर्वर से कोई नॉन्स मिला है, तो आपको उस नॉन्स वैल्यू को nonce दावे में शामिल करना होगा. ऑथराइज़ेशन कोड एक्सचेंज के लिए, नॉन्स क्लेम करना ज़रूरी नहीं है. इसका इस्तेमाल सिर्फ़ तब किया जाता है, जब DPoP-Nonce हेडर पहले मिल चुका हो. इस JSON को Base64Url कोड में बदलें:

   {
     "jti":"JTI_VALUE",
     "htm":"POST",
     "htu":"https://oauth2.googleapis.com/token",
     "iat":YOUR_JWT_ISSUED_TIME,
     "nonce":"SERVER_PROVIDED_NONCE"
   }

   jti की वैल्यू, एक्सचेंज के टाइप पर निर्भर करती है:

   • ऑथराइज़ेशन कोड एक्सचेंज के लिए, jti, ऑथराइज़ेशन कोड का Base64Url-कोड में बदला गया SHA256 हैश होना चाहिए: "jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))".
   • रिफ़्रेश टोकन एक्सचेंज के लिए, jti हर अनुरोध के लिए एक यूनीक आइडेंटिफ़ायर होना चाहिए: "jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
4. सबूत पर हस्ताक्षर करना:

   एन्कोड किए गए हेडर और पेलोड को पीरियड (.) के साथ जोड़ें. इसके बाद, ES256 का इस्तेमाल करके, अपने निजी पासकोड से नतीजे पर हस्ताक्षर करें. ध्यान दें कि JWS के लिए, हस्ताक्षर को रॉ R | S कॉनकैटेनेटेड फ़ॉर्मैट (P-256 के लिए 64 बाइट) में होना चाहिए. अगर OpenSSL का सीधे तौर पर इस्तेमाल किया जा रहा है, तो आपको डिफ़ॉल्ट ASN.1 DER-एन्कोड किए गए सिग्नेचर को इस रॉ फ़ॉर्मैट में बदलना होगा.

सफल एक्सचेंज की जानकारी, टोकन वाले 200 OK रिस्पॉन्स से मिलती है. अगर एक्सचेंज के दौरान मान्य डीपीओपी प्रूफ़ का इस्तेमाल किया जाता है, तो Google जो रीफ़्रेश टोकन दिखाएगा वह आपकी कुंजी से डीपीओपी-बाउंड होगा. हालांकि, ऐक्सेस टोकन डीपीओपी बाउंड नहीं होंगे. ऐक्सेस टोकन में DPoP के बजाय Bearer की token_type बनी रहेगी. इसके अलावा, Google जवाब में DPoP-Nonce एचटीटीपी हेडर दिखाता है. आपके क्लाइंट को इस नॉन्स को कैश मेमोरी में सेव करना होगा. साथ ही, इसे बाद के अनुरोधों में डीपीओपी प्रूफ़ के nonce दावे में शामिल करना होगा. जैसे, रीफ़्रेश टोकन को नए ऐक्सेस टोकन से बदलते समय या डीपीओपी से सुरक्षित एपीआई को कॉल करते समय. पहले से जारी किए गए इस नॉन्स का इस्तेमाल करके, अपने अगले अनुरोध पर दोतरफ़ा यात्रा की गड़बड़ी (use_dpop_nonce) से बचा जा सकता है.

DPoP से बाउंड किए गए रीफ़्रेश टोकन के साथ किए गए टोकन एक्सचेंज के अनुरोधों के लिए, DPoP के सबूत शामिल किए जाने चाहिए.

एक्सचेंज पूरा न होने की समस्या तब आती है, जब DPoP हेडर मौजूद न हो, अमान्य हो या सबूत के तौर पर टोकन से बाउंड की गई कुंजी के बजाय किसी दूसरी कुंजी का इस्तेमाल किया गया हो. इन मामलों में, सर्वर 400 Bad Request गड़बड़ी दिखाता है. अगर डीपीओपी प्रूफ़ में htm या htu के दावे मेल नहीं खाते हैं, iat की समयसीमा खत्म हो गई है, jti का फिर से इस्तेमाल किया गया है या हस्ताक्षर अमान्य है, तो Google invalid_dpop_proof गड़बड़ी का कोड दिखाता है. अगर डीपीओपी नॉन्स की ज़रूरत है, जैसे कि रीफ़्रेश टोकन एक्सचेंज के दौरान, और डीपीओपी प्रूफ़ में nonce दावा मौजूद नहीं है या नॉन्स की वैल्यू सर्वर के लिए स्वीकार नहीं की जा सकती (उदाहरण के लिए, इसकी समयसीमा खत्म हो गई है, पहले ही इस्तेमाल की जा चुकी है या गलत है), तो Google use_dpop_nonce गड़बड़ी कोड के साथ-साथ DPoP-Nonce एचटीटीपी हेडर दिखाता है. इसमें एक नया नॉन्स होता है, जिसका इस्तेमाल बाद के अनुरोध में किया जा सकता है. अन्य गड़बड़ियों के लिए, invalid_grant दिख सकता है.

Google इस अनुरोध का जवाब, एक JSON ऑब्जेक्ट के तौर पर देता है. इसमें कम समय के लिए मान्य ऐक्सेस टोकन और रीफ़्रेश टोकन शामिल होता है.

जवाब में ये फ़ील्ड शामिल होते हैं:

यहां दिए गए स्निपेट में, डीपीओपी का इस्तेमाल करने पर मिलने वाले रिस्पॉन्स हेडर और मुख्य हिस्से का सैंपल दिखाया गया है:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

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

छठा चरण: यह देखना कि उपयोगकर्ताओं ने किन दायरों को ऐक्सेस करने की अनुमति दी है

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

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

ज़्यादा जानकारी के लिए, अलग-अलग अनुमतियों को मैनेज करने का तरीका देखें.

यह देखने के लिए कि उपयोगकर्ता ने आपके ऐप्लिकेशन को किसी खास दायरे का ऐक्सेस दिया है या नहीं, ऐक्सेस टोकन के जवाब में scope फ़ील्ड की जांच करें. access_token से दिए गए ऐक्सेस के स्कोप, स्पेस-डिलिमिटेड और केस-सेंसिटिव स्ट्रिंग की सूची के तौर पर दिखाए जाते हैं.

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

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

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 अनुरोध भेजता है. इस अनुरोध के मुख्य हिस्से में ये पैरामीटर शामिल होते हैं:

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

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

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

client_id=your_client_id&
refresh_token=refresh_token&
grant_type=refresh_token

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

एक्सचेंज पूरा होने पर, 200 OK रिस्पॉन्स मिलता है. इसमें नया ऐक्सेस टोकन शामिल होता है. डीपीओपी का इस्तेमाल करने पर, token_type, Bearer होता है. सफल जवाब से पुष्टि होती है कि रीफ़्रेश टोकन के लिए, डीपीओपी के सबूत को स्वीकार कर लिया गया है. Google, जवाब में एक नया DPoP-Nonce एचटीटीपी हेडर भी दिखा सकता है. अगर ऐसा होता है, तो आपके क्लाइंट को इस नॉन्स को कैश मेमोरी में सेव करना होगा. साथ ही, बाद के अनुरोधों में डीपीओपी के सबूत के nonce दावे में इसे शामिल करना होगा.

अगर DPoP हेडर मौजूद नहीं है, अमान्य है या गलत कुंजी का इस्तेमाल करता है, तो एक्सचेंज नहीं हो पाता. डीपीओपी की गड़बड़ी के खास कोड और नॉन्स को मैनेज करने के बारे में जानकारी पाने के लिए, एक्सचेंज नहीं हो सका लेख पढ़ें.

यहां दिए गए स्निपेट में, डीपीओपी का इस्तेमाल करने पर मिलने वाले रिस्पॉन्स हेडर और मुख्य हिस्से का सैंपल दिखाया गया है:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "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 दिखाया जाता है.

ऐप्लिकेशन पर रीडायरेक्ट करने के तरीके

अपने ऐप्लिकेशन सुरक्षित रखना

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

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

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

इस बारे में और पढ़ें

आईईटीएफ़ के सबसे सही मौजूदा तरीके OAuth 2.0 for खास ऐप्लिकेशन में, यहां बताए गए कई सबसे सही तरीके शामिल हैं.