सर्वर से सर्वर ऐप्लिकेशन के लिए OAuth 2.0 का उपयोग करना

आपको मेरी यह बात गाँठ बाँध लेनी चाहिए कि आप क्रिएटर हैं, इसलिए आप एक आर्टिस्ट हैं और आर्टिस्ट को इंस्पायर्ड होना चाहिए.

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

आम तौर पर, जब किसी ऐप्लिकेशन में उपयोगकर्ता के डेटा के बजाय Google API का इस्तेमाल किया जाता है, तो सेवा खाते का इस्तेमाल किया जाता है. उदाहरण के लिए, अगर ऐप्लिकेशन ऐसे ऐप्लिकेशन का इस्तेमाल करता है जिनमें डेटा परसिस्टेंस के लिए Google Cloud Datastore का इस्तेमाल किया जाता है, तो Google Cloud Datastore API के लिए अपने कॉल की पुष्टि करने के लिए, सेवा खाते का इस्तेमाल किया जाएगा.

Google Workspace डोमेन के एडमिन, डोमेन के उपयोगकर्ताओं की ओर से, उपयोगकर्ता के डेटा को ऐक्सेस करने के लिए, सेवा खातों के लिए पूरे डोमेन का अधिकार भी दे सकते हैं.

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

खास जानकारी

सर्वर-टू-सर्वर इंटरैक्शन की सुविधा देने के लिए, पहले API Consoleमें अपने प्रोजेक्ट के लिए सेवा खाता बनाएं. अगर आपको अपने Google Workspace खाते के उपयोगकर्ताओं का डेटा ऐक्सेस करना है, तो कृपया पूरे डोमेन के लिए सेवा खाते का ऐक्सेस दें.

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

आखिर में, आपका ऐप्लिकेशन Google API को कॉल करने के लिए, ऐक्सेस टोकन का इस्तेमाल कर सकता है.

सेवा खाता बनाया जा रहा है

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

जब आपका ऐप्लिकेशन Google App Engine पर चलता है, तो अपना प्रोजेक्ट बनाते समय सेवा खाता अपने-आप सेट अप हो जाता है.

जब आपका ऐप्लिकेशन Google Compute Engine पर चलता है, तो प्रोजेक्ट बनाते समय एक सेवा खाता अपने-आप सेट अप हो जाता है. हालांकि, आपको यह तय करना होता है कि Google Compute Engine इंस्टेंस बनाते समय, आपके ऐप्लिकेशन को किन ऐप्लिकेशन का ऐक्सेस चाहिए. ज़्यादा जानकारी के लिए, सेवा खातों का इस्तेमाल करने के लिए इंस्टेंस तैयार करना देखें.

अगर आपका ऐप्लिकेशन Google App Engine या Google Compute Engine पर नहीं चलता है, तो आपको Google API Consoleमें ये क्रेडेंशियल पाने होंगे. सेवा-खाते के क्रेडेंशियल जनरेट करने के लिए या पहले से जनरेट किए गए सार्वजनिक क्रेडेंशियल देखने के लिए, ये काम करें:

सबसे पहले, एक सेवा खाता बनाएँ:

  1. Service accounts pageखोलें।
  2. If prompted, select a project, or create a new one.
  3. क्रिएट सर्विस अकाउंट पर क्लिक करें।
  4. सेवा खाते के विवरण के तहत, सेवा खाते के लिए एक नाम, आईडी और विवरण टाइप करें, फिर बनाएं और जारी रखें पर क्लिक करें।
  5. वैकल्पिक: इस सेवा खाते को प्रोजेक्ट तक पहुंच प्रदान करें के अंतर्गत, सेवा खाते को प्रदान करने के लिए IAM भूमिकाएं चुनें.
  6. जारी रखें पर क्लिक करें।
  7. वैकल्पिक: उपयोगकर्ताओं को इस सेवा खाते तक पहुंच प्रदान करें के तहत, उन उपयोगकर्ताओं या समूहों को जोड़ें जिन्हें सेवा खाते का उपयोग और प्रबंधन करने की अनुमति है।
  8. हो गया क्लिक करें.

अगला, एक सेवा खाता कुंजी बनाएँ:

  1. आपके द्वारा बनाए गए सेवा खाते के ईमेल पते पर क्लिक करें।
  2. कुंजी टैब पर क्लिक करें।
  3. कुंजी जोड़ें ड्रॉप-डाउन सूची में, नई कुंजी बनाएं चुनें.
  4. क्रिएट पर क्लिक करें ।

