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

संबंधित दस्तावेज़

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

खास जानकारी

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

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

नीचे दिए गए आंकड़ों से जानकारी को बेहतर तरीके से समझा जा सकता है:

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

ऐक्सेस टोकन

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

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

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

क्लाइंट प्रमाणीकरण

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

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

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

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

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

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

OAuth सर्वर ऊपर दी गई रोटेशन प्रक्रिया के साथ काम करने लायक होना चाहिए.

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

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

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

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

ऐक्सेस टोकन का दायरा

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

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

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

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

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

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

सफल जवाब

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

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

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

ऑथराइज़ेशन सर्वर में, एचटीटीपी और कोट;कैश-कंट्रोल" की रिस्पॉन्स हेडर फ़ील्ड में "no-store" की वैल्यू के साथ-साथ टोकन, क्रेडेंशियल या अन्य संवेदनशील जानकारी, और "नो-कैश और कोट की वैल्यू के साथ "ग्रेस और कोट; फ़ील्ड शामिल होना चाहिए.

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

     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 (गलत अनुरोध) स्टेटस कोड (जब तक अलग से निर्देश न दिया गया हो) देना चाहिए. साथ ही, उसमें गड़बड़ी का जवाब और कोड वाले सेक्शन में दिया गया कम से कम एक पैरामीटर शामिल होना चाहिए.

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

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

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

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

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

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

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

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

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

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

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

इसके बाद, GTAF, इन सर्वर, Client_credentials अनुदान टाइप, और कॉन्फ़िगर किए गए दायरे का इस्तेमाल करके, OAuth सर्वर पर एचटीटीपीएस पोस्ट अनुरोध करता है. उदाहरण के लिए, GTAF's का अनुरोध नीचे दिए गए अनुरोध से मिलता-जुलता है:

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

GTAF के इस्तेमाल किए गए हेडर, कर्ल से भेजे गए हेडर से मेल नहीं खाएंगे. हालांकि, ऑथराइज़ेशन हेडर एक जैसा होगा.

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	अमान्य_अनुरोध	अनुरोध में एक ज़रूरी पैरामीटर मौजूद नहीं है, जिसमें सही पैरामीटर वैल्यू शामिल नहीं की गई है (अनुमति देने के प्रकार के अलावा), कोई पैरामीटर दोहराया जाता है, एक से ज़्यादा क्रेडेंशियल शामिल किए जाते हैं, GTAF के ज़रिए पुष्टि करने के लिए एक से ज़्यादा तरीकों का इस्तेमाल किया जाता है या गलत तरीके से काम करता है.
एचटीटीपी 401	अमान्य_क्लाइंट	क्लाइंट की पुष्टि नहीं हो सकी (उदाहरण के लिए, अज्ञात क्लाइंट, कोई क्लाइंट पुष्टि शामिल नहीं है या पुष्टि करने का कोई तरीका काम नहीं करता). OAuth सर्वर, एचटीटीपी 401 (बिना अनुमति वाला) स्टेटस कोड दिखा सकता है. इससे यह पता चलता है कि कौनसी एचटीटीपी पुष्टि करने की स्कीम इस्तेमाल की जा सकती हैं. अगर क्लाइंट ने "Authority" अनुरोध हेडर फ़ील्ड के ज़रिए पुष्टि करने की कोशिश की है, तो OAuth सर्वर को एक एचटीटीपी 401 (बिना अनुमति वाला) स्थिति कोड के साथ जवाब देना चाहिए और उसमें क्लाइंट की इस्तेमाल की गई पुष्टि करने वाली स्कीम से "WWW-Auth" रिस्पॉन्स हेडर फ़ील्ड शामिल करना चाहिए.
एचटीटीपी 500	OAuth सर्वर काम नहीं कर रहा

डीबग करने में इस्तेमाल किए जा सकने वाले दूसरे जवाबों की जानकारी के लिए, आरएफ़सी 6749 का सेक्शन 5.2 देखें.