استخدام OAuth 2.0 لتطبيقات الخادم إلى الخادم

يدعم نظام Google OAuth 2.0 التفاعلات من خادم إلى خادم مثل تلك التي تتم بين تطبيق ويب وخدمة Google. لهذا السيناريو تحتاج إلى حساب خدمة، وهو الحساب الذي ينتمي إلى التطبيق الخاص بك بدلا من المستخدم النهائي الفردي. يستدعي تطبيقك Google APIs نيابة عن حساب الخدمة ، لذلك لا يشارك المستخدمون بشكل مباشر. يُطلق على هذا السيناريو أحيانًا اسم "OAuth الثنائي" أو "2LO". (يشير المصطلح ذي الصلة "بروتوكول OAuth الثلاثي" إلى السيناريوهات التي يستدعي فيها تطبيقك واجهات برمجة تطبيقات Google نيابةً عن المستخدمين ، والتي تتطلب أحيانًا موافقة المستخدم.)

عادةً ما يستخدم التطبيق حساب خدمة عندما يستخدم التطبيق واجهات برمجة تطبيقات Google للعمل مع بياناته الخاصة بدلاً من بيانات المستخدم. على سبيل المثال ، قد يستخدم التطبيق الذي يستخدم Google Cloud Datastore لاستمرار البيانات حساب خدمة لمصادقة مكالماته إلى Google Cloud Datastore API.

مشرفي نطاق Google مساحة عمل يمكن أيضا منح خدمة حسابات السلطة واسع المجال لبيانات المستخدم الوصول بالنيابة عن المستخدمين في المجال.

يصف هذا المستند كيف يمكن لأحد التطبيقات إكمال تدفق OAuth 2.0 من خادم إلى خادم باستخدام مكتبة عميل Google APIs (موصى به) أو HTTP.

ملخص

لدعم التفاعلات خادم إلى خادم، أولا إنشاء حساب خدمة للمشروع الخاص بك في API Console. إذا كنت ترغب في الوصول إلى بيانات المستخدم للمستخدمين في حساب Google Workspace الخاص بك ، فقم بتفويض الوصول على مستوى النطاق إلى حساب الخدمة.

بعد ذلك ، يستعد تطبيقك لإجراء مكالمات API مصرح بها باستخدام بيانات اعتماد حساب الخدمة لطلب رمز وصول من خادم مصادقة OAuth 2.0.

أخيرًا ، يمكن لتطبيقك استخدام رمز الوصول للاتصال بواجهات برمجة تطبيقات Google.

إنشاء حساب خدمة

تتضمن بيانات اعتماد حساب الخدمة عنوان بريد إلكتروني تم إنشاؤه ويكون فريدًا وزوج مفاتيح عام / خاص واحد على الأقل. إذا تم تمكين التفويض على مستوى المجال ، فسيكون معرّف العميل أيضًا جزءًا من بيانات اعتماد حساب الخدمة.

إذا كان تطبيقك يعمل على Google App Engine ، فسيتم إعداد حساب الخدمة تلقائيًا عند إنشاء مشروعك.

إذا كان تطبيقك يعمل على Google Compute Engine ، فسيتم أيضًا إعداد حساب الخدمة تلقائيًا عند إنشاء مشروعك ، ولكن يجب عليك تحديد النطاقات التي يحتاج تطبيقك إلى الوصول إليها عند إنشاء مثيل Google Compute Engine. لمزيد من المعلومات، راجع إعداد مثيل لحسابات خدمة استخدام .

إذا لم يتم تشغيل التطبيق الخاص بك على محرك جوجل التطبيق أو Google Compute Engine و يجب الحصول أوراق الاعتماد هذه في Google API Console. لإنشاء بيانات اعتماد حساب الخدمة ، أو لعرض بيانات الاعتماد العامة التي قمت بإنشائها بالفعل ، قم بما يلي:

First, create a service account:

  1. Open the Service accounts page.
  2. If prompted, select a project, or create a new one.
  3. Click  Create service account.
  4. Under Service account details, type a name, ID, and description for the service account, then click Create and continue.
  5. Optional: Under Grant this service account access to project, select the IAM roles to grant to the service account.
  6. Click Continue.
  7. Optional: Under Grant users access to this service account, add the users or groups that are allowed to use and manage the service account.
  8. Click Done.
  9. Click  Create key, then click Create.