आपकी नई सार्वजनिक/निजी कुंजी जोड़ी तैयार की जाती है और आपकी मशीन पर डाउनलोड की जाती है; यह निजी कुंजी की एकमात्र प्रति के रूप में कार्य करता है। आप इसे सुरक्षित रूप से संग्रहीत करने के लिए जिम्मेदार हैं। यदि आप इस कुंजी जोड़ी को खो देते हैं, तो आपको एक नया बनाना होगा।

आप जब चाहें, API Console पर जाकर, ईमेल पता, सार्वजनिक कुंजी के फ़िंगरप्रिंट, और दूसरी जानकारी देख सकते हैं. इसके अलावा, सार्वजनिक/निजी कुंजी के दूसरे जोड़े भी जनरेट कर सकते हैं. API Consoleमें सेवा खाते के क्रेडेंशियल के बारे में ज़्यादा जानने के लिए, API Consoleसहायता फ़ाइल में सेवा खाते देखें.

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

पूरे डोमेन के लिए सेवा खाते का ऐक्सेस देना

Google Workspace खाते का इस्तेमाल करके, संगठन का Workspace एडमिन, Google Workspace डोमेन में उपयोगकर्ताओं की ओर से, Workspace के उपयोगकर्ता के डेटा को ऐक्सेस करने के लिए, ऐप्लिकेशन को अनुमति दे सकता है. उदाहरण के लिए, Google Workspace डोमेन के सभी उपयोगकर्ताओं के कैलेंडर में इवेंट जोड़ने के लिए, Google Calendar API का इस्तेमाल करने वाला ऐप्लिकेशन, सेवा खाते का इस्तेमाल करके उपयोगकर्ताओं की ओर से Google Calendar API ऐक्सेस करेगा. किसी डोमेन के उपयोगकर्ताओं की ओर से किसी डेटा को ऐक्सेस करने के लिए, सेवा खाते को अनुमति देना कभी-कभी इसे "पूरे डोमेन का अधिकार देना" कहा जाता है.

पूरे डोमेन के लिए किसी सेवा खाते को अनुमति देने के लिए, Google Workspace डोमेन के सुपर एडमिन को यह तरीका अपनाना होगा:

  1. अपने Google Workspace डोमेन के Admin console में जाकर, मुख्य मेन्यू > सुरक्षा > ऐक्सेस और डेटा कंट्रोल > एपीआई कंट्रोल पर जाएं.
  2. पूरे डोमेन पर ईमेल भेजना पैनल में, डोमेन वाइड डेलिगेशन मैनेज करें चुनें.
  3. नया जोड़ें पर क्लिक करें.
  4. Client-ID फ़ील्ड में, सेवा खाते का Client-ID डालें. आपको Service accounts pageमें, अपने सेवा खाते का क्लाइंट आईडी मिल सकता है.
  5. OAuth के दायरे (कॉमा से अलग किए गए) फ़ील्ड में, उन दायरों की सूची डालें जिन्हें आपके ऐप्लिकेशन को ऐक्सेस देना है. उदाहरण के लिए, अगर आपके ऐप्लिकेशन को Google Drive API और Google Calendar API का पूरा ऐक्सेस चाहिए, तो https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar पर जाएं.
  6. अनुमति दें पर क्लिक करें.

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

डेलिगेट एपीआई कॉल करने की तैयारी करना

Java

API Consoleसे क्लाइंट ईमेल पता और निजी कुंजी मिलने के बाद, सेवा खाते के क्रेडेंशियल और उन स्कोप से GoogleCredential ऑब्जेक्ट बनाने के लिए, Java के लिए Google API क्लाइंट लाइब्रेरी का इस्तेमाल करें जिनका आपके ऐप्लिकेशन को ऐक्सेस चाहिए. उदाहरण के लिए:

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

अगर आप Google Cloud Platform पर कोई ऐप्लिकेशन डेवलप कर रहे हैं, तो इसके बजाय ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल का इस्तेमाल कर सकते हैं. इससे प्रोसेस आसान हो सकती है.

पूरे डोमेन के लिए डेलिगेट करना

अगर आपने सेवा खाते को डोमेन के लिए ऐक्सेस दिया है और आपको किसी उपयोगकर्ता खाते का डुप्लीकेट बनाना है, तो GoogleCredential ऑब्जेक्ट के createDelegated तरीके के साथ, उपयोगकर्ता खाते का ईमेल पता बताएं. उदाहरण के लिए:

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("workspace-user@example.com");

