تحذير: تتعلق هذه الصفحة بواجهات برمجة التطبيقات القديمة من Google، وهي واجهات برمجة التطبيقات لبيانات Google؛ وهي مرتبطة فقط بواجهات برمجة التطبيقات المدرجة في دليل Google Data APIs، والتي تم استبدال العديد منها بواجهات برمجة تطبيقات أحدث. للحصول على معلومات حول واجهة برمجة تطبيقات جديدة، اطلع على وثائق واجهة برمجة التطبيقات الجديدة. للحصول على معلومات حول تفويض الطلبات باستخدام واجهة برمجة تطبيقات أحدث، اطلع على مصادقة حسابات Google وتفويضها.
يصف هذا المستند كيفية استخدام مكتبات برامج واجهة برمجة تطبيقات بيانات Google للاتصال بـ مصادقة OAuth لتطبيقات الويب من Google.
تسمح واجهة OAuth لتطبيق يستند إلى الويب بالدخول إلى خدمة Google بالنيابة عن المستخدم. للحفاظ على مستوى عالٍ من الأمان، يمكّن بروتوكول OAuth التطبيق من الحصول على رمز دخول بدون الحاجة إلى معالجة معلومات تسجيل الدخول لحساب المستخدم.
توفر مكتبات برامج Google Data API طرقًا لمساعدتك على استخدام OAuth في تطبيق الويب. وعلى وجه التحديد، هناك طرق لإنشاء الرمز المميز للطلب وتفويض الرمز المميز للطلب وتبادل رمز الطلب المميز مع رمز الدخول. تعالج المكتبات أيضًا خوارزميات التوقيع الضرورية عند تقديم طلبات إلى خدمة بيانات Google.
الجمهور
تم إعداد هذا المستند للمبرمجين الذين يريدون لتطبيقاتهم المستندة إلى الويب الدخول إلى خدمات Google بالنيابة عن المستخدمين، وذلك باستخدام مكتبات برامج Google Data APIs.
يفترض هذا المستند أنك على دراية بواجهة OAuth والعملية العامة لدمج OAuth في تطبيق الويب. للحصول على وصف كامل لبروتوكول OAuth، اطلع على مصادقة OAuth لتطبيقات الويب أو المواصفات الرسمية على oauth.net.
استخدام بروتوكول OAuth الثلاثي وواجهات برمجة التطبيقات لبيانات Google بدون مكتبات العملاء
إذا كنت تريد أن يتفاعل تطبيق الويب مع خدمة بيانات Google باستخدام OAuth كطريقة تفويض، يكون كل ما تحتاج إلى معرفته في مصادقة OAuth لتطبيقات الويب. وليست هناك حاجة لاستخدام مكتبات برامج Google Data APIs إذا لم تكن تريد ذلك.
في ما يلي مخطط تفصيلي لكيفية مصادقة التطبيق لأحد المستخدمين باستخدام OAuth:
- يُرسِل تطبيقك طلبًا موقَّعًا لجلب رمز مميز مميّز لطلب OAuth من نقطة النهاية
OAuthRequestToken
. - يعيد تطبيقك توجيه المستخدم إلى عنوان URL المناسب على
OAuthAuthorizeToken
لتفويض الرمز المميز للطلب. - عند منح إمكانية الدخول، تتم إعادة توجيه المستخدم إلى تطبيقك (عنوان URL لـ
oauth_callback
) - يُرسِل تطبيقك طلبًا موقَّعًا لترقية الرمز المميز للطلب المعتمَد إلى رمز دخول باستخدام نقطة النهاية
OAuthGetAccessToken
.
تبسّط مكتبات برامج "Google Data APIs" عملية التفويض هذه من خلال معالجة تفاصيل مختلفة لك. يشرح هذا المستند كيفية تنفيذ ذلك.
تسجيل تطبيق الويب
يتطلب OAuth توقيع جميع طلبات البيانات من واجهة برمجة التطبيقات رقميًا. تدعم Google طريقتي التوقيع HMAC-SHA1
وRSA-SHA1
. للتوقيع على الطلبات، يحتاج تطبيقك أولاً إلى التسجيل باستخدام Google. بعد التسجيل، ستزوّدك Google بمفتاح مستهلك (وسرّي للاستخدام مع HMAC-SHA1
)، ومكان لتحميل شهادة عامة.
1- تسجيل نطاقك
يُرجى اتباع الخطوات الموضحة في التسجيل للتطبيقات المستندة إلى الويب.
2- إنشاء زوج من المفاتيح الخاصة / الشهادات العامة (اختياري)
إذا اخترت استخدام RSA-SHA1
باعتباره oauth_signature_method
، ستحتاج إلى إنشاء مفتاحَي ترميز خاصَين RSA
وتوقيع الشهادة العلني للتوقيع الذاتي. راجع إنشاء مفتاح خاص للتوقيع الذاتي وشهادة عامة
(أدناه) للحصول على أمثلة حول كيفية إجراء ذلك.
العمل باستخدام بروتوكول OAuth الثلاثي وواجهات برمجة التطبيقات لبيانات Google: أمثلة مكتبة العملاء
تعرض الأقسام التالية أمثلة لاستخدام طرق مكتبة برامج Google Data APIs لاتباع الخطوات الموضحة في القسم "العمل مع OAuth" في مستندات OAuth. تفترض جميع الأمثلة في هذا المستند أن نطاق مضيف التطبيق هو example.com
.
تحديد نطاق الدخول إلى البيانات
تحدّد كل خدمة من خدمات Google قيمة scope
تحدّد وصول رمز مميّز إلى بيانات المستخدم. يتم سرد قيم النطاقات المتاحة في الأسئلة الشائعة حول بيانات Google. على سبيل المثال، لاستخدام واجهة برمجة التطبيقات لقائمة المستندات، اضبط scope
على https://docs.google.com/feeds/
، كما هو موضح في الأسئلة الشائعة.
ملاحظة: اضبط القيمة scope
على أضيق عنوان URL يسمح بالوصول الذي تحتاج إليه. وهذا يقلل من فرصة الحصول على البيانات الشخصية وتسربها بدون قصد. على سبيل المثال، إذا كنت تريد الدخول إلى خلاصة قائمة المستندات الخاصة بالمستخدم الحالي، فاستخدم النطاق https://docs.google.com/feeds/default/private/full
بدلاً من نطاق أوسع مثل https://docs.google.com/feeds/
، الذي يوفر إمكانية الوصول إلى جميع خلاصات قائمة المستندات.
الرموز المميزة متعددة النطاقات
لإنشاء رموز مميزة تصل إلى واجهات برمجة تطبيقات متعددة لبيانات Google، افصل بين كل نطاق بحرف مسافة. يؤدي المثال التالي إلى إنشاء رمز مميز يمكنه الدخول إلى كل من بيانات محرّر مستندات Google وبيانات تقويم Google للمستخدم.
scope=https://www.google.com/calendar/feeds/ https://docs.google.com/feeds/
تشفير عنوان URL
يجب أن تكون الأحرف بخلاف ASCII التي تظهر في عناوين URL، بما في ذلك النقطتين والشرطة المائلة والمسافات، بترميز URL ليتم نقلها عبر HTTP. تعمل مكتبات برامج Google Data API على ترميز المعلمات تلقائيًا نيابةً عنك، بحيث يمكنك ببساطة استخدام سلاسل غير مشفرة باستخدام عناوين URL عند تعيين قيم لمعلمات. على سبيل المثال، يمكنك إجراء التعيين التالي في شفرتك:
scope=https://www.google.com/calendar/feeds/ https://docs.google.com/feeds/
عند استدعاء مكتبة العميل، يتم بعد ذلك ترميز المعلمة
scope
تلقائيًا إلى القيمة التالية:
https%3a%2f%2fwww.google.com%2fcalendar%2ffeeds%2f+https%3a%2f%2fdocs.google.com%2ffeeds%2f
جلب رمز مميز للطلب
لغة Java
بالنسبة إلى HMAC-SHA1
، تحتاج إلى طريقة للاحتفاظ بسر الرمز المميز (الذي يتم الحصول عليه في الاستجابة) لإنشاء كائن رمز OAuth مميز يعود من صفحة الموافقة. لإجراء ذلك، عليك ضبط متغيّر الجلسة أو ملف تعريف الارتباط.
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);
باستخدام RSA-SHA1
، لا يتم استخدام oauth_token_secret
، لذلك ليست هناك حاجة للاحتفاظ بسر الرمز المميز.
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
كطريقة التوقيع:
إذا كنت تستخدم فئات أحدث من الإصدار 2.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 لصفحة الموافقة، يمكن للتطبيق استخدامه بعدة طرق لإرسال المستخدم إلى معالج OAuthAuthorizeToken
. والمنهج الأكثر شيوعًا هو إعادة توجيه المستخدم أو عرض رابط إلى هذه الصفحة.
لغة Java
بالنسبة إلى HMAC-SHA1
:
String approvalPageUrl = oauthHelper.createUserAuthorizationUrl(oauthParameters); System.out.println(approvalPageUrl);
بالنسبة إلى RSA-SHA1
:
String approvalPageUrl = oauthHelper.createUserAuthorizationUrl(oauthParameters); System.out.println(approvalPageUrl);
لغة PHP
// If on a G Suite domain, use your domain for the hd param (e.g. 'example.com'). $approvalUrl = $consumer->getRedirectUrl(array('hd' => 'default')); echo "<a href=\"$approvalUrl\">Grant access</a>";
بدلاً من ذلك، يمكنك ببساطة إعادة التوجيه إلى عنوان URL للموافقة:
// If on a G Suite domain, use your domain for the hd param (e.g. 'example.com'). $consumer->redirect(array('hd' => 'default'));
لغة Python
إذا كنت تستخدم فئات أحدث من الإصدار 2.0 أو الإصدارات الأحدث استنادًا إلى GDClient، فاستخدم:
# req_token is from previous call to client.GetOAuthToken() domain = None # If on a G Suite domain, use your domain (e.g. 'example.com'). self.redirect(request_token.generate_authorization_url(google_apps_domain=domain))
إذا كنت تستخدم فئات الإصدار 1.0 الأقدم بناءً على GDataService، فستختلف العملية قليلاً.
# req_token is from previous call to client.FetchOAuthRequestToken() oauth_callback_url = 'http://%s/get_access_token' % self.request.host self.redirect(client.GenerateOAuthAuthorizationURL(callback_url=oauth_callback_url))
NET.
string authorizationUrl = OAuthUtil.CreateUserAuthorizationUrl(parameters); Console.WriteLine(authorizationUrl);
استخراج الرمز المميز من عنوان URL لرد الاتصال
عندما تُعيد Google التوجيه إلى تطبيقك، يتم إلحاق oauth_token
بعنوان URL "oauth_callback_url
" كمَعلمة طلب البحث.
بعد ذلك، يجب أن يستخرج تطبيقك قيمة الرمز المميز من معلمة طلب البحث لعنوان URL ويعيد إنشاء معلمات oauth.
توفر مكتبات العملاء طرقًا مناسبة لاستخراج oauth_token
. وتستند هذه النماذج إلى الأمثلة السابقة.
لغة Java
إذا اخترت الاحتفاظ بسر الرمز المميز في عنوان URL لرد الاتصال (عند استخدام HMAC-SHA1
):
GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters(); oauthParameters.setOAuthConsumerKey(CONSUMER_KEY); oauthParameters.setOAuthConsumerSecret(CONSUMER_SECRET); GoogleOAuthHelper oauthHelper = new GoogleOAuthHelper(new OAuthHmacSha1Signer()); oauthHelper.getOAuthParametersFromCallback(request.getQueryString(), oauthParameters);
الاختلاف الوحيد مع RSA-SHA1
هو طريقة التوقيع:
GoogleOAuthParameters oauthParameters = new GoogleOAuthParameters(); oauthParameters.setOAuthConsumerKey(CONSUMER_KEY); PrivateKey privKey = getPrivateKey("/path/to/your/rsakey.pk8"); GoogleOAuthHelper oauthHelper = new GoogleOAuthHelper(new OAuthRsaSha1Signer(privKey)); oauthHelper.getOAuthParametersFromCallback(request.getQueryString(), oauthParameters);
لغة PHP
هذه الخطوة ليست ضرورية عند استخدام مكتبة PHP.
لغة Python
إذا كنت تستخدم فئات أحدث من الإصدار 2.0 أو الإصدارات الأحدث استنادًا إلى GDClient، فاستخدم:
# Recall request_token. In Google App Engine, use AeLoad(): # saved_request_token = gdata.gauth.AeLoad('myKey') request_token = gdata.gauth.AuthorizeRequestToken(saved_request_token, self.request.uri)
إذا كنت تستخدم الصفوف الأقدم من الإصدار 1.0 بناءً على GDataService، فاستخدم:
oauth_token = gdata.auth.OAuthTokenFromUrl(self.request.uri) if oauth_token: oauth_token.secret = # TODO: recall saved request_token and set the token secret here. oauth_token.oauth_input_params = gdata.auth.OAuthInputParams( gdata.auth.OAuthSignatureMethod.HMAC_SHA1, CONSUMER_KEY, consumer_secret=CONSUMER_SECRET) client.SetOAuthToken(oauth_token) else: print 'No oauth_token found in the URL'
هذه العملية مماثلة لـ RSA-SHA1
، ولكن بدون سر الرمز المميز:
oauth_token = gdata.auth.OAuthTokenFromUrl(self.request.uri) if oauth_token: oauth_token.oauth_input_params = gdata.auth.OAuthInputParams( gdata.auth.OAuthSignatureMethod.RSA_SHA1, CONSUMER_KEY, rsa_key=RSA_KEY) client.SetOAuthToken(oauth_token) else: print 'No oauth_token found in the URL'
NET.
إذا اخترت الاحتفاظ بسر الرمز المميز في عنوان URL لمعاودة الاتصال:
OAuthUtil.UpdateOAuthParametersFromCallback(url, parameters);
الترقية إلى رمز دخول
الخطوة الأخيرة في رقصة رمز OAuth المميز هي ترقية الرمز المميز للطلب المصرح به إلى رمز دخول قديم باستخدام عنوان URL لـ OAuthGetAccessToken
، كما هو موضح في وثائق مصادقة OAuth لتطبيقات الويب الكاملة.
في ما يلي بعض الأمثلة على استخدام كل مكتبة من مكتبات العملاء:
لغة Java
String accessToken = oauthHelper.getAccessToken(oauthParameters); // You can also pull the OAuth token string from the oauthParameters: // String accessToken = oauthParameters.getOAuthToken(); System.out.println("OAuth Access Token: " + accessToken); String accessTokenSecret = oauthParameters.getOAuthTokenSecret(); System.out.println("OAuth Access Token's Secret: " + accessTokenSecret);
لغة PHP
if (!isset($_SESSION['ACCESS_TOKEN'])) { if (!empty($_GET) && isset($_SESSION['REQUEST_TOKEN'])) { $_SESSION['ACCESS_TOKEN'] = serialize($consumer->getAccessToken($_GET, unserialize($_SESSION['REQUEST_TOKEN']))); } }
لغة Python
إذا كنت تستخدم فئات أحدث من الإصدار 2.0 أو الإصدارات الأحدث استنادًا إلى GDClient، فاستخدم:
# Upgrade the token and save in the user's datastore access_token = client.GetAccessToken(request_token) # If you're using Google App Engine, you can call the AeSave() method to save # the access token under the current logged in user's account. #gdata.gauth.AeSave(access_token, token_key)
إذا كنت تستخدم الصفوف الأقدم من الإصدار 1.0 بناءً على GDataService، فاستخدم:
access_token = client.UpgradeToOAuthAccessToken() # calls SetOAuthToken() for you
إذا كنت تستخدم gdata.gauth.AeSave()
على App Engine، فسيتم تخزين الرمز المميز والرمز المميز لك ضمن المستخدم الحالي الذي سجّل الدخول.
NET.
OAuthUtil.GetAccessToken(parameters); // If you want to extract the OAuth Token/TokenSecret from the OAuthParameters instance: string accessToken = parameter.Token; Console.WriteLine("OAuth Access Token: " + accessToken); string accessTokenSecret = parameter.TokenSecret; Console.WriteLine("OAuth Access Token's Secret: " + accessTokenSecret);
ملاحظة: إذا كنت تستخدم HMAC-SHA1
، فاحرص على حفظ سر الرمز المميز للدخول إلى جانب قيمة الرمز المميز في قاعدة البيانات، وإلا فلن تتمكن من إعادة إنشاء معلمات OAuth بشكل صحيح للاستخدام لاحقًا.
استخدام رمز الدخول
بعد الحصول على رمز الدخول، يمكنك استخدام استدعاءات مكتبة عميل Google Data APIs القياسية للتفاعل مع الخدمة. وستعتني المكتبة بتوقيع الطلبات وتضمين رأس التفويض الصحيح بالنيابة عنك. ستستعيد عادةً الرمز المميز للمستخدم من ملف تعريف ارتباط أو قاعدة بيانات. توضح هذه الأمثلة كيفية إعادة إنشاء معلمات 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
) وأنك تسترجع هذا المفتاح/الرمز المميز للاستخدام لاحقًا.
إذا كنت تستخدم فئات أحدث من الإصدار 2.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
- مقالة: استخدام OAuth مع Google Data APIs
- نموذج مكتبة عميل Python
- مكتبة برامج Python نموذج Google App Engine
- نموذج مكتبة برامج جافا
- مكتبة برامج جافا نموذج Google App Engine
- نموذج مكتبة برامج Zend PHP
- وثائق مصادقة OAuth لتطبيقات الويب
- وثائق OAuth.net
بروتوكول OAuth الثنائي
يسمح بروتوكول OAuth الثنائي للتطبيقات الموثوق بها بالوصول إلى بيانات Google للمستخدمين بدون تدخلهم المباشر. يمكن لمجموعتين رئيسيتين استخدام بروتوكول OAuth الثنائي:
مشرفو نطاق G Suite: يمكن للمشرفين إنشاء نصوص برمجية وتطبيقات مُخصَّصة تدير بيانات المستخدم لنطاقهم من خلال Google Data APIs. للتعرّف على إدارة المفتاح والسر المقترنين بنطاقك في G Suite، ومنح إمكانية التحكم في الوصول العام، راجع "إدارة مفتاح وسر OAuth".
مورّدو البرامج الخارجية: قد يقدّم المورّدون تطبيقات تستخدم بروتوكول OAuth الثنائي للتكامل مع G Suite. يمكن منح حق الوصول لتطبيقات الجهات الخارجية في صفحة برنامج "إدارة واجهة برمجة التطبيقات" أو من خلال التثبيت من سوق G Suite.
لا يلزم الحصول على رمز دخول وفقًا لتدفق التفويض العادي (يُشار إليه أيضًا باسم بروتوكول OAuth الثلاثي).
توضح نماذج مكتبة البرامج التالية كيفية إعداد البرنامج لاستخدام بروتوكول 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
إذا كنت تستخدم فئات أحدث من الإصدار 2.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
- مكتبة عميل جافا نموذج بروتوكول OAuth الثنائي
- مكتبة برامج Python TwoLeggedOAuthExample (للفئات client.py) أو 2_leg_oauth sample (لفئات service.py)
- مكتبة عميل .NET نموذج بروتوكول OAuth الثنائي
- وثائق بروتوكول OAuth الثنائي
إنشاء مفتاح خاص وشهادة عامة للتوقيع الذاتي
يتم استخدام المفتاح الخاص لإنشاء توقيع يجب تضمينه مع كل طلب. تستخدم Google المفتاح العام المضمّن في الشهادة للتحقّق من التوقيع. يجب أن يكون المفتاح العام مفتاح RSA 1024 بت مُشفَّر في شهادة X.509 بتنسيق PEM. ويجب إرسال الشهادة إلى Google عند التسجيل.
تقدم الأقسام التالية أمثلة على كيفية إنشاء المفاتيح والشهادات باستخدام أداتين خاصتين: الأداة OpenSSL
وأداة keytool
البرمجية في جافا.
لا تتعلق هذه الأمثلة بواجهات برمجة التطبيقات لبيانات Google، ويمكنك استخدام الأدوات نفسها لإنشاء مفاتيح لأي غرض.
تفترض الأمثلة أن شركتك تسمى 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 لتوقيع الطلبات التي تم إجراؤها رقميًا في واجهات برمجة تطبيقات بيانات Google.
جارٍ إنشاء المفاتيح لبرنامج جافا
يقبل برنامج جافا المفاتيح الخاصة بتنسيق PKCS#8. بعد إنشاء مفتاح/شهادة باستخدام الإرشادات أعلاه، أنشئ ملف .pk8 من ملف pem .الذي تم إنشاؤه:
openssl pkcs8 -in myrsakey.pem -topk8 -nocrypt -out myrsakey.pk8
بدلاً من ذلك، يمكنك استخدام مخزن مفاتيح جافا وأداة الأداة المساعدة لإنشاء زوج من مفاتيح 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
كلمة المرور لحماية المفتاح الخاص.
لكتابة الشهادة في ملف يمكن استخدامه في أداة إدارة النطاقات، استخدِم الأمر التالي:
# Output the public certificate to a file keytool -export -rfc -keystore ./Example.jks -storepass changeme \ -alias Example -file mycert.pem