डेटा प्लान एजेंट API के लिए OAuth

मिलते-जुलते दस्तावेज़

OAuth 2.0 को RFC 6749 के तौर पर स्टैंडर्ड किया गया है. इस बारे में ज़्यादा जानकारी देने वाला दस्तावेज़ https://oauth.net/2 पर उपलब्ध है. एचटीटीपी बेसिक ऑथेंटिकेशन के बारे में आरएफ़सी 2617 के सेक्शन 2 में बताया गया है.

खास जानकारी

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

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

इस इमेज में, जानकारी के फ़्लो के बारे में खास जानकारी दी गई है:

पहली इमेज. OAuth फ़्लो का ऐब्स्ट्रैक्ट.

ऐक्सेस टोकन

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

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

कैरियर की सुरक्षा से जुड़ी ज़रूरी शर्तों के आधार पर, ऐक्सेस टोकन के अलग-अलग फ़ॉर्मैट, स्ट्रक्चर, और इस्तेमाल करने के तरीके हो सकते हैं. उदाहरण के लिए, क्रिप्टोग्राफ़िक प्रॉपर्टी. GTAF, सिर्फ़ [RFC6750] में बताए गए बेयरर टाइप के ऐक्सेस टोकन के साथ काम करता है.

क्लाइंट की पुष्टि करना

GTAF, "भरोसेमंद क्लाइंट" के तौर पर काम करता है. साथ ही, यह पासवर्ड को सुरक्षित रख सकता है. फ़िलहाल, GTAF सिर्फ़ एचटीटीपी की सामान्य पुष्टि करने की सुविधा के साथ काम करता है. इससे DPA के साथ पुष्टि की जा सकती है. क्लाइंट आइडेंटिफ़ायर को "application/x-www-form-urlencoded" एन्कोडिंग एल्गोरिदम का इस्तेमाल करके कोड में बदला जाता है. इसके बाद, कोड में बदली गई वैल्यू का इस्तेमाल उपयोगकर्ता नाम के तौर पर किया जाता है. पासवर्ड को भी इसी एल्गोरिदम का इस्तेमाल करके कोड में बदला जाता है और इसका इस्तेमाल पासवर्ड के तौर पर किया जाता है.

GTAF जैसे कॉन्फ़िडेंशियल क्लाइंट को क्लाइंट क्रेडेंशियल जारी किए जाते हैं. ये टोकन एंडपॉइंट के लिए अनुरोध करते समय, कैरियर के OAuth सर्वर से पुष्टि करते हैं. क्लाइंट की पुष्टि करने की सुविधा का इस्तेमाल इन कामों के लिए किया जाता है: \

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

GTAF, टोकन एंडपॉइंट को अनुरोध भेजते समय, "client_id" अनुरोध पैरामीटर का इस्तेमाल करके खुद की पहचान करता है.

क्लाइंट क्रेडेंशियल को रोटेट करने की सुविधा खास तौर पर अहम है. OAuth सर्वर में, रोटेशन के दौरान क्रेडेंशियल के दो जोड़े एक साथ इस्तेमाल किए जा सकते हों. साथ ही, इसमें क्रेडेंशियल बंद करने की सुविधा भी होनी चाहिए. समय-समय पर पुष्टि से जुड़े क्रेडेंशियल बदलने की सामान्य प्रक्रिया में:

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

OAuth सर्वर, ऊपर दी गई रोटेशन प्रोसेस के साथ काम कर सकता हो.

टोकन एंडपॉइंट

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

टोकन एंडपॉइंट को कॉन्फ़िगर करते समय, इन बातों का ध्यान रखें:

• टोकन एंडपॉइंट की जगह की जानकारी, सेवा के दस्तावेज़ में दी जानी चाहिए.
• एंडपॉइंट यूआरआई में "application/x-www-form-urlencoded" फ़ॉर्मैट वाला क्वेरी कॉम्पोनेंट शामिल हो सकता है. अतिरिक्त क्वेरी पैरामीटर जोड़ते समय, इसे बनाए रखना ज़रूरी है. एंडपॉइंट यूआरआई में फ़्रैगमेंट कॉम्पोनेंट शामिल नहीं होना चाहिए.
• टोकन एंडपॉइंट पर किए गए अनुरोधों से, एचटीटीपी अनुरोध और जवाब में साफ़ तौर पर लिखे गए क्रेडेंशियल ट्रांसमिट होते हैं. इसलिए, कैरियर के OAuth सर्वर को टोकन एंडपॉइंट पर अनुरोध भेजने के लिए, टीएलएस का इस्तेमाल करना होगा.
• GTAF, ऐक्सेस टोकन का अनुरोध करते समय एचटीटीपी "POST" तरीके का इस्तेमाल करता है.
• बिना वैल्यू के भेजे गए पैरामीटर को अनुरोध से हटा दिया जाना चाहिए. OAuth सर्वर को, ऐसे अनुरोध पैरामीटर को अनदेखा करना चाहिए जिनकी पहचान नहीं हो पाई है. अनुरोध और जवाब के पैरामीटर को एक से ज़्यादा बार शामिल नहीं किया जाना चाहिए.
• GTAF सिर्फ़ बेयरर टाइप के ऐक्सेस टोकन के साथ काम करता है.

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

