क्लाइंट-साइड वेब ऐप्लिकेशन के लिए OAuth 2.0

OAuth 2.0 एंडपॉइंट

https://accounts.google.com/o/oauth2/v2/auth पर मौजूद Google के OAuth 2.0 एंडपॉइंट से ऐक्सेस का अनुरोध करने के लिए, यूआरएल जनरेट करें. इस एंडपॉइंट को एचटीटीपीएस से ऐक्सेस किया जा सकता है; साधारण एचटीटीपी कनेक्शन स्वीकार नहीं किए जाते.

Google का ऑथराइज़ेशन सर्वर, वेब सर्वर ऐप्लिकेशन के लिए इन क्वेरी स्ट्रिंग पैरामीटर के साथ काम करता है:

Google के अनुमति देने वाले सर्वर पर रीडायरेक्ट करने का सैंपल

यहां एक यूआरएल का उदाहरण दिया गया है. इसमें, यूआरएल को आसानी से पढ़ने के लिए लाइन ब्रेक और स्पेस का इस्तेमाल किया गया है.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

अनुरोध का यूआरएल बनाने के बाद, उपयोगकर्ता को उस पर रीडायरेक्ट करें.

JavaScript का सैंपल कोड

यहां दिए गए JavaScript स्निपेट में, JavaScript के लिए Google APIs क्लाइंट लाइब्रेरी का इस्तेमाल किए बिना, JavaScript में अनुमति फ़्लो शुरू करने का तरीका बताया गया है. यह OAuth 2.0 एंडपॉइंट, क्रॉस-ऑरिजिन रिसॉर्स शेयरिंग (सीओआरएस) के साथ काम नहीं करता. इसलिए, स्निपेट एक फ़ॉर्म बनाता है, जो उस एंडपॉइंट के लिए अनुरोध खोलता है.

/*
 * Create form to request access token from Google's OAuth 2.0 server.
 */
function oauthSignIn() {
  // Google's OAuth 2.0 endpoint for requesting an access token
  var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

  // Create <form> element to submit parameters to OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'GET'); // Send as a GET request.
  form.setAttribute('action', oauth2Endpoint);

  // Parameters to pass to OAuth 2.0 endpoint.
  var params = {'client_id': 'YOUR_CLIENT_ID',
                'redirect_uri': 'YOUR_REDIRECT_URI',
                'response_type': 'token',
                'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly',
                'include_granted_scopes': 'true',
                'state': 'pass-through value'};

  // Add form parameters as hidden input values.
  for (var p in params) {
    var input = document.createElement('input');
    input.setAttribute('type', 'hidden');
    input.setAttribute('name', p);
    input.setAttribute('value', params[p]);
    form.appendChild(input);
  }

  // Add form to page and submit it to open the OAuth 2.0 endpoint.
  document.body.appendChild(form);
  form.submit();
}

OAuth 2.0 एंडपॉइंट

OAuth 2.0 सर्वर, आपके ऐक्सेस टोकन के अनुरोध में बताए गए redirect_uri को जवाब भेजता है.

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

• ऐक्सेस टोकन का रिस्पॉन्स:

  https://oauth2.example.com/callback#access_token=4/P7q7W91&token_type=Bearer&expires_in=3600

  फ़्रैगमेंट स्ट्रिंग में access_token पैरामीटर के अलावा, token_type पैरामीटर भी होता है. यह हमेशा Bearer पर सेट होता है. साथ ही, इसमें expires_in पैरामीटर भी होता है, जो सेकंड में टोकन के लाइफ़टाइम की जानकारी देता है. अगर ऐक्सेस टोकन के अनुरोध में state पैरामीटर तय किया गया था, तो उसकी वैल्यू भी जवाब में शामिल की जाती है.

• गड़बड़ी का जवाब:

  https://oauth2.example.com/callback#error=access_denied

OAuth 2.0 सर्वर रिस्पॉन्स का सैंपल

