שימוש ב-OAuth 2.0 לאפליקציות אינטרנט בצד הלקוח

נקודות קצה ב-OAuth 2.0

יצירת כתובת URL כדי לבקש גישה מנקודת הקצה מסוג OAuth 2.0 של Google ב- https://accounts.google.com/o/oauth2/v2/auth ניתן לגשת לנקודת הקצה הזו באמצעות HTTPS. חיבורי HTTP רגילים נדחים.

שרת ההרשאות של Google תומך בפרמטרים הבאים של מחרוזת שאילתה לאינטרנט אפליקציות שרת:

דוגמה להפניה מחדש לשרת ההרשאות של Google

למטה מוצגת כתובת URL לדוגמה, עם מעברי שורה ורווחים לשיפור הקריאוּת. כתובת ה-URL מבקשת גישה להיקף שמאפשר גישה לאחזור נתוני 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

לאחר יצירת כתובת ה-URL של הבקשה, הפנה את המשתמש אליה.

קוד לדוגמה של JavaScript

קטע הקוד הבא של JavaScript מראה איך להתחיל את תהליך ההרשאה ב- JavaScript בלי להשתמש בספריית הלקוח של Google APIs ל-JavaScript. מאז ה-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/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 שצוין בקשה לאסימון גישה.

אם המשתמש יאשר את הבקשה, התגובה תכיל אסימון גישה. אם המשתמש לא מאשר את הבקשה, התשובה תכיל הודעת שגיאה. אסימון הגישה או מוחזרת הודעת שגיאה בקטע ה-hash של ה-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

כדי לבדוק את התהליך הזה, לוחצים על כתובת ה-URL לדוגמה הבאה, הרשאת קריאה בלבד להצגת מטא-נתונים של קבצים ב-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), אלא אם המכונה המקומית מציגה קובץ בכתובת הכתובת הזאת. בשלב הבא מוצג פרטים נוספים על המידע שהוחזר URI כשהמשתמש מופנה בחזרה לאפליקציה.

נקודות קצה ב-OAuth 2.0

לאחר שהאפליקציה שלך מקבלת אסימון גישה, אפשר להשתמש באסימון כדי לבצע קריאות API בשם נתון חשבון משתמש, אם היקפי הגישה הנדרשים על ידי ה-API הוענקו. כדי לעשות את זה, צריך לכלול אסימון הגישה בבקשה ל-API על ידי הכללת שאילתת access_token או ערך Bearer של כותרת HTTP בAuthorization. כשהדבר אפשרי, עדיף להשתמש בכותרת HTTP, כי מחרוזות השאילתה בדרך כלל גלויות ביומני השרת. במרבית במקרים מסוימים תוכלו להשתמש בספריית לקוח כדי להגדיר את הקריאות ל-Google APIs (לדוגמה, שליחת קריאה ל-YouTube Live Streaming API).

שימו לב ש-YouTube Live Streaming API לא תומך בזרימה של חשבון השירות. מאז אין דרך לקשר חשבון שירות לחשבון YouTube, מנסה לאשר בקשות באמצעות חשבון זה התהליך הזה יפיק את השגיאה NoLinkedYouTubeAccount.

אפשר לנסות את כל ממשקי ה-API של Google ולצפות בהיקף שלהם בקישור OAuth 2.0 Playground

דוגמאות ל-HTTP GET

קריאה ל liveBroadcasts.list נקודת קצה (API של YouTube סטרימינג בשידור חי) באמצעות ה-HTTP Authorization: Bearer עשויה להיראות כך. שימו לב שתצטרכו לציין אסימון גישה משלכם:

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

זוהי קריאה לאותו API בשביל המשתמש המאומת באמצעות access_token פרמטר של מחרוזת שאילתה:

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

curl דוגמאות

אפשר לבדוק את הפקודות האלה באמצעות אפליקציית שורת הפקודה curl. הנה דוגמה שמשתמשת באפשרות של כותרת HTTP (מועדף):

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

קטע הקוד הבא מדגים איך להשתמש ב-CORS (שיתוף משאבים בין מקורות) כדי לשלוח בקשה ל-Google API. בדוגמה הזו לא נעשה שימוש בספריית הלקוח של Google APIs ל-JavaScript. אבל גם אם אתם לא משתמשים בספריית הלקוח, סביר להניח שמדריך לתמיכה ב-CORS במסמכי התיעוד של הספרייה הזו יעזור לך. כדי להבין טוב יותר את הבקשות האלה.