ऊपर दिया गया कोड अपने createDelegated() तरीके को कॉल करने के लिए, GoogleCredential ऑब्जेक्ट का इस्तेमाल करता है. createDelegated() तरीके का आर्ग्युमेंट, आपके Workspace खाते से जुड़ा कोई उपयोगकर्ता होना चाहिए. अनुरोध करने वाला आपका कोड, इस क्रेडेंशियल का इस्तेमाल करके, आपके सेवा खाते का इस्तेमाल करके Google API को कॉल करेगा.

Python

API Consoleसे क्लाइंट का ईमेल पता और निजी कुंजी मिलने के बाद, Python के लिए Google API क्लाइंट लाइब्रेरी का इस्तेमाल करके, यह तरीका अपनाएं:

  1. सेवा खाते के क्रेडेंशियल और उन दायरों से Credentials ऑब्जेक्ट बनाएं, जिन्हें आपके ऐप्लिकेशन को ऐक्सेस करने की ज़रूरत है. उदाहरण के लिए: 
    from google.oauth2 import service_account

SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
SERVICE_ACCOUNT_FILE = '/path/to/service.json'

credentials = service_account.Credentials.from_service_account_file(
        SERVICE_ACCOUNT_FILE, scopes=SCOPES)

    अगर आप Google Cloud Platform पर कोई ऐप्लिकेशन डेवलप कर रहे हैं, तो इसके बजाय ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल का इस्तेमाल कर सकते हैं. इससे प्रोसेस आसान हो सकती है.

  2. पूरे डोमेन के लिए डेलिगेट करना

    अगर आपने सेवा खाते को पूरे डोमेन के लिए ऐक्सेस दिया है और आपको किसी उपयोगकर्ता खाते का डुप्लीकेट बनाना है, तो मौजूदा ServiceAccountCredentials ऑब्जेक्ट के लिए, with_subject तरीके का इस्तेमाल करें. उदाहरण के लिए:

    delegated_credentials = credentials.with_subject('user@example.org')

अपने ऐप्लिकेशन में Google API को कॉल करने के लिए, क्रेडेंशियल ऑब्जेक्ट का इस्तेमाल करें.

एचटीटीपी/REST

API Consoleसे Client-ID और निजी कुंजी पाने के बाद, आपके आवेदन को ये चरण पूरे करने होंगे:

  1. JSON वेब टोकन (JWT), (उच्चारण), "jot") बनाएं. इसमें हेडर, दावा सेट, और हस्ताक्षर शामिल होता है.
  2. Google OAuth 2.0 के ऑथराइज़ेशन सर्वर से ऐक्सेस टोकन का अनुरोध करें.
  3. वह JSON रिस्पॉन्स मैनेज करें जो ऑथराइज़ेशन सर्वर दिखाता है.

नीचे दिए गए सेक्शन में बताया गया है कि इन चरणों को कैसे पूरा करना है.

अगर रिस्पॉन्स में ऐक्सेस टोकन शामिल होता है, तो Google API को कॉल करने के लिए, ऐक्सेस टोकन का इस्तेमाल किया जा सकता है. (अगर जवाब में ऐक्सेस टोकन शामिल नहीं है, तो हो सकता है कि आपका JWT और टोकन अनुरोध सही तरीके से न बनाया गया हो. इसके अलावा, यह भी हो सकता है कि सेवा खाते के पास अनुरोध किए गए स्कोप को ऐक्सेस करने की अनुमति न हो.)

जब ऐक्सेस टोकन की समयसीमा खत्म हो जाती है, तो आपका ऐप्लिकेशन एक अन्य JWT जनरेट करता है, उस पर हस्ताक्षर करता है, और दूसरे ऐक्सेस टोकन का अनुरोध करता है.

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

इस सेक्शन के बाकी हिस्सों में, JWT बनाने, JWT पर हस्ताक्षर करने, ऐक्सेस टोकन का अनुरोध करने, और रिस्पॉन्स को मैनेज करने की खास बातें बताई गई हैं.

JWT बनाना

JWT में तीन हिस्से होते हैं: हेडर, दावा सेट, और हस्ताक्षर. हेडर और दावे का सेट, JSON ऑब्जेक्ट हैं. इन JSON ऑब्जेक्ट को UTF-8 बाइट के हिसाब से बांटा जाता है. इसके बाद, Base64url एन्कोडिंग का इस्तेमाल करके इन्हें कोड में बदला जाता है. इस एन्कोडिंग से, बार-बार कोड में बदलने की प्रोसेस की वजह से, एन्कोडिंग में बदलाव होता है. हेडर, दावे का सेट, और हस्ताक्षर में पीरियड (.) का वर्ण जोड़ा जाता है.