इस फ़्लो की जांच करने के लिए, यहां दिए गए सैंपल यूआरएल पर क्लिक करें. यह यूआरएल, आपके Google Drive में मौजूद फ़ाइलों का मेटाडेटा देखने के लिए, सिर्फ़ पढ़ने का ऐक्सेस और Google Calendar के इवेंट देखने के लिए, सिर्फ़ पढ़ने का ऐक्सेस मांगता है:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=https%3A//oauth2.example.com/code&
 client_id=client_id

OAuth 2.0 फ़्लो पूरा करने के बाद, आपको http://localhost/oauth2callback पर रीडायरेक्ट कर दिया जाएगा. उस यूआरएल पर, 404 NOT FOUND गड़बड़ी का मैसेज दिखेगा. ऐसा तब तक होगा, जब तक आपकी लोकल मशीन उस पते पर कोई फ़ाइल उपलब्ध नहीं कराती. अगले चरण में, उपयोगकर्ता को आपके ऐप्लिकेशन पर वापस रीडायरेक्ट किए जाने पर, यूआरआई में दी गई जानकारी के बारे में ज़्यादा जानकारी दी गई है.

OAuth 2.0 एंडपॉइंट

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

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

  {
    "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"
  }

OAuth 2.0 एंडपॉइंट

जब आपके ऐप्लिकेशन को ऐक्सेस टोकन मिल जाता है, तो किसी उपयोगकर्ता खाते की ओर से 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

JavaScript का सैंपल कोड

नीचे दिए गए कोड स्निपेट में, Google API को अनुरोध भेजने के लिए, सीओआरएस (क्रॉस-ऑरिजिन रिसॉर्स शेयरिंग) का इस्तेमाल करने का तरीका बताया गया है. इस उदाहरण में, JavaScript के लिए Google APIs क्लाइंट लाइब्रेरी का इस्तेमाल नहीं किया गया है. हालांकि, भले ही क्लाइंट लाइब्रेरी का इस्तेमाल न किया जा रहा हो, फिर भी उस लाइब्रेरी के दस्तावेज़ में मौजूद सीओआरएस सहायता गाइड से, आपको इन अनुरोधों को बेहतर तरीके से समझने में मदद मिलेगी.

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

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/drive/v3/about?fields=user&' +
    'access_token=' + params['access_token']);
xhr.onreadystatechange = function (e) {
  console.log(xhr.response);
};
xhr.send(null);

OAuth 2.0 एंडपॉइंट

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

OAuth 2.0 फ़्लो के लिए, पेज इन चरणों का पालन करता है:

1. यह उपयोगकर्ता को Google के OAuth 2.0 सर्वर पर रीडायरेक्ट करता है. यह सर्वर, https://www.googleapis.com/auth/drive.metadata.readonly और https://www.googleapis.com/auth/calendar.readonly के दायरों को ऐक्सेस करने का अनुरोध करता है.
2. अनुरोध किए गए एक या एक से ज़्यादा स्कोप का ऐक्सेस देने (या अस्वीकार करने) के बाद, उपयोगकर्ता को मूल पेज पर रीडायरेक्ट कर दिया जाता है. यह पेज, फ़्रैगमेंट आइडेंटिफ़ायर स्ट्रिंग से ऐक्सेस टोकन को पार्स करता है.
3. यह पेज यह जांच करता है कि उपयोगकर्ता ने ऐप्लिकेशन को किन दायरों का ऐक्सेस दिया है.

4. अगर उपयोगकर्ता ने अनुरोध किए गए स्कोप() का ऐक्सेस दिया है, तो पेज, सैंपल एपीआई अनुरोध करने के लिए ऐक्सेस टोकन का इस्तेमाल करता है.

   एपीआई अनुरोध, Drive API के about.get तरीके को कॉल करता है, ताकि अनुमति पा चुके उपयोगकर्ता के Google Drive खाते की जानकारी हासिल की जा सके.

5. अगर अनुरोध पूरा हो जाता है, तो ब्राउज़र के डिबगिंग कंसोल में एपीआई का जवाब लॉग किया जाता है.

