דף זה תורגם על ידי Cloud Translation API.

OAuth בספריות הלקוח של פרוטוקול הנתונים של Google

אזהרה: דף זה עוסק בממשקי API הישנים יותר של Google, בממשקי ה-API של נתוני Google, והוא רלוונטי רק לממשקי ה-API שרשומים בספריית ממשקי ה-API של נתוני Google, שרבים מהם הוחלפו בממשקי API חדשים יותר. למידע על API חדש ספציפי, עיינו במסמכי התיעוד של ה-API החדש. למידע על הרשאת בקשות באמצעות ממשק API חדש יותר, יש לעיין בקטע אימות והרשאה של חשבונות Google.

מסמך זה מתאר כיצד להשתמש בספריות הלקוח של Google Data API כדי להתחבר אל אימות OAuth עבור יישומי אינטרנט של Google.

ממשק ה-OAuth מאפשר לאפליקציה מבוססת-אינטרנט לגשת לשירות Google בשם משתמש. כדי לשמור על רמת אבטחה גבוהה, OAuth מאפשר לאפליקציה לקבל אסימון גישה מבלי לטפל בפרטי ההתחברות לחשבון המשתמש.

ספריות הלקוח של Google Data API מספקות שיטות שיעזרו לכם להשתמש ב-OAuth באפליקציית האינטרנט שלכם. באופן ספציפי, קיימות שיטות לבניית אסימון הבקשה עבור אסימון בקשה, הרשאת אסימון הבקשה והחלפת אסימון הבקשה המורשה לאסימון גישה. הספריות מטפלות גם באלגוריתמים הנחוצים לחתימה כששולחים בקשות לשירות נתונים של Google.

Audience

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

במסמך הזה ההנחה היא שאתם מכירים את ממשק OAuth ואת התהליך הכללי לשילוב OAuth באפליקציית האינטרנט. לתיאור מלא של פרוטוקול OAuth, קראו את המאמר אימות OAuth עבור אפליקציות אינטרנט או את המפרט הרשמי בכתובת oauth.net.

שימוש ב-OAuth תלת-רגלי ובממשקי API של נתונים של Google ללא ספריות הלקוח

אם אתם רוצים שאפליקציית האינטרנט תיצור אינטראקציה עם שירות נתונים של Google באמצעות OAuth כשיטת הרשאה, כל מה שצריך לדעת הוא באימות OAuth לאפליקציות אינטרנט. אין צורך להשתמש בספריות הלקוח של Google Data APIs אם אינך רוצה.

לפניכם תיאור של האופן שבו האפליקציה עשויה לאמת משתמש באמצעות OAuth:

האפליקציה שלך חותמת על בקשה חתומה לאסימון אסימון OAuth ראשוני מנקודת הקצה OAuthRequestToken.
האפליקציה מפנה את המשתמש לכתובת ה-URL המתאימה של OAuthAuthorizeToken כדי לאשר את אסימון הבקשה.
לאחר הענקת גישה, המשתמש יופנה בחזרה לאפליקציה (כתובת האתר של oauth_callback)
האפליקציה שלך שולחת בקשה חתומה לשדרוג אסימון הבקשה המורשה לקוד גישה באמצעות נקודת הקצה OAuthGetAccessToken.

ספריות הלקוח של Google Data APIs מפשטות את תהליך ההרשאה בכך שהן מטפלות עבורך בפרטים שונים. מסמך זה מסביר כיצד.

רושם את יישום האינטרנט שלך

OAuth דורש חתימה דיגיטלית של כל הקריאות ל-API. Google תומכת בשיטות החתימה HMAC-SHA1 ו-RSA-SHA1. כדי לחתום על בקשות, יש קודם כל לרשום את האפליקציה ב-Google. לאחר ההרשמה, Google תמסור לך מפתח צרכן (וסוד לשימוש ב-HMAC-SHA1) ומקום שבו ניתן להעלות אישור ציבורי.

1. רישום הדומיין שלך

יש לבצע את השלבים המתוארים בהרשמה לאפליקציות מבוססות אינטרנט.

2. יצירת זוג מפתחות פרטי / זוג אישורים ציבוריים (אופציונלי)

אם ברצונך להשתמש במספר RSA-SHA1 בתור oauth_signature_method, יהיה עליך ליצור צמד אישי של מפתח ציבורי ובאישור RSA בחתימה עצמית. כדי לקבל דוגמאות איך לעשות זאת, אפשר לעיין בקטע יצירת מפתח פרטי לחתימה עצמית ואישור ציבורי (בהמשך).

