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

OAuth 2.0 एंडपॉइंट

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

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

सैंपल के तौर पर, Google के ऑथराइज़ेशन सर्वर पर रीडायरेक्ट करने की सुविधा

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

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 client_id=client_id

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

JavaScript सैंपल कोड

नीचे दिया गया JavaScript स्निपेट यह दिखाता है कि JavaScript के लिए Google API क्लाइंट लाइब्रेरी का इस्तेमाल किए बिना, 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/youtube.force-ssl',
                '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 में मौजूद फ़ाइलों का मेटाडेटा देखने के लिए, रीड ओनली ऐक्सेस का अनुरोध करता है:

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl&
 include_granted_scopes=true&
 response_type=token&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 client_id=client_id

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

OAuth 2.0 एंडपॉइंट

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

ध्यान दें कि YouTube Live Streaming API, सेवा खाते के फ़्लो के साथ काम नहीं करता. सेवा खाते को YouTube खाते से लिंक करने का कोई तरीका नहीं है. इसलिए, इस फ़्लो का इस्तेमाल करके अनुरोधों को अनुमति देने की कोशिश करने पर, NoLinkedYouTubeAccount गड़बड़ी जनरेट होगी.

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

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

Authorization: Bearer एचटीटीपी हेडर का इस्तेमाल करके, liveBroadcasts.list एंडपॉइंट (YouTube Live Streaming API) को कॉल करने पर ऐसा दिख सकता है. ध्यान दें कि आपको अपना ऐक्सेस टोकन बताना होगा:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

यहां access_token क्वेरी स्ट्रिंग पैरामीटर का इस्तेमाल करके, पुष्टि किए गए उपयोगकर्ता के लिए उसी एपीआई को कॉल किया गया है:

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

curl के उदाहरण

curl कमांड-लाइन ऐप्लिकेशन का इस्तेमाल करके, इन कमांड की जांच की जा सकती है. यहां एक उदाहरण दिया गया है, जिसमें एचटीटीपी हेडर विकल्प का इस्तेमाल किया जाता है (इसका सुझाव दिया जाता है):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

इसके अलावा, क्वेरी स्ट्रिंग पैरामीटर विकल्प:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

JavaScript सैंपल कोड

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

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

var xhr = new XMLHttpRequest();
xhr.open('GET',
    'https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id,snippet&mine=true' +
    '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/youtube.force-ssl स्कोप के ऐक्सेस का अनुरोध करता है.
2. अनुरोध किए गए एक या उससे ज़्यादा दायरों का ऐक्सेस देने या अस्वीकार करने के बाद, उपयोगकर्ता को ओरिजनल पेज पर रीडायरेक्ट किया जाता है. यह पेज, फ़्रैगमेंट आइडेंटिफ़ायर स्ट्रिंग से ऐक्सेस टोकन को पार्स करता है.

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

   यह एपीआई अनुरोध, YouTube Data API के liveBroadcasts.list तरीके का इस्तेमाल करके, उस उपयोगकर्ता के YouTube चैनल के लिए वीडियो ब्रॉडकास्ट की सूची हासिल करता है जिसे अनुमति मिली है.

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

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

इस कोड को स्थानीय तौर पर चलाने के लिए, आपको अपने ऑथराइज़ेशन क्रेडेंशियल से जुड़े YOUR_CLIENT_ID और YOUR_REDIRECT_URI वैरिएबल की वैल्यू सेट करनी होंगी. YOUR_REDIRECT_URI वैरिएबल को उसी यूआरएल पर सेट किया जाना चाहिए जिस पर पेज दिखाया जा रहा है. वैल्यू, उस OAuth 2.0 क्लाइंट के लिए, अनुमति वाले रीडायरेक्ट यूआरआई में से किसी एक से पूरी तरह मेल खानी चाहिए. आपने इसे API Console Credentials pageमें कॉन्फ़िगर किया है. अगर यह वैल्यू, अनुमति वाले यूआरआई से मेल नहीं खाती है, तो आपको 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']) {
      var xhr = new XMLHttpRequest();
      xhr.open('GET',
          'https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id,snippet&mine=true' +
          '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 {
      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/youtube.force-ssl',
                  '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 एंडपॉइंट

इस उदाहरण में, कॉल करने वाला ऐप्लिकेशन, उपयोगकर्ता का YouTube डेटा वापस पाने के लिए ऐक्सेस का अनुरोध करता है. इसके अलावा, उपयोगकर्ता ने ऐप्लिकेशन को पहले से दिए गए अन्य ऐक्सेस का भी अनुरोध किया है.

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

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

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

var SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl';
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 API क्लाइंट लाइब्रेरी का इस्तेमाल किए बिना, 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();
}