अपने Google खाते के अनुमतियां पेज पर जाकर, ऐप्लिकेशन का ऐक्सेस वापस लिया जा सकता है. ऐप्लिकेशन को Google API दस्तावेज़ों के लिए OAuth 2.0 डेमो के तौर पर लिस्ट किया जाएगा.

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

<html><head></head><body>
<script>
  var YOUR_CLIENT_ID = 'REPLACE_THIS_VALUE';
  var YOUR_REDIRECT_URI = 'REPLACE_THIS_VALUE';

  // Parse query string to see if page request is coming from OAuth 2.0 server.
  var fragmentString = location.hash.substring(1);
  var params = {};
  var regex = /([^&=]+)=([^&]*)/g, m;
  while (m = regex.exec(fragmentString)) {
    params[decodeURIComponent(m[1])] = decodeURIComponent(m[2]);
  }
  if (Object.keys(params).length > 0 && params['state']) {
    if (params['state'] == localStorage.getItem('state')) {
      localStorage.setItem('oauth2-test-params', JSON.stringify(params) );

      trySampleRequest();
    } else {
      console.log('State mismatch. Possible CSRF attack');
    }
  }

  // Function to generate a random state value
  function generateCryptoRandomState() {
    const randomValues = new Uint32Array(2);
    window.crypto.getRandomValues(randomValues);

    // Encode as UTF-8
    const utf8Encoder = new TextEncoder();
    const utf8Array = utf8Encoder.encode(
      String.fromCharCode.apply(null, randomValues)
    );

    // Base64 encode the UTF-8 data
    return btoa(String.fromCharCode.apply(null, utf8Array))
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=+$/, '');
  }

  // If there's an access token, try an API request.
  // Otherwise, start OAuth 2.0 flow.
  function trySampleRequest() {
    var params = JSON.parse(localStorage.getItem('oauth2-test-params'));
    if (params && params['access_token']) { 
      // User authorized the request. Now, check which scopes were granted.
      if (params['scope'].includes('https://www.googleapis.com/auth/drive.metadata.readonly')) {
        // User authorized read-only Drive activity permission.
        // Calling the APIs, etc.
        var xhr = new XMLHttpRequest();
        xhr.open('GET',
          'https://www.googleapis.com/drive/v3/about?fields=user&' +
          'access_token=' + params['access_token']);
        xhr.onreadystatechange = function (e) {
          if (xhr.readyState === 4 && xhr.status === 200) {
            console.log(xhr.response);
          } else if (xhr.readyState === 4 && xhr.status === 401) {
            // Token invalid, so prompt for user permission.
            oauth2SignIn();
          }
        };
        xhr.send(null);
      }
      else {
        // User didn't authorize read-only Drive activity permission.
        // Update UX and application accordingly
        console.log('User did not authorize read-only Drive activity permission.');
      }

      // Check if user authorized Calendar read permission.
      if (params['scope'].includes('https://www.googleapis.com/auth/calendar.readonly')) {
        // User authorized Calendar read permission.
        // Calling the APIs, etc.
        console.log('User authorized Calendar read permission.');
      }
      else {
        // User didn't authorize Calendar read permission.
        // Update UX and application accordingly
        console.log('User did not authorize Calendar read permission.');
      } 
    } else {
      oauth2SignIn();
    }
  }

  /*
   * Create form to request access token from Google's OAuth 2.0 server.
   */
  function oauth2SignIn() {
    // create random state value and store in local storage
    var state = generateCryptoRandomState();
    localStorage.setItem('state', state);

    // Google's OAuth 2.0 endpoint for requesting an access token
    var oauth2Endpoint = 'https://accounts.google.com/o/oauth2/v2/auth';

    // Create element to open OAuth 2.0 endpoint in new window.
    var form = document.createElement('form');
    form.setAttribute('method', 'GET'); // Send as a GET request.
    form.setAttribute('action', oauth2Endpoint);

    // Parameters to pass to OAuth 2.0 endpoint.
    var params = {'client_id': YOUR_CLIENT_ID,
                  'redirect_uri': YOUR_REDIRECT_URI,
                  'scope': 'https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly',
                  'state': state,
                  'include_granted_scopes': 'true',
                  'response_type': 'token'};

    // Add form parameters as hidden input values.
    for (var p in params) {
      var input = document.createElement('input');
      input.setAttribute('type', 'hidden');
      input.setAttribute('name', p);
      input.setAttribute('value', params[p]);
      form.appendChild(input);
    }

    // Add form to page and submit it to open the OAuth 2.0 endpoint.
    document.body.appendChild(form);
    form.submit();
  }
