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

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

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

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

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

پیش‌نیازها

برای پیکربندی صفحه رضایت OAuth، دریافت شناسه کلاینت و بارگذاری کتابخانه کلاینت، مراحل شرح داده شده در بخش تنظیمات را دنبال کنید.

مقداردهی اولیه کلاینت توکن

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

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 توکن و دریافت توکن دسترسی استفاده کنید. گوگل از کاربر می‌خواهد که:

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

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

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

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

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

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

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

با این حال، استثنائاتی وجود دارد. برنامه‌های Google Workspace Enterprise با تفویض اختیار در سطح دامنه یا برنامه‌هایی که به عنوان Trusted علامت‌گذاری شده‌اند، صفحه رضایت مجوزهای جزئی را دور می‌زنند. برای این برنامه‌ها، کاربران صفحه رضایت مجوزهای جزئی را نمی‌بینند. در عوض، برنامه شما یا همه محدوده‌های درخواستی را دریافت می‌کند یا هیچ کدام را دریافت نمی‌کند.

For more detailed information, see How to handle granular permissions .

مجوز افزایشی

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

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

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

آژاکس

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

برنامه آژاکس
کلاینت توکن را هنگام بارگذاری صفحه مقداردهی اولیه کنید:
        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 باعث ایجاد یک لحظه رضایت کاربر می‌شود، برنامه شما فقط به منابعی که توسط بخشی که کاربر برای گسترش انتخاب می‌کند مورد نیاز است دسترسی خواهد داشت، بنابراین اشتراک‌گذاری منابع از طریق انتخاب کاربر محدود می‌شود.

صفحات وب متعدد

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

برنامه چند صفحه‌ای
صفحه وب کد
صفحه ۱. اسنادی برای مطالعه 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/documents.readonly',
  });
  client.requestAccessToken();
صفحه ۲. رویدادهای آینده 
  const client = google.accounts.oauth2.initTokenClient({
    client_id: 'YOUR_GOOGLE_CLIENT_ID',
    callback: "onTokenResponse",
    scope: 'https://www.googleapis.com/auth/calendar.readonly',
  });
  client.requestAccessToken();
صفحه ۳. چرخ فلک عکس 
  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
        ...
      }
    }
  },
});

Any previously accepted grants from prior sessions or requests will also be included in the response. A record of user consent is maintained per user and Client ID, and persists across multiple calls to initTokenClient() or requestAccessToken() . By default, user consent is only necessary the first time a user visits your website and requests a new scope but may be requested on every page load using prompt=consent in Token Client config objects.

کار با توکن‌ها

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

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

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

در این مثال، رویدادهای تقویم آینده کاربران وارد شده را با استفاده از توکن دسترسی برگردانده شده توسط 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();

APIهای گوگل به طور پیش‌فرض از CORS پشتیبانی می‌کنند، گنجاندن یک توکن دسترسی در یک درخواست XMLHttpRequest یا fetch ، بررسی اولیه CORS را آغاز می‌کند؛ یک درخواست OPTIONS قبل از GET یا POST.

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

کار با کتابخانه جاوا اسکریپت API های گوگل

کلاینت توکن با کتابخانه کلاینت 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);
  });