Next, create a service account key:

  1. Click the email address for the service account you created.
  2. Click the Keys tab.
  3. In the Add key drop-down list, select Create new key.
  4. Click Create.

Your new public/private key pair is generated and downloaded to your machine; it serves as the only copy of the private key. You are responsible for storing it securely. If you lose this key pair, you will need to generate a new one.

يمكنك العودة إلى API Console في أي وقت لعرض عنوان البريد الإلكتروني وبصمات الأصابع الرئيسية العامة، وغيرها من المعلومات، أو لتوليد / أزواج رئيسية خاصة إضافية الجمهور. لمزيد من المعلومات حول أوراق اعتماد حساب الخدمة في API Console، انظر حسابات خدمة في API Consoleملف المساعدة.

قم بتدوين عنوان البريد الإلكتروني لحساب الخدمة وقم بتخزين ملف المفتاح الخاص لحساب الخدمة في مكان يمكن الوصول إليه من خلال تطبيقك. يحتاج تطبيقك إليهم لإجراء مكالمات API معتمدة.

تفويض سلطة على مستوى المجال لحساب الخدمة

إذا كان لديك حساب Google Workspace ، فيمكن لمسؤول المؤسسة تخويل تطبيق للوصول إلى بيانات المستخدم نيابة عن المستخدمين في مجال Google Workspace. على سبيل المثال ، قد يستخدم التطبيق الذي يستخدم واجهة برمجة تطبيقات تقويم Google لإضافة أحداث إلى تقاويم جميع المستخدمين في نطاق Google Workspace حساب خدمة للوصول إلى واجهة برمجة تطبيقات تقويم Google نيابة عن المستخدمين. يُشار أحيانًا إلى تفويض حساب خدمة للوصول إلى البيانات نيابة عن المستخدمين في مجال باسم "تفويض سلطة على مستوى المجال" لحساب خدمة.

لتفويض سلطة على مستوى النطاق لحساب خدمة ، يجب على المشرف المتميز لنطاق Google Workspace إكمال الخطوات التالية:

  1. من نطاق Google مساحة عمل في وحدة تحكم المشرف ، انتقل إلى القائمة الرئيسية > الأمن> ضوابط API.
  2. في الجزء وفد واسعة النطاق، حدد إدارة الوفد واسعة النطاق.
  3. انقر على إضافة جديد.
  4. في حقل معرف العميل، أدخل معرف العميل حساب الخدمة. يمكنك العثور على معرف عميل حساب الخدمة الخاص بك في Service accounts page.
  5. في نطاقات أوث الميدان (بفواصل)، أدخل قائمة النطاقات أن التطبيق الخاص بك ينبغي أن تمنح الوصول إليها. على سبيل المثال، إذا كان التطبيق الخاص بك يحتاج إلى الوصول المجال واسع الكامل للAPI في Google Drive والتقويم API جوجل، أدخل: https://www.googleapis.com/auth/drive، https://www.googleapis.com/auth التقويم /.
  6. انقر فوق تخويل.

يتمتع تطبيقك الآن بصلاحية إجراء مكالمات واجهة برمجة التطبيقات كمستخدمين في نطاقك ("لانتحال شخصية" المستخدمين). عندما تستعد لإجراء مكالمات API مصرح بها ، فإنك تحدد المستخدم لانتحال صفته.

الاستعداد لإجراء مكالمة API معتمدة

جافا

بعد الحصول على عنوان البريد الإلكتروني العميل والمفتاح الخاص من API Console، استخدم مكتبة عميل جوجل واجهات برمجة التطبيقات للجافا لخلق GoogleCredential كائن من أوراق اعتماد حساب الخدمة ونطاقات التطبيق يحتاج الوصول إليها. على سبيل المثال:

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

إذا كنت تقوم بتطوير التطبيق على نظام التشغيل السحابي Google، يمكنك استخدام أوراق اعتماد التطبيق الافتراضي بدلا من ذلك، التي يمكن تبسيط هذه العملية.

تفويض السلطة على مستوى المجال