עבודה עם OAuth תלת-רגלי ו-Google Data APIs: דוגמאות לספריות לקוח

בקטעים הבאים תוכלו לראות דוגמאות לשימוש בשיטות ספריית הלקוח של Google Data APIs כדי לבצע את השלבים המתוארים בקטע "עבודה עם OAuth" במסמכי התיעוד של OAuth. כל הדוגמאות במסמך הזה מניחות שהדומיין של מארח האפליקציה שלך הוא example.com.

קביעת היקף הגישה לנתונים

כל שירות של Google מגדיר ערך של scope הקובע את הגישה של אסימון לנתוני המשתמש. ערכי הטווח הזמינים מפורטים בשאלות נפוצות בנושא נתוני Google. לדוגמה, כדי להשתמש ב-Docs Document API, צריך להגדיר את scope כ-https://docs.google.com/feeds/, כפי שמצוין בשאלות נפוצות.

הערה: מגדירים את הערך scope לכתובת ה-URL הצרה ביותר, המאפשרת את הגישה הנדרשת. כך תוכלו להפחית בטעות את הגישה למידע אישי ולהדליף אותו. לדוגמה, אם רוצים לגשת לפיד פרטי המסמכים של המשתמש הנוכחי, צריך להשתמש בהיקף https://docs.google.com/feeds/default/private/full במקום בהיקף רחב יותר כמו https://docs.google.com/feeds/, שמספק גישה לכל הפידים של רשימת המסמכים.

אסימונים מרובי היקפים

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

scope=https://www.google.com/calendar/feeds/ https://docs.google.com/feeds/

קידוד כתובות URL

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

scope=https://www.google.com/calendar/feeds/ https://docs.google.com/feeds/

כשמתקשרים לספריית הלקוח, הפרמטר scope מקודד באופן אוטומטי לפי כתובת ה-URL לערך הבא:

https%3a%2f%2fwww.google.com%2fcalendar%2ffeeds%2f+https%3a%2f%2fdocs.google.com%2ffeeds%2f

אחזור אסימון בקשה

Java

עבור HMAC-SHA1, דרושה לך דרך כלשהי לשמור על סוד האסימון (התקבל בתגובה) כדי ליצור אובייקט אסימון OAuth שחוזר מדף האישור. כדי לעשות זאת, צריך להגדיר משתנה הפעלה או קובץ cookie.

import com.google.gdata.client.docs.*;
import com.google.gdata.client.authn.oauth.*;

String CONSUMER_KEY = "example.com";
String CONSUMER_SECRET = "abc123doremi";

GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters();
oauthParameters.setOAuthConsumerKey(CONSUMER_KEY);
oauthParameters.setOAuthConsumerSecret(CONSUMER_SECRET);
oauthParameters.setScope("https://docs.google.com/feeds/");
oauthParameters.setOAuthCallback("http://www.example.com/UpgradeToken.jsp");

GoogleOAuthHelper oauthHelper = new GoogleOAuthHelper(new OAuthHmacSha1Signer());
oauthHelper.getUnauthorizedRequestToken(oauthParameters);

לא נעשה שימוש ב-oauth_token_secret באמצעות RSA-SHA1, ולכן אין צורך לשמור על סוד האסימון.

import com.google.gdata.client.docs.*;
import com.google.gdata.client.authn.oauth.*;

String CONSUMER_KEY = "example.com";

GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters();
oauthParameters.setOAuthConsumerKey(CONSUMER_KEY);
oauthParameters.setScope("https://docs.google.com/feeds/");
oauthParameters.setOAuthCallback("http://www.example.com/UpgradeToken.jsp");

PrivateKey privKey = getPrivateKey("/path/to/your/rsakey.pk8");

GoogleOAuthHelper oauthHelper = new GoogleOAuthHelper(new OAuthRsaSha1Signer(privKey));
oauthHelper.getUnauthorizedRequestToken(oauthParameters);

...

public static PrivateKey getPrivateKey(String privKeyFileName) {
  File privKeyFile = new File(privKeyFileName);
  FileInputStream fis = new FileInputStream(privKeyFile);
  DataInputStream dis  = new DataInputStream(fis);

  byte[] privKeyBytes = new byte[(int) privKeyFile.length()];
  dis.read(privKeyBytes);
  dis.close();
  fis.close();

  String BEGIN = "-----BEGIN PRIVATE KEY-----";
  String END = "-----END PRIVATE KEY-----";
  String str = new String(privKeyBytes);
  if (str.contains(BEGIN) && str.contains(END)) {
    str = str.substring(BEGIN.length(), str.lastIndexOf(END));
  }

  KeyFactory fac = KeyFactory.getInstance("RSA");
  EncodedKeySpec privKeySpec = new PKCS8EncodedKeySpec(Base64.decode(str));
  return fac.generatePrivate(privKeySpec);
}