JWT इस तरह से तैयार की जाती है:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

हस्ताक्षर के लिए बेस स्ट्रिंग कुछ इस तरह होती है:

{Base64url encoded header}.{Base64url encoded claim set}
JWT का हेडर बनाना

हेडर में तीन फ़ील्ड होते हैं जिनसे हस्ताक्षर का एल्गोरिदम, दावे का फ़ॉर्मैट, और [सेवा खाते की कुंजी का कुंजी आईडी](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) दिखती है, जिसका इस्तेमाल JWT पर हस्ताक्षर करने के लिए किया गया था. एल्गोरिदम और फ़ॉर्मैट ज़रूरी है. हर फ़ील्ड में सिर्फ़ एक वैल्यू होती है. जैसे-जैसे ज़्यादा एल्गोरिदम और फ़ॉर्मैट के बारे में जानकारी मिलेगी, यह हेडर ज़रूरत के मुताबिक बदल जाएगा. कुंजी आईडी ज़रूरी नहीं है. Google के पास यह अधिकार है कि वह आने वाले समय में, गलत कुंजी आईडी वाले टोकन को अस्वीकार कर सकता है.

सेवा खाते, आरएसए SHA-256 एल्गोरिदम और JWT टोकन फ़ॉर्मैट पर निर्भर करते हैं. इस वजह से, हेडर को JSON के तौर पर दिखाया जा सकता है:

{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

इस तरह के Base64url को दिखाते हैं:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=
JWT पर किया जाने वाला दावा सेट करना

JWT के दावा सेट में, JWT के बारे में जानकारी होती है. इसमें, अनुरोध की गई अनुमतियां (दायरे), टोकन का टारगेट, जारी करने वाले का समय, और टोकन की लाइफ़ शामिल होती है. ज़्यादातर फ़ील्ड ज़रूरी हैं. JWT हेडर की तरह, JWT दावा सेट भी एक JSON ऑब्जेक्ट है. इसका इस्तेमाल, सिग्नेचर की गिनती में किया जाता है.

ज़रूरी दावे

JWT में होने वाले दावे के सेट में किए गए ज़रूरी दावे, नीचे दिखाए गए हैं. वे दावे के सेट में किसी भी क्रम में दिख सकते हैं.

नाम ब्यौरा
iss सेवा खाते का ईमेल पता.
scope ऐप्लिकेशन के लिए मांगी गई अनुमतियों के बीच की खाली जगह की सूची.
aud दावे के सही टारगेट का ब्यौरा. ऐक्सेस टोकन का इस्तेमाल करते समय, यह वैल्यू हमेशा https://oauth2.googleapis.com/token होती है.
exp इस दावे के लागू होने की समयसीमा, 00:00:00 यूटीसी से सेकंड के तौर पर बताई गई है, 1 जनवरी, 1970. इस वैल्यू को, जारी किए गए समय के बाद ज़्यादा से ज़्यादा एक घंटा हो सकता है.
iat दावा जारी किए जाने का समय, 1 जनवरी, 1970 को 00:00:00 यूटीसी से सेकंड के रूप में बताया गया.

JWT के दावा सेट में ज़रूरी फ़ील्ड को JSON के तौर पर दिखाया जाता है:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
अन्य दावे

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

किसी ऐक्सेस टोकन को ऐक्सेस करने वाले ऐक्सेस टोकन के लिए, रिसॉर्स में JWT के दावे का वह ईमेल पता डालें जो sub फ़ील्ड की वैल्यू के तौर पर सेट किया गया हो.

नाम ब्यौरा
sub उस उपयोगकर्ता का ईमेल पता जिसके लिए ऐप्लिकेशन, ऐक्सेस देने के लिए अनुरोध कर रहा है.

अगर किसी ऐप्लिकेशन के पास किसी उपयोगकर्ता के नाम पर काम करने की अनुमति नहीं है, तो ऐक्सेस टोकन अनुरोध का जवाब sub फ़ील्ड के साथ गड़बड़ी होगा.

JWT के ऐसे दावा सेट का उदाहरण जिसमें sub फ़ील्ड शामिल है:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "sub": "some.user@example.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
JWT के दावे के सेट को कोड में बदला जा रहा है

JWT हेडर की तरह, JWT का दावा सेट UTF-8 और Base64url-सुरक्षित कोड में बदला जाना चाहिए. यहां JWT में किए गए दावे के सेट के JSON को दिखाने का एक उदाहरण दिया गया है:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
हस्ताक्षर का पता लगाना

JSON वेब सिग्नेचर (JWS) वह खास जानकारी है जो JWT के लिए, हस्ताक्षर जनरेट करने की प्रोसेस को गाइड करती है. हस्ताक्षर के लिए इनपुट, इस कॉन्टेंट की बाइट ऐरे है:

{Base64url encoded header}.{Base64url encoded claim set}

हस्ताक्षर की गणना करते समय, JWT हेडर में साइनिंग एल्गोरिदम का इस्तेमाल करना ज़रूरी है. Google OAuth 2.0 के ऑथराइज़ेशन सर्वर पर काम करने वाला सिर्फ़ साइनिंग एल्गोरिदम ही SHA-256 हैशिंग एल्गोरिदम का इस्तेमाल करने वाला आरएसए है. इसे JWT के हेडर में alg फ़ील्ड में RS256 के तौर पर दिखाया जाता है.

Google API Consoleसे मिली निजी कुंजी का इस्तेमाल करके, SHA256withRSA (जिसे SHA-SA-XXXX1-V1_5-SIGN भी कहा जाता है और SHA-256 हैश फ़ंक्शन भी कहा जाता है) का इस्तेमाल करके, इनपुट के UTF-8 पर हस्ताक्षर करें. आउटपुट, बाइट की कैटगरी के तौर पर होगा.

हस्ताक्षर को Base64url में एन्कोड किया जाना चाहिए. हेडर, दावे का सेट, और हस्ताक्षर में पीरियड (.) वर्ण का एक साथ जुड़ जाता है. ऐसा करने पर, JWT डाउनलोड हो जाएगी. यह नीचे दिया गया होना चाहिए (साफ़ तौर पर जानकारी देने के लिए, लाइन ब्रेक जोड़े गए):

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

यहां Base64url एन्कोडिंग से पहले JWT का एक उदाहरण दिया गया है:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

यहां ऐसे JWT का उदाहरण दिया गया है जिसे हस्ताक्षर करके, ट्रांसमिशन के लिए तैयार किया गया है:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

ऐक्सेस टोकन के लिए अनुरोध करना

साइन किया गया JWT जनरेट करने के बाद, ऐप्लिकेशन उसका इस्तेमाल करके ऐक्सेस टोकन का अनुरोध कर सकता है. यह ऐक्सेस टोकन का अनुरोध, एचटीटीपीएस POST का अनुरोध है और मुख्य हिस्से को यूआरएल के कोड में बदला गया है. यूआरएल नीचे दिखाया गया है:

https://oauth2.googleapis.com/token

एचटीटीपीएस POST के अनुरोध में ये पैरामीटर ज़रूरी हैं:

नाम ब्यौरा
grant_type ज़रूरत के हिसाब से, नीचे दी गई स्ट्रिंग, यूआरएल के कोड में बदले गए का इस्तेमाल करें: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion JWT, जिसमें हस्ताक्षर भी शामिल है.

नीचे, ऐक्सेस टोकन के लिए किए गए अनुरोध में इस्तेमाल किए गए एचटीटीपीएस POST के अनुरोध की जानकारी दी गई है:

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

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

curl को इस्तेमाल करने वाला वही अनुरोध नीचे दिया गया है:

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

रिस्पॉन्स को हैंडल करना

अगर JWT और ऐक्सेस टोकन के लिए अनुरोध सही तरीके से बनाए गए हैं और सेवा खाते को कार्रवाई करने की अनुमति है, तो अनुमति देने वाले सर्वर से मिले JSON के रिस्पॉन्स में, ऐक्सेस टोकन शामिल होता है. जवाब का एक उदाहरण नीचे दिया गया है:

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

ऐक्सेस टोकन का इस्तेमाल expires_in वैल्यू के हिसाब से तय की गई अवधि के दौरान फिर से किया जा सकता है.

Google API को कॉल किया जा रहा है

Java

Google के ऑब्जेक्ट को कॉल करने के लिए, GoogleCredential ऑब्जेक्ट का इस्तेमाल करें. इसके लिए, यह तरीका अपनाएं:

  1. एपीआई के लिए सेवा ऑब्जेक्ट बनाएं, जिसे आप GoogleCredential ऑब्जेक्ट का इस्तेमाल करके कॉल करना चाहते हैं. उदाहरण के लिए: 
    SQLAdmin sqladmin =
    new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
  2. एपीआई सेवा के लिए सेवा ऑब्जेक्ट से मिले इंटरफ़ेस का इस्तेमाल करके अनुरोध करें. उदाहरण के लिए, example-123 के रोमांचक प्रोजेक्ट में Cloud SQL डेटाबेस के इंस्टेंस की सूची बनाने के लिए: 
    SQLAdmin.Instances.List instances =
    sqladmin.instances().list("exciting-example-123").execute();

Python

इन चरणों को पूरा करके, Google API को कॉल करने के लिए Credentials ऑब्जेक्ट का इस्तेमाल करें:

  1. जिस एपीआई को कॉल करना है उसके लिए सेवा ऑब्जेक्ट बनाएं. आप build फ़ंक्शन को कॉल करके, एपीआई के नाम और वर्शन के साथ-साथ, अनुमति वाले Credentials ऑब्जेक्ट को जोड़कर सेवा ऑब्जेक्ट बनाते हैं. उदाहरण के लिए, Cloud SQL एडमिन एपीआई के वर्शन 1beta3 को कॉल करने के लिए: 
    import googleapiclient.discovery

sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
  2. एपीआई सेवा के लिए सेवा ऑब्जेक्ट से मिले इंटरफ़ेस का इस्तेमाल करके अनुरोध करें. उदाहरण के लिए, example-123 के रोमांचक प्रोजेक्ट में Cloud SQL डेटाबेस के इंस्टेंस की सूची बनाने के लिए: 
    response = sqladmin.instances().list(project='exciting-example-123').execute()

एचटीटीपी/REST

जब आपका ऐप्लिकेशन ऐक्सेस टोकन हासिल कर लेता है, तब टोकन का इस्तेमाल करके किसी दिए गए सेवा खाते या उपयोगकर्ता खाते की ओर से Google API को कॉल किया जा सकता है. ऐसा तब भी किया जा सकता है, जब एपीआई के लिए ज़रूरी दायरे का ऐक्सेस दिया गया हो. ऐसा करने के लिए, एपीआई में ऐक्सेस टोकन शामिल करके access_token क्वेरी पैरामीटर या Authorization एचटीटीपी हेडर Bearer की वैल्यू शामिल करें. जब संभव हो, तो एचटीटीपी हेडर को प्राथमिकता दी जाती है, क्योंकि सर्वर लॉग में क्वेरी स्ट्रिंग दिखती हैं. ज़्यादातर मामलों में, Google API पर अपने कॉल सेट अप करने के लिए क्लाइंट लाइब्रेरी का इस्तेमाल किया जा सकता है (उदाहरण के लिए, Drive Files API पर कॉल करते समय).

OAuth 2.0 Playground में, सभी Google API को आज़माया जा सकता है और उनके दायरे देखे जा सकते हैं.

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

drive.files एंडपॉइंट (Drive Files API) के लिए, Authorization: Bearer एचटीटीपी हेडर का इस्तेमाल करने वाला कॉल कुछ ऐसा दिख सकता है. ध्यान दें कि आपको अपना ऐक्सेस टोकन तय करना होगा:

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 OAuth 2.0 के ऑथराइज़ेशन सर्वर से जारी किए गए ऐक्सेस टोकन, expires_in की वैल्यू के बाद खत्म हो जाते हैं. जब ऐक्सेस टोकन खत्म हो जाता है, तो ऐप्लिकेशन को एक और JWT जनरेट करना चाहिए, उस पर हस्ताक्षर करना चाहिए, और दूसरे ऐक्सेस टोकन के लिए अनुरोध करना चाहिए.

JWT में गड़बड़ी कोड

error फ़ील्ड error_description फ़ील्ड मतलब समस्या ठीक करने का तरीका
unauthorized_client Unauthorized client or scope in request. अगर पूरे डोमेन के लिए ऐक्सेस देने की सुविधा इस्तेमाल करने की कोशिश की जा रही है, तो उपयोगकर्ता के डोमेन के Admin console में, सेवा खाते को अनुमति नहीं दी गई है.

पक्का करें कि सेवा खाते को, sub दावे (फ़ील्ड) में उपयोगकर्ता के लिए, Admin console के पूरे डोमेन पर सौंपना पेज से अनुमति दी गई हो.

आम तौर पर, यह प्रक्रिया कुछ मिनट में पूरी हो जाती है. हालांकि, आपके Google खाते में, सभी उपयोगकर्ताओं तक पहुंचने में 24 घंटे लग सकते हैं.
unauthorized_client Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested. Admin console में क्लाइंट आईडी (अंकों में) के बजाय, क्लाइंट ईमेल पते का इस्तेमाल करके सेवा खाते को अनुमति दी गई. Admin console के डोमेन के सभी डोमेन के लिए पेज पर, क्लाइंट को हटाएं और संख्या वाले आईडी के साथ उसे फिर से जोड़ें.
access_denied (कोई भी मान) अगर पूरे डोमेन के लिए डेलिगेशन की सुविधा इस्तेमाल की जा रही है, तो अनुरोध किए गए एक या एक से ज़्यादा स्कोप, Admin console में मौजूद नहीं हैं.

पक्का करें कि सेवा खाते को, sub दावे (फ़ील्ड) में उपयोगकर्ता के लिए, Admin console के पूरे डोमेन पर सौंपना पेज पर अनुमति दी गई हो. साथ ही, इसमें वे सभी स्कोप शामिल हों जिनके लिए आपने अपने JWT के scope दावे में अनुरोध किया है.

आम तौर पर, यह प्रक्रिया कुछ मिनट में पूरी हो जाती है. हालांकि, आपके Google खाते में, सभी उपयोगकर्ताओं तक पहुंचने में 24 घंटे लग सकते हैं.
admin_policy_enforced (कोई भी मान) Google खाते के लिए, एक या एक से ज़्यादा दायरों को अनुमति नहीं मिली है.

Google Workspace एडमिन सहायता लेख कंट्रोल करें कि कौनसे तीसरे पक्ष और Google Workspace का डेटा Google Workspace के डेटा को ऐक्सेस कर सकते हैं. इससे आपको यह पता चलेगा कि एडमिन आपके OAuth क्लाइंट आईडी का ऐक्सेस दिए जाने तक, सभी स्कोप या संवेदनशील और पाबंदी वाले स्कोप के ऐक्सेस पर कैसे पाबंदी लगा सकता है.
invalid_client (कोई भी मान)

OAuth क्लाइंट या JWT टोकन अमान्य है या गलत तरीके से कॉन्फ़िगर किया गया है.

ज़्यादा जानकारी के लिए गड़बड़ी की जानकारी देखें.

पक्का करें कि JWT टोकन मान्य है और उसमें सही दावे किए गए हैं.

जांच लें कि OAuth क्लाइंट और सेवा खाता सही तरीके से कॉन्फ़िगर किया गया हो और आप सही ईमेल पते का इस्तेमाल कर रहे हों.

जांच लें कि JWT टोकन सही है या नहीं और अनुरोध में क्लाइंट आईडी के लिए जारी किया गया है.
invalid_grant Not a valid email. उपयोगकर्ता मौजूद नहीं है. जांच लें कि sub दावे (फ़ील्ड) में दिया गया ईमेल पता सही है.
invalid_grant

Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your 'iat' and 'exp' values and use a clock with skew to account for clock differences between systems.

 आम तौर पर, इसका मतलब यह है कि स्थानीय सिस्टम का समय सही नहीं है. ऐसा तब भी हो सकता है, जब आने वाले समय में iat की वैल्यू exp वैल्यू में 65 मिनट से ज़्यादा हो. इसके अलावा, exp वैल्यू iat वैल्यू से कम भी हो सकती है.

पक्का करें कि सिस्टम पर वह घड़ी सही है जहां JWT जनरेट की गई है. अगर ज़रूरी हो, तो अपना समय Google NTP के साथ सिंक करें.
invalid_grant Invalid JWT Signature.

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

इसके अलावा, JWT का दावा गलत तरीके से कोड में बदला जा सकता है - यह Base64 से कोड में बदला गया होना चाहिए, इसमें नई लाइनें या पैडिंग के बराबर चिह्न नहीं होने चाहिए.

JWT के दावे के सेट को डिकोड करें और पुष्टि करें कि दावे पर हस्ताक्षर करने वाली कुंजी, सेवा खाते से जुड़ी है.

Google की ओर से दी गई OAuth लाइब्रेरी का इस्तेमाल करके, यह पक्का करें कि JWT सही तरीके से जनरेट हुई है.

invalid_scope Invalid OAuth scope or ID token audience provided. किसी भी दायरे का अनुरोध नहीं किया गया है और दायरों की कोई सूची मौजूद नहीं है. इसके अलावा, आप जो अनुरोध कर सकते हैं वह मौजूद नहीं है, जैसे कि अमान्य.

पक्का करें कि JWT का scope दावा (फ़ील्ड) भरा गया है. साथ ही, उन दायरों की तुलना करें जो आपके एपीआई के दस्तावेज़ वाले दायरे से मेल खाते हैं. इससे यह पक्का किया जा सकेगा कि कोई गड़बड़ी या स्पेलिंग नहीं है.

ध्यान दें कि scope दावे में शामिल दायरों की सूची को कॉमा से नहीं, बल्कि स्पेस से अलग किया जाना चाहिए.
disabled_client The OAuth client was disabled. JWT के दावे पर हस्ताक्षर करने के लिए इस्तेमाल की गई कुंजी बंद है.

Google API Consoleपर जाएं और IAM और एडमिन > सेवा खाते में जाकर, उस सेवा खाते को चालू करें जिस पर "मुख्य आईडी" लिखा है, ताकि दावे पर हस्ताक्षर किए जा सकें.
org_internal This client is restricted to users within its organization. अनुरोध में मौजूद OAuth क्लाइंट आईडी, किसी खास Google Cloud संगठन में Google खातों का ऐक्सेस सीमित करने वाले एक प्रोजेक्ट का हिस्सा है.

पुष्टि करने के लिए, संगठन के सेवा खाते का इस्तेमाल करें. अपने OAuth ऐप्लिकेशन के लिए, उपयोगकर्ता टाइप कॉन्फ़िगरेशन की पुष्टि करें.

अतिरिक्त शर्तें: OAuth के बिना सेवा खाते को अनुमति देना

कुछ Google API में, हस्ताक्षर किए गए JWT का इस्तेमाल करके, OAuth 2.0 ऐक्सेस टोकन के बजाय, सीधे API (एपीआई) कॉल किए जा सकते हैं. अगर ऐसा हो सकता है, तो एपीआई कॉल करने से पहले, आपको Google के ऑथराइज़ेशन सर्वर पर नेटवर्क अनुरोध करने से बचना चाहिए.

जिस एपीआई को कॉल करना है उसकी सेवा की परिभाषा, Google API GitHub का डेटा स्टोर करने की जगह में पब्लिश की गई है. साथ ही, ऐक्सेस टोकन के बजाय JWT का इस्तेमाल करके, अनुमति वाले एपीआई कॉल किए जा सकते हैं. इसके लिए:

  1. ऊपर बताए गए तरीके से सेवा खाता बनाएं. खाता बनाते समय, आपको मिलने वाली JSON फ़ाइल को ज़रूर रखें.
  2. किसी भी सामान्य JWT लाइब्रेरी का इस्तेमाल करके, जैसे कि jwt.io पर मिलने वाली लाइब्रेरी इस्तेमाल करें. साथ ही, हेडर और पेलोड के साथ एक JWT बनाएं, जो इस तरह से दिखाया गया हो: 
    {
  "alg": "RS256",
  "typ": "JWT",
  "kid": "abcdef1234567890"
}
.
{
  "iss": "123456-compute@developer.gserviceaccount.com",
  "sub": "123456-compute@developer.gserviceaccount.com",
  "aud": "https://firestore.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600
}
    • हेडर में kid फ़ील्ड के लिए, अपने सेवा खाते का निजी कुंजी आईडी बताएं. आपको यह वैल्यू, सेवा खाते की JSON फ़ाइल के private_key_id फ़ील्ड में मिल सकती है.
    • iss और sub फ़ील्ड के लिए, अपने सेवा खाते का ईमेल पता बताएं. आपको यह वैल्यू, सेवा खाते की JSON फ़ाइल के client_email फ़ील्ड में मिल सकती है.
    • aud फ़ील्ड के लिए, एपीआई एंडपॉइंट को तय करें. उदाहरण के लिए: https://SERVICE.googleapis.com/.
    • iat फ़ील्ड के लिए, यूनिक्स का मौजूदा समय बताएं और exp फ़ील्ड के लिए, 3600 सेकंड बाद का समय बताएं, जब JWT खत्म होने वाली है.

अपने सेवा खाते की JSON फ़ाइल में मिली निजी कुंजी का इस्तेमाल करके, आरएसए-256 के साथ JWT पर साइन करें.

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

Java

google-api-java-client और java-jwt का इस्तेमाल करें:

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("123456-compute@developer.gserviceaccount.com")
        .withSubject("123456-compute@developer.gserviceaccount.com")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

Python

PyJWT का इस्तेमाल करके:

iat = time.time()
exp = iat + 3600
payload = {'iss': '123456-compute@developer.gserviceaccount.com',
           'sub': '123456-compute@developer.gserviceaccount.com',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')
  1. एपीआई में कॉल करें और साइन किए गए JWT को बेयर टोकन के तौर पर इस्तेमाल करें: 
    GET /v1/projects/abc/databases/123/indexes HTTP/1.1
Authorization: Bearer SIGNED_JWT
Host: firestore.googleapis.com