إذا كان لديك تفويض الوصول واسع المجال لحساب خدمة وترغب في تمثيل حساب المستخدم، حدد عنوان البريد الإلكتروني من حساب المستخدم مع createDelegated طريقة لل GoogleCredential الكائن. على سبيل المثال:

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("user@example.com");

استخدام GoogleCredential الكائن لاستدعاء جوجل واجهات برمجة التطبيقات في التطبيق الخاص بك.

بايثون

بعد الحصول على عنوان البريد الإلكتروني العميل والمفتاح الخاص من API Console، استخدم مكتبة عميل جوجل واجهات برمجة التطبيقات لبيثون لاستكمال الخطوات التالية:

  1. إنشاء Credentials كائن من أوراق اعتماد حساب الخدمة ونطاقات التطبيق يحتاج الوصول إليها. على سبيل المثال:
    from google.oauth2 import service_account
    
    SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
    SERVICE_ACCOUNT_FILE = '/path/to/service.json'
    
    credentials = service_account.Credentials.from_service_account_file(
            SERVICE_ACCOUNT_FILE, scopes=SCOPES)

    إذا كنت تقوم بتطوير التطبيق على نظام التشغيل السحابي Google، يمكنك استخدام أوراق اعتماد التطبيق الافتراضي بدلا من ذلك، التي يمكن تبسيط هذه العملية.

  2. تفويض السلطة على مستوى المجال

    إذا كان لديك تفويض الوصول واسع المجال لحساب خدمة وترغب في تمثيل حساب المستخدم، استخدم with_subject طريقة موجود ServiceAccountCredentials الكائن. على سبيل المثال:

    delegated_credentials = credentials.with_subject('user@example.org')

استخدم كائن بيانات الاعتماد لاستدعاء Google APIs في تطبيقك.

HTTP / REST

بعد الحصول على هوية العميل والمفتاح الخاص من API Console، يحتاج التطبيق الخاص بك لإكمال الخطوات التالية:

  1. قم بإنشاء JSON Web Token (JWT ، وضوحا ، "jot") والذي يتضمن رأس ، ومجموعة ادعاء ، وتوقيع.
  2. اطلب رمز دخول من خادم مصادقة Google OAuth 2.0.
  3. تعامل مع استجابة JSON التي يقوم خادم التفويض بإرجاعها.

تصف الأقسام التالية كيفية إتمام هذه الخطوات.

إذا تضمنت استجابة رمز وصول، يمكنك استخدام وصول رمزية ل استدعاء API جوجل . (إذا لم تتضمن الاستجابة رمز وصول ، فقد لا يتم تكوين طلب JWT والرمز بشكل صحيح ، أو قد لا يكون لدى حساب الخدمة الإذن للوصول إلى النطاقات المطلوبة.)

عندما رمز وصول تنتهي ، طلبك يولد JWT آخر، وعلامات ذلك، ويطلب رمز وصول آخر.

يستخدم تطبيق الخادم الخاص بك JWT لطلب رمز مميز من Google Authorization Server ، ثم يستخدم الرمز المميز لاستدعاء نقطة نهاية Google API. لا يوجد مستخدم نهائي متورط.

يصف الجزء المتبقي من هذا القسم تفاصيل إنشاء JWT ، وتوقيع JWT ، وتشكيل طلب رمز الوصول ، والتعامل مع الاستجابة.

إنشاء JWT

يتكون JWT من ثلاثة أجزاء: رأس ومجموعة مطالبة وتوقيع. مجموعة الرأس والمطالبة هي كائنات JSON. يتم تسلسل كائنات JSON هذه إلى UTF-8 بايت ، ثم يتم تشفيرها باستخدام تشفير Base64url. يوفر هذا الترميز مرونة ضد تغييرات التشفير بسبب عمليات التشفير المتكررة. يتم متصلا الرأس، مجموعة المطالبة، والتوقيع مع نقطة ( . ) حرف.

يتكون JWT على النحو التالي:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

السلسلة الأساسية للتوقيع هي كما يلي:

{Base64url encoded header}.{Base64url encoded claim set}
تشكيل رأس JWT

يتكون الرأس من حقلين يشيران إلى خوارزمية التوقيع وشكل التأكيد. كلا الحقلين إلزاميان ، ولكل حقل قيمة واحدة فقط. مع تقديم خوارزميات وتنسيقات إضافية ، سيتغير هذا العنوان وفقًا لذلك.