PHP

שימוש ב-HMAC-SHA1 כשיטת החתימה:

require_once 'Zend/Oauth/Consumer.php';

session_start();

$CONSUMER_KEY = 'example.com';
$CONSUMER_SECRET = 'abc123doremi';

// Multi-scoped token.
$SCOPES = array(
  'https://docs.google.com/feeds/',
  'https://spreadsheets.google.com/feeds/'
);

$oauthOptions = array(
  'requestScheme' => Zend_Oauth::REQUEST_SCHEME_HEADER,
  'version' => '1.0',
  'consumerKey' => $CONSUMER_KEY,
  'consumerSecret' => $CONSUMER_SECRET,
  'signatureMethod' => 'HMAC-SHA1',
  'callbackUrl' => 'http://myapp.example.com/access_token.php',
  'requestTokenUrl' => 'https://www.google.com/accounts/OAuthGetRequestToken',
  'userAuthorizationUrl' => 'https://www.google.com/accounts/OAuthAuthorizeToken',
  'accessTokenUrl' => 'https://www.google.com/accounts/OAuthGetAccessToken'
);

$consumer = new Zend_Oauth_Consumer($oauthOptions);

// When using HMAC-SHA1, you need to persist the request token in some way.
// This is because you'll need the request token's token secret when upgrading
// to an access token later on. The example below saves the token object as a session variable.
if (!isset($_SESSION['ACCESS_TOKEN'])) {
  $_SESSION['REQUEST_TOKEN'] = serialize($consumer->getRequestToken(array('scope' => implode(' ', $SCOPES))));
}

שימוש ב-RSA-SHA1 כשיטת החתימה:

require_once 'Zend/Crypt/Rsa/Key/Private.php';
require_once 'Zend/Oauth/Consumer.php';

session_start();

$CONSUMER_KEY = 'example.com';
$SCOPE = 'https://docs.google.com/feeds/';

$oauthOptions = array(
  'requestScheme' => Zend_Oauth::REQUEST_SCHEME_HEADER,
  'version' => '1.0',
  'consumerKey' => $CONSUMER_KEY,
  'consumerSecret' => new Zend_Crypt_Rsa_Key_Private(file_get_contents(realpath('/path/to/yourRSAPrivateKey.pem'))),
  'signatureMethod' => 'RSA-SHA1',
  'callbackUrl' => 'http://myapp.example.com/access_token.php',
  'requestTokenUrl' => 'https://www.google.com/accounts/OAuthGetRequestToken',
  'userAuthorizationUrl' => 'https://www.google.com/accounts/OAuthAuthorizeToken',
  'accessTokenUrl' => 'https://www.google.com/accounts/OAuthGetAccessToken'
);

$consumer = new Zend_Oauth_Consumer($oauthOptions);

if (!isset($_SESSION['ACCESS_TOKEN'])) {
  $_SESSION['REQUEST_TOKEN'] = serialize($consumer->getRequestToken(array('scope' => $SCOPE)));
}

Python

שימוש ב-HMAC-SHA1 כשיטת החתימה:

אם משתמשים בכיתות V2.0 ואילך המבוססות על GDClient, צריך להשתמש באחת מהשיטות הבאות:

import gdata.gauth
import gdata.docs.client

CONSUMER_KEY = 'example.com'
CONSUMER_SECRET = 'abc123doremi'
SCOPES = ['https://docs.google.com/feeds/', 'https://www.google.com/calendar/feeds/']  # example of a multi-scoped token

client = gdata.docs.client.DocsClient(source='yourCompany-YourAppName-v1')

oauth_callback_url = 'http://%s/get_access_token' % self.request.host
request_token = client.GetOAuthToken(
    SCOPES, oauth_callback_url, CONSUMER_KEY, consumer_secret=CONSUMER_SECRET)

# When using HMAC-SHA1, you need to persist the request_token in some way.
# You'll need the token secret when upgrading to an access token later on.
# In Google App Engine, you can use the AeSave helper:
# gdata.gauth.AeSave(request_token, 'myKey')