अनुमति और टोकन एंडपॉइंट की मदद से क्लाइंट, "scope" अनुरोध पैरामीटर का इस्तेमाल करके, ऐक्सेस के अनुरोध का दायरा तय कर सकता है. इसके बाद, अनुमति देने वाला सर्वर "scope" रिस्पॉन्स पैरामीटर का इस्तेमाल करके, क्लाइंट को जारी किए गए ऐक्सेस टोकन के स्कोप के बारे में बताता है.

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

 scope = scope-token *( SP scope-token )
 scope-token = 1*( %x21 / %x23-5B / %x5D-7E )

GTAF को स्कोप लागू करने की ज़रूरत नहीं होती. हालांकि, यह सुविधा काम करती है. ज़्यादा जानकारी के लिए, RFC 6749 के सेक्शन 3.3 देखें.

ऐक्सेस टोकन जारी करना

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

जवाब मिल गया

जब GTAF कोई अनुरोध भेजता है, तो OAuth सर्वर एक ऐक्सेस टोकन और रीफ़्रेश टोकन (ज़रूरी नहीं) जारी करता है. साथ ही, 200 (OK) स्टेटस कोड के साथ एचटीटीपी रिस्पॉन्स के एंटिटी-बॉडी में ये पैरामीटर जोड़कर रिस्पॉन्स बनाता है: \

• access_token: ज़रूरी है. OAuth सर्वर से जारी किया गया ऐक्सेस टोकन. GTAF को उम्मीद है कि टोकन एंडपॉइंट, बियरर टोकन देगा.
• expires_in: ज़रूरी है. ऐक्सेस टोकन की लाइफ़टाइम अवधि, सेकंड में. उदाहरण के लिए, "3600" वैल्यू से पता चलता है कि ऐक्सेस टोकन, रिस्पॉन्स जनरेट होने के एक घंटे बाद खत्म हो जाएगा. अगर इसे शामिल नहीं किया जाता है, तो OAuth सर्वर को किसी अन्य तरीके से समयसीमा खत्म होने का समय बताना चाहिए या डिफ़ॉल्ट वैल्यू को दस्तावेज़ में शामिल करना चाहिए.
• token_type: ज़रूरी है. जारी किया गया टोकन किस तरह का है. अलग-अलग तरह के टोकन के बारे में ज़्यादा जानकारी के लिए, आरएफ़सी 6749 के सेक्शन 7.1 पर जाएं. वैल्यू, केस-इनसेंसिटिव होती है. यह लेख लिखते समय, GTAF सिर्फ़ बेयरर टोकन के साथ काम करता है.
• refresh_token: OPTIONAL. रीफ़्रेश टोकन. इसका इस्तेमाल, उसी ऑथराइज़ेशन ग्रांट का इस्तेमाल करके नए ऐक्सेस टोकन पाने के लिए किया जा सकता है.
• स्कोप: अगर इसे लागू किया गया है और यह GTAF के अनुरोध किए गए स्कोप के जैसा है, तो यह ज़रूरी नहीं है. हालांकि, अगर ऐसा नहीं है, तो यह ज़रूरी है.

इन पैरामीटर को "application/json" का इस्तेमाल करके, एचटीटीपी रिस्पॉन्स की इकाई-बॉडी में शामिल किया जाता है. पैरामीटर को JavaScript Object Notation (JSON) स्ट्रक्चर में क्रम से लगाया जाता है. इसके लिए, हर पैरामीटर को सबसे ऊपर के स्ट्रक्चर लेवल पर जोड़ा जाता है. पैरामीटर के नाम और स्ट्रिंग वैल्यू को JSON स्ट्रिंग के तौर पर शामिल किया जाता है. संख्यात्मक वैल्यू को JSON नंबर के तौर पर शामिल किया जाता है. पैरामीटर का क्रम मायने नहीं रखता और यह अलग-अलग हो सकता है.

पुष्टि करने वाले सर्वर को, टोकन, क्रेडेंशियल या अन्य संवेदनशील जानकारी वाले किसी भी जवाब में, एचटीटीपी "Cache-Control" रिस्पॉन्स हेडर फ़ील्ड को "no-store" वैल्यू के साथ शामिल करना होगा. साथ ही, "Pragma" रिस्पॉन्स हेडर फ़ील्ड को "no-cache" वैल्यू के साथ शामिल करना होगा.

उदाहरण के लिए:

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"Bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

यहां कुछ ज़रूरी बातें बताई गई हैं:

• GTAF, रिस्पॉन्स में मौजूद उन वैल्यू के नामों को अनदेखा करता है जिनकी पहचान नहीं हुई है.
• OAuth सर्वर से मिले टोकन और अन्य वैल्यू के साइज़ तय नहीं किए गए हैं.
• GTAF को वैल्यू के साइज़ के बारे में अनुमान लगाने से बचना चाहिए. OAuth सर्वर को, जारी की गई किसी भी वैल्यू के साइज़ के बारे में जानकारी देनी चाहिए.