تعتمد حسابات الخدمة على خوارزمية RSA SHA-256 وتنسيق الرمز المميز لـ JWT. نتيجة لذلك ، يكون تمثيل JSON للرأس كما يلي:

{"alg":"RS256","typ":"JWT"}

تمثيل Base64url لهذا كالتالي:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
تشكيل مجموعة مطالبات JWT

تحتوي مجموعة مطالبة JWT على معلومات حول JWT ، بما في ذلك الأذونات المطلوبة (النطاقات) ، وهدف الرمز المميز ، والمُصدر ، ووقت إصدار الرمز المميز ، وعمر الرمز المميز. معظم الحقول إلزامية. مثل عنوان JWT ، فإن مجموعة ادعاءات JWT هي كائن JSON وتستخدم في حساب التوقيع.

المطالبات المطلوبة

المطالبات المطلوبة في مجموعة مطالبات JWT موضحة أدناه. قد تظهر بأي ترتيب في مجموعة المطالبة.

اسم وصف
iss عنوان البريد الإلكتروني لحساب الخدمة.
scope قائمة محددة بمسافات من الأذونات التي يطلبها التطبيق.
aud واصف الهدف المقصود من التأكيد. عند تقديم طلب رمز وصول هذه القيمة هي دائما https://oauth2.googleapis.com/token .
exp وقت انتهاء صلاحية التأكيد ، المحدد بالثواني منذ 00:00:00 بالتوقيت العالمي المنسق ، 1 يناير 1970. هذه القيمة لها ساعة واحدة كحد أقصى بعد وقت الإصدار.
iat وقت إصدار التأكيد ، المحدد بالثواني منذ 00:00:00 بالتوقيت العالمي المنسق ، 1 يناير 1970.

يظهر تمثيل JSON للحقول المطلوبة في مجموعة مطالبة JWT أدناه:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
مطالبات إضافية

في بعض الحالات الخاصة بالمؤسسات ، يمكن للتطبيق استخدام التفويض على مستوى المجال للعمل نيابة عن مستخدم معين في مؤسسة. يجب منح إذن تنفيذ هذا النوع من انتحال الهوية قبل أن يتمكن التطبيق من انتحال شخصية مستخدم ، وعادة ما يتم التعامل معه بواسطة مشرف متميز. لمزيد من المعلومات، راجع الوصول API تحكم مع وفد واسع المجال .

للحصول على وصول رمز مميز المنح تطبيق تفويض الوصول إلى الموارد، وتضمين عنوان البريد الإلكتروني للمستخدم في المجموعة مطالبة JWT كقيمة من sub المجال.

اسم وصف
sub عنوان البريد الإلكتروني للمستخدم الذي يطلب التطبيق الوصول المفوض إليه.

إذا لم يكن تطبيق إذن انتحال صفة مستخدم، واستجابة لطلب رمز وصول يتضمن sub سوف المجال أن يكون خطأ .

مثال على مجموعة مطالبة JWT يتضمن sub هو مبين أدناه الملعب:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "sub": "some.user@example.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
ترميز مجموعة المطالبة JWT

مثل رأس JWT ، يجب إجراء تسلسل لمجموعة ادعاءات JWT إلى UTF-8 و Base64url-safe المشفرة. فيما يلي مثال على تمثيل JSON لمجموعة مطالبات JWT:

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
حساب التوقيع

JSON الويب التوقيع (JWS) هو المواصفات التي أدلة آليات توليد توقيع لJWT. مدخلات التوقيع هي مصفوفة البايت للمحتوى التالي:

{Base64url encoded header}.{Base64url encoded claim set}

يجب استخدام خوارزمية التوقيع في رأس JWT عند حساب التوقيع. خوارزمية التوقيع الوحيدة التي يدعمها خادم مصادقة Google OAuth 2.0 هي RSA باستخدام خوارزمية التجزئة SHA-256. يمكن التعبير عن هذا RS256 في alg الحقل في رأس JWT.

توقيع تمثيل UTF-8 من الإدخال باستخدام SHA256withRSA (المعروف أيضا باسم RSASSA-PKCS1-V1_5-SIGN مع وظيفة التجزئة SHA-256) مع مفتاح خاص تم الحصول عليها من Google API Console. سيكون الإخراج صفيف بايت.

