OAuth 2.0 برای برنامه های کاربردی وب سمت مشتری

نقاط پایانی OAuth 2.0

یک URL برای درخواست دسترسی از نقطه پایانی OAuth 2.0 Google در https://accounts.google.com/o/oauth2/v2/auth ایجاد کنید. این نقطه پایانی از طریق HTTPS قابل دسترسی است. اتصالات HTTP ساده رد می شوند.

سرور مجوز Google از پارامترهای رشته پرس و جو زیر برای برنامه های وب سرور پشتیبانی می کند:

تغییر مسیر نمونه به سرور مجوز Google

یک URL مثال در زیر نشان داده شده است، با خطوط شکسته و فاصله برای خوانایی.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A//www.googleapis.com/auth/drive.metadata.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

پس از ایجاد URL درخواست، کاربر را به آن هدایت کنید.

کد نمونه جاوا اسکریپت

قطعه جاوا اسکریپت زیر نشان می دهد که چگونه می توان جریان مجوز در جاوا اسکریپت را بدون استفاده از Google APIs Client Library برای جاوا اسکریپت آغاز کرد. از آنجایی که این نقطه پایانی OAuth 2.0 از اشتراک‌گذاری منابع متقاطع (CORS) پشتیبانی نمی‌کند، قطعه فرمی ایجاد می‌کند که درخواست را به آن نقطه پایانی باز می‌کند.