गड़बड़ी वाला जवाब

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

GTAF में अनुमति देना

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

GTAF, client_credentials ग्रांट टाइप का इस्तेमाल करता है. client_credentials ग्रांट टाइप में, GTAF, एचटीटीपी पोस्ट अनुरोध और एचटीटीपी बेसिक पुष्टि का इस्तेमाल करके टोकन का अनुरोध करता है. सभी अनुरोध टीएलएस (यानी, एचटीटीपीएस) का इस्तेमाल करता है. साथ ही, GTAF किसी मान्य टीएलएस सर्टिफ़िकेट के बिना, OAuth सर्वर के साथ इंटिग्रेट नहीं हो सकता. GTAF, कॉन्फ़िगर किए जा सकने वाले टोकन स्कोप को पास कर सकता है. अगर कोई स्कोप कॉन्फ़िगर नहीं किया गया है, तो यह खाली स्कोप पास करेगा.

GTAF को उम्मीद है कि ऐक्सेस टोकन के साथ "expires_in" वैल्यू (लाइफ़टाइम) भी दिखाई जाएगी. expires_in की वैल्यू कम से कम 900 सेकंड होनी चाहिए. साथ ही, यह कुछ घंटों से ज़्यादा नहीं होनी चाहिए. नए टोकन का अनुरोध करने से, मौजूदा टोकन की समयसीमा पहले खत्म नहीं होनी चाहिए.

अलग-अलग तरह के ग्रांट के बारे में ज़्यादा जानने के लिए, RFC 6749 के सेक्शन 1.3 देखें.

अनुरोध और जवाब का उदाहरण

मान लें कि GTAF में OAuth सर्वर के लिए यह कॉन्फ़िगरेशन है:

URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa

ध्यान दें: असली डीपीए के लिए क्लाइंट सीक्रेट, उदाहरण में दिखाए गए क्लाइंट सीक्रेट से ज़्यादा सुरक्षित होना चाहिए.

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

$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==

इसके बाद, GTAF इन क्रेडेंशियल, client_credentials grant type, और कॉन्फ़िगर किए गए स्कोप का इस्तेमाल करके, OAuth सर्वर को एचटीटीपीएस पोस्ट अनुरोध करता है. उदाहरण के लिए, GTAF का अनुरोध, इनसे जनरेट किए गए अनुरोध जैसा दिखता है:

$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'

GTAF इस्तेमाल करने वाले हेडर, curl से भेजे गए हेडर से मेल नहीं खाएंगे. हालांकि, अनुमति देने वाला हेडर एक जैसा होगा.

GTAF को इस फ़ॉर्म में जवाब चाहिए:

{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}

यहां एक मान्य जवाब का उदाहरण दिया गया है:

{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}

ध्यान दें: रिस्पॉन्स, मान्य JSON होना चाहिए.

गड़बड़ी के रिस्पॉन्स और कोड

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

उदाहरण के लिए: \

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }

GTAF को उम्मीद है कि OAuth सर्वर, गड़बड़ी के इन जवाबों के साथ काम करेगा:

गड़बड़ी कोड	जवाब	वजह
एचटीटीपी 400	invalid_request	अनुरोध में ज़रूरी पैरामीटर मौजूद नहीं है, इसमें grant type के अलावा कोई ऐसी पैरामीटर वैल्यू शामिल है जिसका इस्तेमाल नहीं किया जा सकता, इसमें किसी पैरामीटर को दोहराया गया है, इसमें एक से ज़्यादा क्रेडेंशियल शामिल हैं, इसमें GTAF के साथ पुष्टि करने के लिए एक से ज़्यादा तरीकों का इस्तेमाल किया गया है या यह किसी और वजह से गलत है.
एचटीटीपी 401	invalid_client	क्लाइंट की पुष्टि नहीं हो सकी. जैसे, क्लाइंट के बारे में जानकारी नहीं है, क्लाइंट की पुष्टि शामिल नहीं है या पुष्टि करने का तरीका काम नहीं करता. OAuth सर्वर, एचटीटीपी 401 (अनऑथराइज़्ड) स्टेटस कोड दिखा सकता है. इससे यह पता चलता है कि एचटीटीपी की पुष्टि की कौनसी स्कीम इस्तेमाल की जा सकती हैं. अगर क्लाइंट ने "Authorization" अनुरोध हेडर फ़ील्ड के ज़रिए पुष्टि करने की कोशिश की है, तो OAuth सर्वर को एचटीटीपी 401 (अनुमति नहीं है) स्टेटस कोड के साथ जवाब देना होगा. साथ ही, इसमें "WWW-Authenticate" रिस्पॉन्स हेडर फ़ील्ड शामिल करना होगा. यह फ़ील्ड, क्लाइंट की ओर से इस्तेमाल की गई पुष्टि करने की स्कीम से मेल खाना चाहिए.
एचटीटीपी 500	OAuth सर्वर में गड़बड़ी

डीबग करने के लिए इस्तेमाल किए जा सकने वाले अन्य जवाबों के बारे में जानने के लिए, सेक्शन 5.2 देखें. यह RFC 6749 में दिया गया है.