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