בקטע הקוד הזה, המשתנה access_token מייצג את האסימון שיש לכם כדי להגיש בקשות API בשם המשתמש המורשה. התוכן דוגמה שממחישה איך לאחסן את האסימון באחסון המקומי של הדפדפן ולאחזר אותו כששולחים בקשת API.

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

דוגמת הקוד הזו מדגימה איך להשלים את תהליך OAuth 2.0 ב-JavaScript, בלי להשתמש ספריית הלקוח של Google APIs ל-JavaScript. הקוד מיועד לדף HTML שמוצג בו לחצן לנסות לשלוח בקשת API. אם תלחצו על הלחצן, הקוד בודק אם הדף שמר אסימון הגישה ל-API באחסון המקומי של הדפדפן. אם כן, היא תריץ את בקשת ה-API. אחרת, מתחיל זרימת OAuth 2.0.

לתהליך OAuth 2.0, הדף מבצע את השלבים הבאים:

1. הוא מפנה את המשתמש לשרת OAuth 2.0 של Google, שמבקש גישה היקף הרשאות אחד (https://www.googleapis.com/auth/youtube.force-ssl).
2. אחרי הענקת (או דחייה) של הרשאת גישה להיקף בקשה אחד או יותר, המשתמש מופנה אל הדף המקורי, שמנתח את אסימון הגישה מהמחרוזת של מזהה המקטע.

3. הדף משתמש באסימון הגישה כדי לבצע את בקשת ה-API לדוגמה.

   בקשת ה-API הזו מפעילה את ה-liveBroadcasts.list של YouTube Data API שיטה לאחזור רשימה של שידורי וידאו לערוץ YouTube של המשתמש המורשה.

4. אם הבקשה מבוצעת בהצלחה, תגובת ה-API תתועד בניפוי הבאגים של הדפדפן במסוף.

אפשר לבטל את הגישה לאפליקציה דרך הדף הרשאות של חשבון Google. האפליקציה תופיע כהדגמה של OAuth 2.0 ל-Google API Docs.

כדי להריץ את הקוד הזה באופן מקומי, צריך להגדיר ערכים עבור YOUR_CLIENT_ID YOUR_REDIRECT_URI משתנים שתואמים פרטי כניסה להרשאה. המשתנה YOUR_REDIRECT_URI צריך להיות מוגדר לאותה כתובת אתר שבה הדף מוצג. הערך צריך להתאים בדיוק לאחד מהערכים מזהי ה-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/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 של המשתמש, בנוסף לכל גישה אחרת שיש לו כבר העניק לאפליקציה.

כדי להוסיף היקפים לאסימון גישה קיים, צריך לכלול את include_granted_scopes בבקשה לשרת OAuth 2.0 של Google.

קטע הקוד הבא מדגים איך לעשות את זה. קטע הקוד מניח שאחסנתם היקפי ההרשאות שעבורם אסימון הגישה בתוקף באחסון המקומי של הדפדפן. (ה הקוד הדוגמה המלאה מאחסן רשימת היקפים של אסימון הגישה חוקי על ידי הגדרת המאפיין oauth2-test-params.scope בקובץ המקומי של הדפדפן storage.)

קטע הקוד משווה את היקפי ההרשאות שבהם אסימון הגישה תקף להיקף שבו רוצים להשתמש לשאילתה מסוימת. אם אסימון הגישה לא מכסה את ההיקף הזה, מתחיל תהליך OAuth 2.0. כאן, הפונקציה oauth2SignIn זהה לזו שצוינה שלב 2 (ומופיע מאוחר יותר בשלב הבא דוגמה).

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}

האסימון יכול להיות אסימון גישה או אסימון רענון. אם האסימון הוא אסימון גישה ויש לו אסימון הרענון התואם, גם אסימון הרענון יבוטל.

אם הביטול בוצע בהצלחה, קוד סטטוס ה-HTTP של התשובה 200 במקרים של שגיאות, מוחזר קוד מצב HTTP 400 עם קוד שגיאה.

קטע הקוד הבא של JavaScript מראה איך לבטל אסימון ב-JavaScript בלי להשתמש באופרטור ספריית הלקוח של Google APIs ל-JavaScript. מאז נקודת הקצה OAuth 2.0 של Google לביטול אין תמיכה בשיתוף משאבים בין מקורות (CORS), הקוד יוצר טופס ושולח את הטופס לנקודת הקצה (endpoint) במקום להשתמש בשיטה 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();
}