/*
 * 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',
                '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 مشخص شده در درخواست نشانه دسترسی شما ارسال می کند.

اگر کاربر درخواست را تأیید کند، پاسخ حاوی یک نشانه دسترسی است. اگر کاربر درخواست را تایید نکند، پاسخ حاوی یک پیام خطا است. نشانه دسترسی یا پیام خطا بر روی قطعه هش 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//www.googleapis.com/auth/drive.metadata.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 هدایت خواهید شد. آن URL یک خطای 404 NOT FOUND را نشان می دهد مگر اینکه دستگاه محلی شما فایلی را در آن آدرس ارائه کند. مرحله بعدی جزئیات بیشتری را در مورد اطلاعات بازگردانده شده در URI هنگامی که کاربر به برنامه شما هدایت می شود ارائه می دهد.

نقاط پایانی OAuth 2.0

پس از اینکه برنامه شما یک نشانه دسترسی به دست آورد، در صورتی که دامنه دسترسی مورد نیاز توسط API اعطا شده باشد، می توانید از این رمز برای برقراری تماس با Google API از طرف یک حساب کاربری خاص استفاده کنید. برای انجام این کار، توکن دسترسی را با درج یک پارامتر query access_token یا یک مقدار Authorization HTTP header Bearer در درخواست API قرار دهید. در صورت امکان، هدر HTTP ترجیح داده می شود، زیرا رشته های پرس و جو در گزارش های سرور قابل مشاهده هستند. در بیشتر موارد می‌توانید از کتابخانه سرویس گیرنده برای تنظیم تماس‌های خود با Google API استفاده کنید (به عنوان مثال، هنگام تماس با Drive Files API ).

می‌توانید همه APIهای Google را امتحان کنید و دامنه آنها را در OAuth 2.0 Playground مشاهده کنید.

نمونه های HTTP GET

تماس با نقطه پایانی drive.files (API فایل‌های Drive) با استفاده از هدر HTTP Authorization: Bearer ممکن است به شکل زیر باشد. توجه داشته باشید که باید رمز دسترسی خود را مشخص کنید:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

در اینجا یک فراخوانی به همان API برای کاربر تأیید شده با استفاده از پارامتر رشته query access_token وجود دارد:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

نمونه های curl

می توانید این دستورات را با برنامه خط فرمان curl آزمایش کنید. در اینجا یک مثال است که از گزینه هدر HTTP (ترجیح) استفاده می کند:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

یا، گزینه پارامتر query string:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

کد نمونه جاوا اسکریپت

قطعه کد زیر نحوه استفاده از CORS (اشتراک‌گذاری منابع متقاطع) را برای ارسال درخواست به Google API نشان می‌دهد. این مثال از Google APIs Client Library برای جاوا اسکریپت استفاده نمی کند. با این حال، حتی اگر از کتابخانه مشتری استفاده نمی کنید، راهنمای پشتیبانی CORS در اسناد آن کتابخانه احتمالاً به شما در درک بهتر این درخواست ها کمک می کند.

در این قطعه کد، متغیر access_token نشان دهنده نشانه ای است که شما برای درخواست API از طرف کاربر مجاز به دست آورده اید. مثال کامل نحوه ذخیره آن توکن در حافظه محلی مرورگر و بازیابی آن هنگام درخواست API را نشان می دهد.

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

این نمونه کد نحوه تکمیل جریان OAuth 2.0 در جاوا اسکریپت را بدون استفاده از Google APIs Client Library برای جاوا اسکریپت نشان می دهد. کد مربوط به یک صفحه HTML است که دکمه ای را برای امتحان درخواست API نمایش می دهد. اگر روی دکمه کلیک کنید، کد بررسی می کند که آیا صفحه نشانه دسترسی API را در حافظه محلی مرورگر شما ذخیره کرده است یا خیر. اگر چنین است، درخواست API را اجرا می کند. در غیر این صورت، جریان OAuth 2.0 را آغاز می کند.

برای جریان OAuth 2.0، صفحه این مراحل را دنبال می کند:

1. کاربر را به سرور OAuth 2.0 گوگل هدایت می کند، که درخواست دسترسی به حوزه https://www.googleapis.com/auth/drive.metadata.readonly را می کند.
2. پس از اعطای (یا رد کردن) دسترسی به یک یا چند محدوده درخواستی، کاربر به صفحه اصلی هدایت می شود که رمز دسترسی را از رشته شناسه قطعه تجزیه می کند.

3. صفحه از نشانه دسترسی برای درخواست نمونه API استفاده می کند.

   درخواست API برای بازیابی اطلاعات مربوط به حساب Google Drive کاربر مجاز، روش about.get درایو API را فراخوانی می‌کند.

4. اگر درخواست با موفقیت اجرا شود، پاسخ API در کنسول اشکال زدایی مرورگر ثبت می شود.

می‌توانید دسترسی به برنامه را از طریق صفحه مجوزهای حساب Google خود لغو کنید. این برنامه به عنوان نسخه ی نمایشی OAuth 2.0 برای Google API Docs فهرست می شود.

برای اجرای این کد به صورت محلی، باید مقادیری را برای متغیرهای YOUR_CLIENT_ID و YOUR_REDIRECT_URI تنظیم کنید که مطابق با اعتبار مجوز شما باشد. متغیر YOUR_REDIRECT_URI باید روی همان URL که صفحه در حال ارائه است تنظیم شود. مقدار باید دقیقاً با یکی از URIهای مجاز تغییر مسیر برای مشتری OAuth 2.0 مطابقت داشته باشد که در آن پیکربندی کرده اید. API Console Credentials page. اگر این مقدار با یک URI مجاز مطابقت نداشته باشد، یک خطای redirect_uri_mismatch دریافت خواهید کرد. پروژه شما باید API مناسب برای این درخواست را نیز فعال کرده باشد.

<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/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 {
      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',
                  '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

برای افزودن دامنه به یک نشانه دسترسی موجود، پارامتر include_granted_scopes را در درخواست خود به سرور OAuth 2.0 Google اضافه کنید.

قطعه کد زیر نحوه انجام این کار را نشان می دهد. قطعه فرض می کند که شما محدوده هایی را که رمز دسترسی شما برای آنها معتبر است در حافظه محلی مرورگر ذخیره کرده اید. (کد مثال کامل ، فهرستی از حوزه هایی را که نشانه دسترسی برای آنها معتبر است، با تنظیم ویژگی oauth2-test-params.scope در حافظه محلی مرورگر ذخیره می کند.)

اسنیپت محدوده هایی را که نشانه دسترسی برای آنها معتبر است با محدوده ای که می خواهید برای یک پرس و جوی خاص استفاده کنید مقایسه می کند. اگر نشانه دسترسی آن محدوده را پوشش ندهد، جریان OAuth 2.0 شروع می شود. در اینجا، تابع oauth2SignIn همان تابعی است که در مرحله 2 ارائه شد (و در ادامه در مثال کامل ارائه شده است).

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}

توکن می تواند یک نشانه دسترسی یا یک نشانه تازه سازی باشد. اگر توکن یک نشانه دسترسی باشد و دارای یک نشانه رفرش متناظر باشد، توکن رفرش نیز باطل می شود.

اگر ابطال با موفقیت پردازش شود، کد وضعیت HTTP پاسخ 200 است. برای شرایط خطا، کد وضعیت HTTP 400 به همراه یک کد خطا برگردانده می شود.

قطعه جاوا اسکریپت زیر نشان می دهد که چگونه می توان یک توکن در جاوا اسکریپت را بدون استفاده از Google APIs Client Library برای جاوا اسکریپت باطل کرد. از آنجایی که نقطه پایانی Google OAuth 2.0 برای باطل کردن توکن‌ها از اشتراک‌گذاری منابع متقاطع (CORS) پشتیبانی نمی‌کند، کد به جای استفاده از روش 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();
}