שימוש ב-RSA-SHA1 כשיטת החתימה:

...

f = open('/path/to/yourRSAPrivateKey.pem')
RSA_KEY = f.read()
f.close()

request_token = client.GetOAuthToken(SCOPES, oauth_callback_url, CONSUMER_KEY, rsa_private_key=RSA_KEY)

לחלופין, אם אתם משתמשים בכיתות הישנות של גרסה 1.0 המבוססות על GDataService, השיחות הן שונות במקצת:

import gdata.auth
import gdata.docs.service

CONSUMER_KEY = 'example.com'
CONSUMER_SECRET = 'abc123doremi'

client = gdata.docs.service.DocsService(source='yourCompany-YourAppName-v1')
client.SetOAuthInputParameters(gdata.auth.OAuthSignatureMethod.HMAC_SHA1, CONSUMER_KEY, consumer_secret=CONSUMER_SECRET)

req_token = client.FetchOAuthRequestToken()
client.SetOAuthToken(req_token)

שימוש ב-RSA-SHA1 כשיטת החתימה:

...

f = open('/path/to/yourRSAPrivateKey.pem')
RSA_KEY = f.read()
f.close()

client = gdata.docs.service.DocsService(source='yourCompany-YourAppName-v1')
client.SetOAuthInputParameters(gdata.auth.OAuthSignatureMethod.RSA_SHA1, CONSUMER_KEY, rsa_key=RSA_KEY)

SCOPES = ['https://docs.google.com/feeds/', 'https://www.google.com/calendar/feeds/']  # example of a multi-scoped token
req_token = client.FetchOAuthRequestToken(scopes=SCOPES)
client.SetOAuthToken(req_token)

‎.NET

שימוש ב-HMAC-SHA1 כשיטת החתימה:

using Google.GData.Client;

string CONSUMER_KEY = "example.com";
string CONSUMER_SECRET = "abc123doremi";

// Multi-scoped token.
string SCOPE = "https://www.google.com/calendar/feeds/ https://www.google.com/m8/feeds/";

OAuthParameters parameters = new OAuthParameters() {
  ConsumerKey = CONSUMER_KEY,
  ConsumerSecret = CONSUMER_SECRET,
  Scope = SCOPE,
  Callback = "http://myapp.example.com/access_token",
  SignatureMethod = "HMAC-SHA1"
}

OAuthUtil.GetUnauthorizedRequestToken(parameters);

שימוש ב-RSA-SHA1 כשיטת החתימה:

RSA-SHA1 is not supported yet.

הרשאת אסימון בקשה

כדי לאשר אסימון בקשה, האפליקציה שלך חייבת להפנות את המשתמש לכתובת ה-URL של OAuthAuthorizeToken, ואז תופיע בקשה להתחבר לחשבון Google שלו. למידע נוסף על כתובת ה-URL של OAuthAuthorizeToken, ניתן לעיין במאמר המלא בנושא אימות OAuth לאפליקציות אינטרנט.

כדי לבנות את כתובת ה-URL של OAuthAuthorizeToken באפליקציה שלך, צריך להשתמש בקוד הבא לכל ספריית לקוח. שימו לב: הדוגמאות האלה מבוססות על הדוגמאות הקודמות.

אחרי שיוצרים את כתובת ה-URL של דף האישור, האפליקציה יכולה להשתמש בו במגוון דרכים כדי לשלוח את המשתמש ל-handler של OAuthAuthorizeToken. הגישה הנפוצה ביותר היא להפנות את המשתמש לדף אחר או להציג קישור לדף הזה.

חילוץ האסימון מכתובת ה-URL לקריאה חוזרת (callback)

כש-Google מפנה את המשתמשים בחזרה לאפליקציה, הפונקציה oauth_token מצורפת לכתובת ה-URL "oauth_callback_url" כפרמטר של שאילתה. לאחר מכן, האפליקציה צריכה לחלץ את ערך האסימון מהפרמטר של השאילתה של כתובת ה-URL ולהגדיר מחדש את הפרמטרים של OAuth.

ספריות הלקוח מספקות שיטות נוחות לחילוץ oauth_token. הדוגמאות האלה מבוססות על הדוגמאות הקודמות.

שדרוג לאסימון גישה

השלב האחרון בריקוד אסימון האסימון הוא לשדרג את אסימון הבקשה המורשה לאסימון גישה לטווח ארוך באמצעות כתובת ה-URL של OAuthGetAccessToken, כפי שמתואר בתיעוד המלא של אימות OAuth לאפליקציות אינטרנט.