يجب أن يكون التوقيع بعد ذلك مشفرًا باستخدام Base64url. يتم متصلا الرأس، مجموعة المطالبة، والتوقيع مع نقطة ( . ) حرف. والنتيجة هي JWT. يجب أن يكون كالتالي (تمت إضافة فواصل الأسطر للتوضيح):

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

فيما يلي مثال على JWT قبل تشفير Base64url:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

فيما يلي مثال على JWT تم توقيعه وجاهز للإرسال:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

جعل طلب رمز الوصول

بعد إنشاء JWT الموقع ، يمكن للتطبيق استخدامه لطلب رمز وصول. هذا الوصول رمز طلب هو HTTPS POST الطلب، والجسد هو ترميز URL. يظهر عنوان URL أدناه:

https://oauth2.googleapis.com/token

ويطلب من المعلمات التالية في HTTPS POST الطلب:

اسم وصف
grant_type استخدام السلسلة التالية، URL ترميز كما الضرورية: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion JWT ، بما في ذلك التوقيع.

وفيما يلي تفريغ الخام من HTTPS POST طلب المستخدمة في الوصول رمز الطلب:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

وفيما يلي نفس الطلب، وذلك باستخدام curl :

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

التعامل مع الاستجابة

إذا تم تشكيل JWT وطلب رمز الوصول بشكل صحيح وكان حساب الخدمة لديه إذن لتنفيذ العملية ، فإن استجابة JSON من خادم التخويل تتضمن رمز وصول. فيما يلي مثال على الرد:

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

الرموز الوصول يمكن إعادة استخدامها خلال فترة الانتقالات المدة المحددة من قبل expires_in القيمة.

استدعاء Google APIs

جافا

استخدام GoogleCredential الكائن لاستدعاء واجهات برمجة التطبيقات جوجل من خلال استكمال الخطوات التالية:

  1. إنشاء كائن خدمة لAPI الذي تريد الاتصال باستخدام GoogleCredential الكائن. على سبيل المثال:
    SQLAdmin sqladmin =
        new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
  2. تقديم طلبات إلى خدمة API باستخدام واجهة المقدمة من كائن خدمة . على سبيل المثال، لسرد حالات قواعد البيانات SQL الغيمة في إثارة-مثلا-123 مشروع:
    SQLAdmin.Instances.List instances =
        sqladmin.instances().list("exciting-example-123").execute();

بايثون

استخدام أذن Credentials كائن لاستدعاء واجهات برمجة التطبيقات جوجل من خلال استكمال الخطوات التالية:

  1. إنشاء كائن خدمة لواجهة برمجة التطبيقات التي تريد الاتصال بها. يمكنك بناء أأ كائن خدمة عن طريق استدعاء build وظيفة مع اسم ونسخة من API وأذن Credentials الكائن. على سبيل المثال، لاستدعاء نسخة 1beta3 إدارة API سحابة SQL:
    import googleapiclient.discovery
    
    sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
  2. تقديم طلبات إلى خدمة API باستخدام واجهة المقدمة من كائن خدمة . على سبيل المثال، لسرد حالات قواعد البيانات SQL الغيمة في إثارة-مثلا-123 مشروع:
    response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP / REST

بعد حصول تطبيقك على رمز وصول ، يمكنك استخدام الرمز المميز لإجراء مكالمات إلى Google API نيابة عن حساب خدمة أو حساب مستخدم معين إذا تم منح نطاق (نطاقات) الوصول المطلوبة بواسطة واجهة برمجة التطبيقات. للقيام بذلك، وتشمل الوصول رمزية في طلب إلى API من قبل بما في ذلك إما access_token المعلمة الاستعلام أو Authorization HTTP رأس Bearer القيمة. عندما يكون ذلك ممكنًا ، يُفضل رأس HTTP ، لأن سلاسل الاستعلام تميل إلى أن تكون مرئية في سجلات الخادم. في معظم الحالات يمكنك استخدام مكتبة العميل لإعداد المكالمات إلى واجهات برمجة التطبيقات (على سبيل المثال، عند استدعاء API الملفات محرك ).

يمكنك تجربة كل واجهات برمجة التطبيقات جوجل وعرض النطاقات الخاصة في أوث 2.0 ملعب .

