با استفاده از مدل توکن

کتابخانه جاوا اسکریپت google.accounts.oauth2 به شما کمک می کند رضایت کاربر را درخواست کنید و یک کد دسترسی برای کار با داده های کاربر دریافت کنید. این مبتنی بر جریان اعطای ضمنی OAuth 2.0 است و به گونه ای طراحی شده است که به شما امکان می دهد مستقیماً با استفاده از REST و CORS با Google API تماس بگیرید یا از کتابخانه سرویس گیرنده Google API ما برای جاوا اسکریپت (همچنین به عنوان gapi.client شناخته می شود) برای دسترسی ساده و انعطاف پذیر به API های پیچیده تر ما

قبل از دسترسی به داده‌های کاربر محافظت‌شده از مرورگر، کاربران در سایت شما فرآیندهای انتخاب حساب مبتنی بر وب Google، ورود به سیستم و رضایت را راه‌اندازی می‌کنند و در نهایت سرورهای OAuth Google مشکلی ایجاد می‌کنند و یک نشانه دسترسی به برنامه وب شما برمی‌گردانند.

در مدل مجوز مبتنی بر توکن، نیازی به ذخیره نشانه‌های تازه‌سازی برای هر کاربر در سرور باطن شما نیست.

توصیه می‌شود به‌جای تکنیک‌هایی که در راهنمای قدیمی‌تر OAuth 2.0 برای برنامه‌های کاربردی وب سمت کلاینت پوشش داده شده، از رویکردی که در اینجا اشاره شده است، پیروی کنید.

راه اندازی

با دنبال کردن مراحل توضیح داده شده در راهنمای دریافت شناسه مشتری Google API خود، یک شناسه مشتری پیدا یا ایجاد کنید. در مرحله بعد، کتابخانه مشتری را به صفحاتی در سایت خود اضافه کنید که Google API را فراخوانی می کنند. در نهایت، مشتری توکن را مقداردهی اولیه کنید. به طور معمول، این کار در کنترل کننده onload کتابخانه مشتری انجام می شود.

یک کلاینت توکن را راه اندازی کنید

initTokenClient() را فراخوانی کنید تا یک کلاینت توکن جدید با شناسه مشتری برنامه وب خود را مقداردهی کنید، در صورت تمایل می توانید فهرستی از یک یا چند محدوده مورد نیاز کاربر برای دسترسی به آن را اضافه کنید: 

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (response) => {
    ...
  },
});

جریان توکن OAuth 2.0 را فعال کنید

از متد requestAccessToken() برای راه اندازی جریان UX توکن و به دست آوردن یک نشانه دسترسی استفاده کنید. گوگل از کاربر می خواهد که:

  • حساب کاربری آنها را انتخاب کنید،
  • اگر قبلاً وارد حساب Google نشده اید، وارد شوید،
  • رضایت برنامه وب خود را برای دسترسی به هر محدوده درخواستی بدهید.

یک اشاره کاربر جریان نشانه را فعال می کند: <button onclick="client.requestAccessToken();">Authorize me</button>

سپس Google یک TokenResponse حاوی یک نشانه دسترسی و فهرستی از محدوده‌هایی که کاربر به آن‌ها اجازه دسترسی داده است، یا یک خطا را به کنترل کننده پاسخ تماس شما برمی‌گرداند.

کاربران ممکن است پنجره های انتخابگر حساب یا ورود به سیستم را ببندند، در این صورت عملکرد پاسخ به تماس شما فراخوانی نمی شود.

طراحی و تجربه کاربری برای برنامه شما باید تنها پس از بررسی کامل خط‌مشی‌های Google OAuth 2.0 اجرا شود. این خط‌مشی‌ها کار با حوزه‌های متعدد، زمان و نحوه رسیدگی به رضایت کاربر و موارد دیگر را پوشش می‌دهند.

مجوز افزایشی یک روش خط‌مشی و طراحی برنامه است که برای درخواست دسترسی به منابع، با استفاده از محدوده‌ها، فقط در صورت نیاز و نه از قبل و به یکباره استفاده می‌شود. کاربران ممکن است به اشتراک گذاری منابع فردی درخواست شده توسط برنامه شما را تأیید یا رد کنند، این به عنوان مجوزهای granular شناخته می شود.