הנה כמה דוגמאות לשימוש בכל ספריות לקוח:

הערה: אם אתם משתמשים ב-HMAC-SHA1, הקפידו לשמור את סוד האסימון של אסימון הגישה לצד ערך האסימון במסד הנתונים, אחרת לא תוכלו לשחזר כראוי את הפרמטרים של OAuth לשימוש בעתיד.

שימוש באסימון גישה

אחרי שתקבלו אסימון גישה, תצטרכו להשתמש בקריאות הרגילות לספריית הלקוחות של Google Data APIs כדי לבצע אינטראקציה עם השירות. הספרייה תטפל בחתימת הבקשות ותכלול את כותרת ההרשאה המתאימה לכם. בדרך כלל, נזכרים באסימון המשתמש מתוך קובץ cookie או מסד נתונים. בעזרת הדוגמאות האלה אפשר לראות איך לשחזר את הפרמטרים של OAuth ולוודא שמתבצעת קריאה לספריית הלקוח.

Java

אם משתמשים ב-HMAC-SHA1:

  GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters();
  oauthParameters.setOAuthConsumerKey(CONSUMER_KEY);
  oauthParameters.setOAuthConsumerSecret(CONSUMER_SECRET);
  oauthParameters.setOAuthToken(ACCESS_TOKEN);
  oauthParameters.setOAuthTokenSecret(TOKEN_SECRET);

  DocsService client = new DocsService("yourCompany-YourAppName-v1");
  client.setOAuthCredentials(oauthParameters, new OAuthHmacSha1Signer());

  URL feedUrl = new URL("https://docs.google.com/feeds/default/private/full");
  DocumentListFeed resultFeed = client.getFeed(feedUrl, DocumentListFeed.class);
  for (DocumentListEntry entry : resultFeed.getEntries()) {
    System.out.println(entry.getTitle().getPlainText());
  }

ההבדל עם RSA-SHA1 הוא שאין צורך להגדיר את הסוד של אסימון הגישה ובניית אובייקט החתימה היא שונה:

  GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters();
  oauthParameters.setOAuthConsumerKey(CONSUMER_KEY);
  oauthParameters.setOAuthConsumerSecret(CONSUMER_SECRET);
  oauthParameters.setOAuthToken(ACCESS_TOKEN);

  PrivateKey privKey = getPrivateKey("/path/to/your/rsakey.pk8");  // See above for the defintion of getPrivateKey()

  DocsService client = new DocsService("yourCompany-YourAppName-v1");
  client.setOAuthCredentials(oauthParameters, new OAuthRsaSha1Signer(privKey));

  URL feedUrl = new URL("https://docs.google.com/feeds/default/private/full");
  DocumentListFeed resultFeed = client.getFeed(feedUrl, DocumentListFeed.class);
  for (DocumentListEntry entry : resultFeed.getEntries()) {
    System.out.println(entry.getTitle().getPlainText());
  }

PHP

require_once 'Zend/Gdata/Docs.php';

if (isset($_SESSION['ACCESS_TOKEN'])) {
  $accessToken = unserialize($_SESSION['ACCESS_TOKEN']);
} else {
  exit;
}


/*  Or, you could set an existing token (say one stored from your database). For HMAC-SHA1:
$accessToken = new Zend_Oauth_Token_Access();
$accessToken->setToken('1/AQfoI-qJDqkvvkf216Gc2g');
$accessToken->setTokenSecret('2c26GLW250tZiQ');
*/

$httpClient = $accessToken->getHttpClient($oauthOptions);
$client = new Zend_Gdata_Docs($httpClient, "yourCompany-YourAppName-v1");

// Retrieve user's list of Google Docs
$feed = $client->getDocumentListFeed();
foreach ($feed->entries as $entry) {
  echo "$entry->title\n";
}

Python

קטע הקוד הזה מבוסס על ההנחה שכבר הבאתם אסימון גישה (באמצעות HMAC-SHA1) ואתם זוכרים את המפתח/הסוד של האסימון לשימוש עתידי.

אם משתמשים בכיתות V2.0 ואילך המבוססות על GDClient, צריך להשתמש באחת מהשיטות הבאות:

client = gdata.docs.client.DocsClient(source='yourCo-yourAppName-v1')
client.auth_token = gdata.gauth.OAuthHmacToken(CONSUMER_KEY, CONSUMER_SECRET, TOKEN,
                                               TOKEN_SECRET, gdata.gauth.ACCESS_TOKEN)