أمثلة HTTP GET

دعوة إلى drive.files نقطة النهاية (وAPI الملفات الصلب) باستخدام Authorization: Bearer HTTP رأس قد تبدو كما يلي. لاحظ أنك تحتاج إلى تحديد رمز الوصول الخاص بك:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

هنا هو دعوة إلى نفس API لمصادقة المستخدم باستخدام access_token معلمة سلسلة الاستعلام:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl الأمثلة

يمكنك اختبار هذه الأوامر مع curl تطبيق سطر الأوامر. إليك مثال يستخدم خيار رأس HTTP (مفضل):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

أو ، بدلاً من ذلك ، خيار معلمة سلسلة الاستعلام:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

عندما تنتهي صلاحية رموز الوصول

الرموز المميزة صدر صول جوجل أوث 2.0 ترخيص خادم تنتهي بعد مدة التي تقدمها expires_in القيمة. عند انتهاء صلاحية رمز الوصول ، يجب على التطبيق إنشاء JWT آخر وتوقيعه وطلب رمز وصول آخر.

رموز خطأ JWT

error المجال error_description الحقل المعنى كيف تحل
unauthorized_client Unauthorized client or scope in request. إذا كنت تحاول استخدام التفويض على مستوى النطاق ، فإن حساب الخدمة غير مصرح به في وحدة تحكم المشرف الخاصة بنطاق المستخدم.

تأكد من أن حساب خدمة يؤذن في وفد واسعة النطاق صفحة من وحدة تحكم المشرف للمستخدم في sub المطالبة (حقل).

على الرغم من أن الأمر يستغرق عادةً بضع دقائق ، فقد يستغرق الأمر ما يصل إلى 24 ساعة للحصول على إذن بالنشر لجميع المستخدمين في حسابك على Google.

unauthorized_client Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested. تم تفويض حساب الخدمة باستخدام عنوان البريد الإلكتروني للعميل بدلاً من معرّف العميل (الرقمي) في وحدة تحكم المشرف. في وفد واسعة النطاق في وحدة تحكم المسؤول، وإزالة العميل، وإعادة إضافتها مع معرف رقمي.
access_denied (اي قيمة) إذا كنت تستخدم التفويض على مستوى النطاق ، فلن يتم اعتماد نطاق واحد أو أكثر من النطاقات المطلوبة في وحدة تحكم المشرف.

تأكد من أن حساب خدمة يؤذن في وفد واسعة النطاق صفحة من وحدة تحكم المشرف للمستخدم في sub المطالبة (الميدان)، وأنه يشمل كل من نطاقات كنت طالبا في scope مطالبة JWT الخاص بك.

على الرغم من أن الأمر يستغرق عادةً بضع دقائق ، فقد يستغرق الأمر ما يصل إلى 24 ساعة للحصول على إذن بالنشر لجميع المستخدمين في حسابك على Google.

invalid_grant Not a valid email. المستخدم غير موجود. تأكد من أن عنوان البريد الإلكتروني في sub المطالبة (الميدان) هو الصحيح.
invalid_grant

Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your 'iat' and 'exp' values and use a clock with skew to account for clock differences between systems.

عادة ، هذا يعني أن وقت النظام المحلي غير صحيح. ويمكن أن يحدث أيضا إذا كان exp القيمة هي أكثر من 65 دقيقة في المستقبل من iat قيمة، أو exp قيمة أقل من iat القيمة.

تأكد من صحة الساعة على النظام حيث تم إنشاء JWT. إذا لزم الأمر، مزامنة وقتك مع جوجل NTP .

invalid_grant Invalid JWT Signature.

يتم توقيع تأكيد JWT بمفتاح خاص غير مرتبط بحساب الخدمة المحدد بواسطة البريد الإلكتروني للعميل أو أن المفتاح الذي تم استخدامه قد تم حذفه أو تعطيله أو انتهاء صلاحيته.

بدلاً من ذلك ، قد يتم ترميز تأكيد JWT بشكل غير صحيح - يجب أن يكون مشفرًا باستخدام Base64 ، بدون أسطر جديدة أو علامات متساوية.

قم بفك تشفير مجموعة ادعاء JWT وتحقق من أن المفتاح الذي وقع على التأكيد مرتبط بحساب الخدمة.