</script>

<button onclick="trySampleRequest();">Try sample request</button>
</body></html>

OAuth 2.0 एंडपॉइंट

किसी मौजूदा ऐक्सेस टोकन में दायरे जोड़ने के लिए, Google के OAuth 2.0 सर्वर से किए गए अनुरोध में include_granted_scopes पैरामीटर शामिल करें.

नीचे दिए गए कोड स्निपेट में, ऐसा करने का तरीका बताया गया है. स्निपेट यह मानता है कि आपने ब्राउज़र के लोकल स्टोरेज में, उन स्कोप को सेव किया है जिनके लिए आपका ऐक्सेस टोकन मान्य है. (पूरे उदाहरण वाला कोड, ब्राउज़र के लोकल स्टोरेज में oauth2-test-params.scope प्रॉपर्टी सेट करके, उन स्कोप की सूची सेव करता है जिनके लिए ऐक्सेस टोकन मान्य है.)

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

var SCOPE = 'https://www.googleapis.com/auth/drive.metadata.readonly';
var params = JSON.parse(localStorage.getItem('oauth2-test-params'));

var current_scope_granted = false;
if (params.hasOwnProperty('scope')) {
  var scopes = params['scope'].split(' ');
  for (var s = 0; s < scopes.length; s++) {
    if (SCOPE == scopes[s]) {
      current_scope_granted = true;
    }
  }
}

if (!current_scope_granted) {
  oauth2SignIn(); // This function is defined elsewhere in this document.
} else {
  // Since you already have access, you can proceed with the API request.
}

OAuth 2.0 एंडपॉइंट

प्रोग्राम के हिसाब से किसी टोकन को रद्द करने के लिए, आपका ऐप्लिकेशन 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 दिखाया जाता है.

यहां दिए गए JavaScript स्निपेट में, JavaScript के लिए Google APIs क्लाइंट लाइब्रेरी का इस्तेमाल किए बिना, JavaScript में टोकन रद्द करने का तरीका बताया गया है. टोकन रद्द करने के लिए, Google का OAuth 2.0 एंडपॉइंट, क्रॉस-ऑरिजिन रिसॉर्स शेयरिंग (सीओआरएस) के साथ काम नहीं करता. इसलिए, अनुरोध पोस्ट करने के लिए XMLHttpRequest() तरीके का इस्तेमाल करने के बजाय, कोड एक फ़ॉर्म बनाता है और उस फ़ॉर्म को एंडपॉइंट पर सबमिट करता है.

function revokeAccess(accessToken) {
  // Google's OAuth 2.0 endpoint for revoking access tokens.
  var revokeTokenEndpoint = 'https://oauth2.googleapis.com/revoke';

  // Create <form> element to use to POST data to the OAuth 2.0 endpoint.
  var form = document.createElement('form');
  form.setAttribute('method', 'post');
  form.setAttribute('action', revokeTokenEndpoint);

  // Add access token to the form so it is set as value of 'token' parameter.
  // This corresponds to the sample curl request, where the URL is:
  //      https://oauth2.googleapis.com/revoke?token={token}
  var tokenField = document.createElement('input');
  tokenField.setAttribute('type', 'hidden');
  tokenField.setAttribute('name', 'token');
  tokenField.setAttribute('value', accessToken);
  form.appendChild(tokenField);

  // Add form to page and submit it to actually revoke the token.
  document.body.appendChild(form);
  form.submit();
}