feed = client.GetDocList()
for entry in feed.entry:
  print entry.title.text

אם אתם משתמשים בכיתות הישנות של גרסה 1.0 המבוססות על GDataService, עליכם להשתמש ב:

client = gdata.docs.service.DocsService(source='yourCompany-YourAppName-v1')
client.SetOAuthInputParameters(SIG_METHOD, CONSUMER_KEY, consumer_secret=CONSUMER_SECRET)

# the token key and secret should be recalled from your database
client.SetOAuthToken(gdata.auth.OAuthToken(key=TOKEN, secret=TOKEN_SECRET))

feed = client.GetDocumentListFeed()
for entry in feed.entry:
  print entry.title.text

‎.NET

אם משתמשים ב-HMAC-SHA1:

OAuthParameters parameters = new OAuthParameters() {
  ConsumerKey = CONSUMER_KEY,
  ConsumerSecret = CONSUMER_SECRET,
  Token = ACCESS_TOKEN,
  TokenSecret = TOKEN_SECRET
}

GOAuthRequestFactory requestFactory = new GOAuthRequestFactory("writely", APPLICATION_NAME, parameters);

DocsService service = new DocsService(APPLICATION_NAME);
service.RequestFactory = requestFactory;

DocumentsListQuery query = new DocumentsListQuery();
DocumentsFeed feed = service.Query(query);
foreach (DocumentEntry entry in feed.Entries) {
  Console.WriteLine(entry.Title.Text);
}

ההבדל עם RSA-SHA1 הוא שאין צורך להגדיר את הסוד של אסימון הגישה ובניית אובייקט החתימה היא שונה:

RSA-SHA1 is not supported yet.

משאבים ודגימות OAuth נוספים תלת-רגליים

דוגמאות ל-OAuth בבלוג הטיפים של Google Data API
מאמר: שימוש ב-OAuth עם ממשקי ה-API של נתונים של Google
דוגמה לספריית לקוחות ב-Python
ספריית לקוח ב-Python דוגמה ל-Google App Engine
דוגמה לספריית לקוחות ב-Java
ספריית לקוח Java דוגמה ל-Google App Engine
דוגמת דוגמה לספריית לקוחות של PHP
מסמכי התיעוד של אימות OAuth לאפליקציות אינטרנט
תיעוד OAuth.net

חזרה למעלה

2 OAuth OAuth

OAuth דו-רגלי מאפשר לאפליקציות מהימנות לגשת לנתוני Google של המשתמשים ללא מעורבות ישירה שלהם. שתי קבוצות של מפתחות יכולות להשתמש ב-OAuth דו-רגלי:

מנהלי דומיין ב-G Suite: מנהלי מערכת יכולים ליצור סקריפטים ואפליקציות מותאמות אישית שמנהלות את נתוני המשתמשים של הדומיין שלהם באמצעות Google Data APIs. מידע נוסף על ניהול המפתח והסוד שמשויכים לדומיין שלך ב-G Suite והענקת בקרת גישה גלובלית זמין במאמר "ניהול המפתח והסוד של OAuth".

ספקי תוכנה של צד שלישי: ספקים יכולים להציע אפליקציות שמשתמשות ב-OAuth דו-רגלי לשילוב עם G Suite. אפשר להעניק גישה לאפליקציות של צד שלישי בדף הלקוח של ניהול ה-API, או להתקין אותן מ-G Suite Marketplace.

בהתאם למהלך ההרשאה הרגיל, אין צורך באסימון גישה (שנקרא גם OAuth תלת-רגלי).

הדוגמאות הבאות של ספריית הלקוח מדגימות איך להגדיר את הלקוח לשימוש ב-2 Legged OAuth באמצעות HMAC-SHA1.

Java

import com.google.gdata.client.docs.*;
import com.google.gdata.client.authn.oauth.*;

String CONSUMER_KEY = "example.com";
String CONSUMER_SECRET = "abc123doremi";

GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters();
oauthParameters.setOAuthConsumerKey(CONSUMER_KEY);
oauthParameters.setOAuthConsumerSecret(CONSUMER_SECRET);

DocsService client = new DocsService("yourCompany-YourAppName-v1");
client.setOAuthCredentials(oauthParameters, new OAuthHmacSha1Signer());

// Retrieve user's list of Google Docs
String user = "any.user@anydomain.com";
URL feedUrl = new URL("https://docs.google.com/feeds/default/private/full" +
                      "?xoauth_requestor_id=" + user);

