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

إنشاء 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

يتألف العنوان من ثلاثة حقول تشير إلى خوارزمية التوقيع وتنسيق التأكيد و[رقم التعريف الأساسي لمفتاح حساب الخدمة](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) الذي تم استخدامه لتوقيع JWT. إنّ الخوارزمية والتنسيق إلزاميان، ولكل حقل قيمة واحدة فقط. ومع تقديم خوارزميات وتنسيقات إضافية، سيتغيّر هذا العنوان وفقًا لذلك. معرّف المفتاح اختياري، وإذا تم تحديد رقم تعريف مفتاح غير صحيح، ستحاول خدمة Google Cloud Platform كل المفاتيح المرتبطة بحساب الخدمة للتحقّق من الرمز المميّز ورفض الرمز المميّز في حال عدم العثور على أي مفتاح صالح. وتحتفظ Google بالحق في رفض الرموز المميّزة التي تتضمّن أرقام تعريف مفاتيح غير صحيحة في المستقبل.

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

{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

في ما يلي تمثيل Base64url كما يلي:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=

تشكيل مجموعة المطالبات باستخدام JWT

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

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

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

يظهر أدناه تنسيق 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
}

مطالبات إضافية

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

للحصول على رمز دخول مميز يمنح تطبيقًا مفوّضًا للوصول إلى أحد الموارد، أدرِج عنوان البريد الإلكتروني للمستخدم في المطالبة التي تم ضبطها في JWT باعتبارها قيمة الحقل 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 هو المواصفات التي توجّه آليات إنشاء التوقيع إلى 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 الموقَّع، يمكن للتطبيق استخدامه لطلب رمز الدخول. طلب رمز الدخول هذا هو طلب POST عبر HTTPS، ويكون النص الأساسي مشفّرًا بعنوان URL. يظهر عنوان URL أدناه:

https://oauth2.googleapis.com/token

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

في ما يلي تفريغ أولي لطلب 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 OAuth 2.0 بعد المدة التي تقدّمها القيمة expires_in. عند انتهاء صلاحية رمز الدخول، يجب أن ينشئ التطبيق رمز JWT آخر ويوقِّع عليه وأن يطلب رمز دخول آخر.