در طول این فرآیند، Google درخواست رضایت کاربر را می‌دهد، و هر محدوده درخواستی را به‌صورت جداگانه فهرست می‌کند، کاربران منابعی را انتخاب می‌کنند که با برنامه شما به اشتراک گذاشته شود، و در نهایت، Google عملکرد پاسخ به تماس شما را فراخوانی می‌کند تا یک نشانه Access و محدوده‌های مورد تأیید کاربر را بازگرداند. سپس برنامه شما به‌طور ایمن نتایج مختلف ممکن را با مجوزهای گرانول کنترل می‌کند.

مجوز افزایشی

برای برنامه های وب، دو سناریو سطح بالا زیر مجوز افزایشی را با استفاده از:

  • یک برنامه Ajax تک صفحه ای که اغلب از XMLHttpRequest با دسترسی پویا به منابع استفاده می کند.
  • چندین صفحه وب، منابع جدا شده و بر اساس هر صفحه مدیریت می شوند.

این دو سناریو برای نشان دادن ملاحظات و روش‌شناسی طراحی ارائه شده‌اند، اما در نظر گرفته نشده‌اند که توصیه‌های جامعی در مورد نحوه ایجاد رضایت در برنامه شما باشند. برنامه های دنیای واقعی ممکن است از تنوع یا ترکیبی از این تکنیک ها استفاده کنند.

آژاکس

با برقراری تماس های متعدد با requestAccessToken() و استفاده از پارامتر scope شی OverridableTokenClientConfig برای درخواست دامنه های فردی در زمان مورد نیاز و فقط در صورت لزوم، پشتیبانی از مجوز افزایشی را به برنامه خود اضافه کنید. در این مثال، منابع درخواست می‌شوند و تنها پس از اینکه یک حرکت کاربر بخش محتوای جمع‌شده را گسترش می‌دهد، قابل مشاهده است.

اپلیکیشن آژاکس
در بارگذاری صفحه، مشتری توکن را راه اندازی کنید: 
        const client = google.accounts.oauth2.initTokenClient({
          client_id: 'YOUR_GOOGLE_CLIENT_ID',
          callback: "onTokenResponse",
        });
درخواست رضایت و دریافت نشانه های دسترسی از طریق حرکات کاربر، روی «+» کلیک کنید تا باز شود:

اسنادی برای خواندن

نمایش اسناد اخیر 

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/documents.readonly'
             })
           );

رویدادهای آینده

نمایش اطلاعات تقویم 

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/calendar.readonly'
             })
           );

نمایش عکس ها 

          client.requestAccessToken(
            overrideConfig = ({
               scope = 'https://www.googleapis.com/auth/photoslibrary.readonly'
             })
           );

هر تماس با requestAccessToken یک لحظه رضایت کاربر را ایجاد می‌کند، برنامه شما فقط به منابع مورد نیاز بخشی که کاربر برای گسترش انتخاب می‌کند دسترسی خواهد داشت، بنابراین اشتراک‌گذاری منابع را از طریق انتخاب کاربر محدود می‌کند.

چندین صفحه وب

هنگام طراحی برای مجوز افزایشی، از چندین صفحه فقط برای درخواست دامنه (های) مورد نیاز برای بارگذاری یک صفحه استفاده می شود، که پیچیدگی و نیاز به برقراری تماس های متعدد برای کسب رضایت کاربر و بازیابی نشانه دسترسی را کاهش می دهد.

اپلیکیشن چند صفحه ای
صفحه وب کد
صفحه 1. اسنادی برای خواندن 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
صفحه 2. رویدادهای آینده 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/calendar.readonly',
  });
  client.requestAccessToken();
صفحه 3. چرخ فلک عکس 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/photoslibrary.readonly',
  });
  client.requestAccessToken();

هر صفحه دامنه لازم را درخواست می کند و با فراخوانی initTokenClient() و requestAccessToken() در زمان بارگذاری، یک نشانه دسترسی به دست می آورد. در این سناریو، از صفحات وب منفرد برای جداسازی واضح عملکرد و منابع کاربر بر اساس محدوده استفاده می شود. در یک موقعیت دنیای واقعی، صفحات منفرد ممکن است چندین محدوده مرتبط را درخواست کنند.

مجوزهای گرانول