DocumentListFeed resultFeed = client.getFeed(feedUrl, DocumentListFeed.class);
for (DocumentListEntry entry : resultFeed.getEntries()) {
  System.out.println(entry.getTitle().getPlainText());
}

PHP

require_once 'Zend/Oauth/Consumer.php';
require_once 'Zend/Gdata/Docs.php';

$CONSUMER_KEY = 'example.com';
$CONSUMER_SECRET = 'abc123doremi';
$USER = 'any.user@anydomain.com';

$oauthOptions = array(
    'requestScheme' => Zend_Oauth::REQUEST_SCHEME_HEADER,
    'version' => '1.0',
    'signatureMethod' => 'HMAC-SHA1',
    'consumerKey' => $CONSUMER_KEY,
    'consumerSecret' => $CONSUMER_SECRET
);

$consumer = new Zend_Oauth_Consumer($oauthOptions);
$token = new Zend_Oauth_Token_Access();
$httpClient = $token->getHttpClient($oauthOptions);

$client = new Zend_Gdata_Docs($httpClient);

// Retrieve user's list of Google Docs
$feed = $client->getDocumentListFeed('https://docs.google.com/feeds/default/private/full?xoauth_requestor_id=' . urlencode($USER));
foreach ($feed->entries as $entry) {
  echo "$entry->title\n";
}

Python

אם משתמשים בכיתות V2.0 ואילך המבוססות על GDClient, צריך להשתמש באחת מהשיטות הבאות:

import gdata.gauth
import gdata.docs.client

CONSUMER_KEY = 'example.com'
CONSUMER_SECRET = 'abc123doremi'
requestor_id = 'any.user@anydomain.com'

client = gdata.docs.client.DocsClient(source='yourCompany-YourAppName-v1')
client.auth_token = gdata.gauth.TwoLeggedOAuthHmacToken(
    CONSUMER_KEY, CONSUMER_SECRET, requestor_id)

# Retrieve user's list of Google Docs
feed = client.GetDocList()
for entry in feed.entry:
  print entry.title.text

אם אתם משתמשים בכיתות הישנות של גרסה 1.0 המבוססות על GDataService, עליכם להשתמש ב:

import gdata.auth
import gdata.docs.service

CONSUMER_KEY = 'example.com'
CONSUMER_SECRET = 'abc123doremi'
SIG_METHOD = gdata.auth.OAuthSignatureMethod.HMAC_SHA1

requestor_id = 'any.user@anydomain.com'

client = gdata.docs.service.DocsService(source='yourCompany-YourAppName-v1')
client.SetOAuthInputParameters(SIG_METHOD, CONSUMER_KEY, consumer_secret=CONSUMER_SECRET,
                               two_legged_oauth=True, requestor_id=requestor_id)

# Retrieve user's list of Google Docs
feed = client.GetDocumentListFeed()
for entry in feed.entry:
  print entry.title.text

# Change to another user on your domain
client.GetOAuthInputParameters().requestor_id = 'another.user@example.com'

‎.NET

using Google.GData.Client;
using Google.GData.Documents;

// Create an OAuth factory to use
GOAuthRequestFactory requestFactory = new GOAuthRequestFactory("writely", "yourCompany-YourAppName-v1");
requestFactory.ConsumerKey = "example.com";
requestFactory.ConsumerSecret = "abc123doremi";

String user = "any.user@anydomain.com";

DocumentsService client = new DocumentsService("yourCompany-YourAppName-v1");
client.RequestFactory = requestFactory;

// Retrieve user's list of Google Docs
DocumentsListQuery query = new DocumentsListQuery();
query.Uri = new OAuthUri("https://docs.google.com/feeds/default/private/full", user, requestFactory.ConsumerKey);

DocumentsFeed feed = client.Query(query);

foreach (DocumentEntry entry in feed.Entries)
{
  Console.WriteLine(entry.Title.Text);
}

משאבים ודגימות OAuth נוספים דו-רגליים

שתי דוגמאות OAuth רגלי בבלוג הטיפים של Google Data API
ספריית לקוח Java דוגמה ל-OAuth דו-רגלי
ספריית לקוח Python ב-twoLeggedOAuthExample (עבור מחלקות client.py) או 2_legged_oauth דוגמה (עבור מחלקות service.py)
ספריית לקוח עם הסיומת .NET דוגמה ל-OAuth דו-רגלי
תיעוד OAuth בעל שתי רגליים