حاول استخدام مكتبة OAuth المقدمة من Google للتأكد من إنشاء JWT بشكل صحيح.

invalid_scope Invalid OAuth scope or ID token audience provided. لم يتم طلب أي نطاقات (قائمة نطاقات فارغة) ، أو أن أحد النطاقات المطلوبة غير موجود (أي غير صالح).

تأكد من أن scope الدعوى (حقل) من JWT يتم ملؤها، ومقارنة نطاقات أنه يحتوي على نطاقات موثقة عن واجهات برمجة التطبيقات التي تريد استخدامها، لضمان عدم وجود أخطاء أو الأخطاء المطبعية.

علما بأن قائمة النطاقات في scope الاحتياجات مطالبة أن تكون مفصولة بمسافات، وليس بفواصل.

disabled_client The OAuth client was disabled. المفتاح المستخدم لتوقيع تأكيد JWT معطل.

انتقل إلى Google API Console، وتحت IAM والمشرف> حسابات الخدمات، تمكين حساب الخدمة الذي يحتوي على "معرف مفتاح" المستخدمة للتوقيع على التأكيد.

ملحق: تفويض حساب الخدمة بدون OAuth

باستخدام بعض واجهات برمجة تطبيقات Google ، يمكنك إجراء مكالمات API مصرح بها باستخدام JWT موقّع مباشرةً كرمز حامل ، بدلاً من رمز وصول OAuth 2.0. عندما يكون ذلك ممكنًا ، يمكنك تجنب الاضطرار إلى تقديم طلب شبكة إلى خادم تفويض Google قبل إجراء مكالمة واجهة برمجة التطبيقات.

إذا كان API تريد دعوة لديه تعريف الخدمة التي نشرت في مستودع Google اجهات برمجة التطبيقات جيثب ، يمكنك إجراء مكالمات API أذن باستخدام JWT بدلا من رمز وصول. لنفعل ذلك:

  1. إنشاء حساب خدمة كما هو موضح أعلاه. تأكد من الاحتفاظ بملف JSON الذي تحصل عليه عند إنشاء الحساب.
  2. باستخدام أي مكتبة JWT القياسية، مثل واحدة وجدت في jwt.io ، إنشاء JWT من ضربة رأس وحمولة مثل المثال التالي:
    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "abcdef1234567890"
    }
    .
    {
      "iss": "123456-compute@developer.gserviceaccount.com",
      "sub": "123456-compute@developer.gserviceaccount.com",
      "aud": "https://firestore.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600
    }
    • لل kid الحقل في رأس تحديد هوية المفتاح الخاص حساب الخدمة. يمكنك العثور على هذه القيمة في private_key_id مجال ملف حساب JSON الخدمة الخاص بك.
    • ل iss و sub المجالات، تحديد عنوان البريد الإلكتروني حساب الخدمة. يمكنك العثور على هذه القيمة في client_email مجال ملف حساب JSON الخدمة الخاص بك.
    • ل aud الحقل، حدد نقطة النهاية API. على سبيل المثال: https:// SERVICE .googleapis.com/ .
    • ل iat الميدانية، وتحديد الوقت يونكس الحالي، ول exp المجال، تحديد الوقت بالضبط 3600 ثانية في وقت لاحق، عندما JWT سوف تنتهي.

قم بتوقيع JWT مع RSA-256 باستخدام المفتاح الخاص الموجود في ملف JSON لحساب الخدمة الخاص بك.

على سبيل المثال:

جافا

باستخدام جوجل-المعهد-جافا العميل و جافا JWT :

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("123456-compute@developer.gserviceaccount.com")
        .withSubject("123456-compute@developer.gserviceaccount.com")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

بايثون

باستخدام PyJWT :

iat = time.time()
exp = iat + 3600
payload = {'iss': '123456-compute@developer.gserviceaccount.com',
           'sub': '123456-compute@developer.gserviceaccount.com',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')
  1. استدعاء API، وذلك باستخدام JWT التي تم التوقيع عليها الرمز المميز للحامل:
    GET /v1/projects/abc/databases/123/indexes HTTP/1.1
    Authorization: Bearer SIGNED_JWT
    Host: firestore.googleapis.com