استخدام 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

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

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

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

يتم تمثيل Base64url على النحو التالي:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

تشكيل مجموعة مطالبات 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 (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:

في ما يلي تفريغ أولي لطلب 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 آخر، وأن يوقّع عليه وأن يطلب رمز دخول آخر.