יצירת מפתח פרטי לחתימה עצמית ואישור ציבורי

המפתח הפרטי משמש ליצירת חתימה, וצריך להוסיף אותה לכל בקשה. המפתח הציבורי המוטמע באישור משמש את Google לאימות החתימה. המפתח הציבורי חייב להיות מפתח RSA בן 1024 ביט המקודד באישור X.509 בפורמט PEM. את האישור יש לשלוח ל-Google בזמן הרישום.

בקטעים הבאים תוכלו למצוא דוגמאות ליצירת מפתחות ואישורים באמצעות שני כלים ספציפיים: כלי השירות OpenSSL והכלי keytool של Java.

הדוגמאות האלה לא ספציפיות לממשקי Google Data API. אפשר להשתמש באותם כלים כדי ליצור מפתחות לכל מטרה.

הדוגמאות מבוססות על ההנחה שהחברה שלכם נקראת My_Company, וממוקמת במאונטיין וויו, קליפורניה, ארה"ב, עם שם הדומיין example.com.

יצירת מפתחות באמצעות OpenSSL

כדי ליצור זוג מפתחות RSA ואת האישור התואם, ניתן להשתמש בפקודה הבאה:

# Generate the RSA keys and certificate
openssl req -x509 -nodes -days 365 -newkey rsa:1024 -sha1 -subj \
  '/C=US/ST=CA/L=Mountain View/CN=www.example.com' -keyout \
  myrsakey.pem -out /tmp/myrsacert.pem

אזהרה: הוספת הפרמטר -nodes יוצרת מפתח פרטי ללא סיסמה כדי להגן עליו. עם זאת, כדאי להסיר את הפרמטר הזה מטעמי אבטחה.

הפרמטר -sha1 מציין שהמפתח ישמש ליצירת חתימות SHA1.

הפרמטר -subj מציין את זהות האפליקציה שהאישור מייצג.

הפרמטר -keyout מציין את הקובץ שיכיל את המפתחות. הקובץ מכיל מידע רגיש, צריך להגן עליו ולא לשתף אותו עם אף אחד.

הפרמטר -out מציין את הקובץ שיכיל את האישור בפורמט PEM (ניתן לשלוח אותו אל Google בזמן ההרשמה).

יצירת מפתחות ללקוח NET.

מסגרת NET לא מבינה מפתחות או אישורים ששמורים בפורמט PEM. לכן, יש לבצע שלב נוסף לאחר יצירת קובץ ה- .pem:

openssl pkcs12 -export -in test_cert.pem -inkey myrsacert.pem -out myrsacert.pfx -name "Testing Certificate"

השלב הזה יוצר קובץ PFX מהמפתח הפרטי ומהאישור שלך. ניתן לייבא את הקובץ לספריית הלקוח NET .כדי לחתום באופן דיגיטלי על בקשות שנשלחו לממשקי API של Google Data.

יצירת מפתחות עבור לקוח Java

לקוח Java מקבל מפתחות פרטיים בפורמט PKCS#8. אחרי שיוצרים מפתח או אישור לפי ההוראות שלמעלה, יוצרים קובץ .pk8 מקובץ ה- .pem שנוצר:

openssl pkcs8 -in myrsakey.pem -topk8 -nocrypt -out myrsakey.pk8

לחלופין, תוכלו להשתמש במאגר המפתחות של Java ובכלי המפתח כדי ליצור זוג מפתחות RSA ואת האישור התואם. משתמשים בפקודה הבאה:

# Generate the RSA keys and certificate
keytool -genkey -v -alias Example -keystore ./Example.jks\
  -keyalg RSA -sigalg SHA1withRSA\
  -dname "CN=www.example.com, OU=Engineering, O=My_Company, L=Mountain  View, ST=CA, C=US"\
  -storepass changeme -keypass changeme

אזהרה: "changeme" אינה סיסמה טובה, זוהי רק דוגמה.

הפרמטר -dname מציין את זהות האפליקציה שהאישור מייצג. הפרמטר -storepass מציין את הסיסמה כדי להגן על מאגר המפתחות. הפרמטר -keypass מציין את הסיסמה כדי להגן על המפתח הפרטי.

כדי לכתוב את האישור בקובץ שבו ניתן להשתמש בכלי ManageDomains, משתמשים בפקודה הבאה:

# Output the public certificate to a file
keytool -export -rfc -keystore ./Example.jks -storepass changeme \
  -alias Example -file mycert.pem

חזרה למעלה