مجوزهای گرانول در همه سناریوها به یک شکل اداره می شوند. پس از اینکه requestAccessToken() تابع پاسخ به تماس شما را فراخوانی کرد و یک نشانه دسترسی بازگردانده شد، بررسی کنید که کاربر با استفاده از hasGrantedAllScopes() یا hasGrantedAnyScope() دامنه های درخواستی را تایید کرده باشد. به عنوان مثال:

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly \
          https://www.googleapis.com/auth/documents.readonly \
          https://www.googleapis.com/auth/photoslibrary.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      if (google.accounts.oauth2.hasGrantedAnyScope(tokenResponse,
          'https://www.googleapis.com/auth/photoslibrary.readonly')) {
        // Look at pictures
        ...
      }
      if (google.accounts.oauth2.hasGrantedAllScopes(tokenResponse,
          'https://www.googleapis.com/auth/calendar.readonly',
          'https://www.googleapis.com/auth/documents.readonly')) {
        // Meeting planning and review documents
        ...
      }
    }
  },
});

هرگونه کمک هزینه قبلاً پذیرفته شده از جلسات یا درخواست های قبلی نیز در پاسخ گنجانده خواهد شد. یک رکورد از رضایت کاربر به ازای هر کاربر و شناسه مشتری نگهداری می‌شود و در چندین تماس با initTokenClient() یا requestAccessToken() باقی می‌ماند. به‌طور پیش‌فرض، رضایت کاربر تنها برای اولین باری که کاربر از وب‌سایت شما بازدید می‌کند و دامنه جدیدی را درخواست می‌کند ضروری است، اما ممکن است در هر بارگذاری صفحه با استفاده از prompt=consent در اشیاء پیکربندی Token Client درخواست شود.

کار با توکن ها

در مدل Token، یک نشانه دسترسی توسط سیستم عامل یا مرورگر ذخیره نمی‌شود، در عوض یک نشانه جدید ابتدا در زمان بارگذاری صفحه، یا متعاقباً با راه‌اندازی فراخوانی به requestAccessToken() از طریق یک حرکت کاربر مانند فشار دادن دکمه به دست می‌آید.

استفاده از REST و CORS با APIهای Google

یک نشانه دسترسی می‌تواند برای درخواست‌های احراز هویت شده به APIهای Google با استفاده از REST و CORS استفاده شود. این به کاربران امکان می‌دهد وارد سیستم شوند، رضایت دهند، Google یک نشانه دسترسی صادر کند و سایت شما با داده‌های کاربر کار کند.

در این مثال، رویدادهای تقویم آینده کاربرانی که وارد سیستم شده‌اند را با استفاده از نشانه دسترسی که توسط tokenRequest() بازگردانده شده است، مشاهده کنید:

var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://www.googleapis.com/calendar/v3/calendars/primary/events');
xhr.setRequestHeader('Authorization', 'Bearer ' + tokenResponse.access_token);
xhr.send();

برای اطلاعات بیشتر به نحوه استفاده از CORS برای دسترسی به APIهای Google مراجعه کنید.

بخش بعدی نحوه ادغام آسان با API های پیچیده تر را پوشش می دهد.

کار با کتابخانه جاوا اسکریپت Google APIs

کلاینت نشانه با کتابخانه سرویس گیرنده Google API برای جاوا اسکریپت کار می کند قطعه کد زیر را ببینید. 

const client = google.accounts.oauth2.initTokenClient({
  client_id: 'YOUR_GOOGLE_CLIENT_ID',
  scope: 'https://www.googleapis.com/auth/calendar.readonly',
  callback: (tokenResponse) => {
    if (tokenResponse && tokenResponse.access_token) {
      gapi.client.setApiKey('YOUR_API_KEY');
      gapi.client.load('calendar', 'v3', listUpcomingEvents);
    }
  },
});

function listUpcomingEvents() {
  gapi.client.calendar.events.list(...);
}

انقضای توکن

با طراحی، توکن های دسترسی عمر کوتاهی دارند. اگر نشانه دسترسی قبل از پایان جلسه کاربر منقضی شود، با فراخوانی requestAccessToken() از یک رویداد مبتنی بر کاربر مانند فشار دادن دکمه، یک توکن جدید دریافت کنید.

با روش google.accounts.oauth2.revoke تماس بگیرید تا رضایت کاربر و دسترسی به منابع برای همه حوزه‌های اعطا شده به برنامه شما حذف شود. یک نشانه دسترسی معتبر برای لغو این مجوز لازم است:

google.accounts.oauth2.revoke('414a76cb127a7ece7ee4bf287602ca2b56f8fcbf7fcecc2cd4e0509268120bd7', done => {
    console.log(done);
    console.log(done.successful);
    console.log(done.error);
    console.log(done.error_description);
  });