ربط إضافة Google Workspace بخدمة تابعة لجهة خارجية

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

توضّح هذه الصفحة كيفية مصادقة المستخدمين باستخدام مسار تفويض (مثل OAuth)، ويتضمّن ذلك الخطوات التالية:

1. الرصد عندما يكون التفويض مطلوبًا.
2. عرض واجهة بطاقة تطلب من المستخدمين تسجيل الدخول إلى الخدمة
3. أعِد تحميل الإضافة ليتمكّن المستخدمون من الوصول إلى الخدمة أو المورد المحمي.

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

اكتشاف أن التفويض مطلوب

عند استخدام الإضافة، قد لا يتم السماح للمستخدمين بالوصول إلى مورد محمي لعدة أسباب، مثل ما يلي:

• لم يتم بعد إنشاء رمز دخول للاتصال بخدمة الجهة الخارجية أو انتهت صلاحيته.
• لا يغطي رمز الدخول المورد المطلوب.
• لا يغطي رمز الدخول النطاقات المطلوبة للطلب.

من المفترض أن ترصد الإضافة هذه الحالات ليتمكّن المستخدمون من تسجيل الدخول إلى خدمتك والوصول إليها.

مطالبة المستخدمين بتسجيل الدخول إلى خدمتك

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

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

إنشاء بطاقة تسجيل دخول وإرجاعها

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

بطاقة التفويض الأساسية

توضِّح الصورة التالية مثالاً على بطاقة التفويض الأساسية من Google:

لاستخدام بطاقة التفويض الأساسية، أرجع رد JSON التالي:

{
  "basic_authorization_prompt": {
    "authorization_url": "AUTHORIZATION_REDIRECT",
    "resource": "RESOURCE_DISPLAY_NAME"
  }
}

استبدل ما يلي:

• AUTHORIZATION_REDIRECT: عنوان URL لتطبيق الويب الذي يعالج المصادقة.
• RESOURCE_DISPLAY_NAME: الاسم المعروض للمورّد أو الخدمة المحمية يظهر هذا الاسم للمستخدم في مطالبة التفويض. على سبيل المثال، إذا كانت قيمة RESOURCE_DISPLAY_NAME هي Example Account، ستظهر في الإشعار رسالة "تريد هذه الإضافة عرض معلومات إضافية، ولكنها تحتاج إلى موافقة للوصول إلى حسابك كمثال".

بعد إكمال التفويض، يُطلَب من المستخدم تحديث الإضافة للوصول إلى المورد المحمي.

بطاقة التفويض المخصّصة

لتعديل رسالة المطالبة بالتفويض، يمكنك إنشاء بطاقة مخصّصة لتجربة تسجيل الدخول إلى خدمتك.

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

تُظهر الصور التالية مثالاً على بطاقة تفويض مخصصة للصفحة الرئيسية لإضافة. تتضمّن البطاقة شعارًا ووصفًا وزر تسجيل دخول:

لاستخدام هذا المثال على البطاقة المخصّصة، يمكنك عرض استجابة JSON التالية:

{
  "custom_authorization_prompt": {
    "action": {
      "navigations": [
        {
          "pushCard": {
            "sections": [
              {
                "widgets": [
                  {
                    "image": {
                      "imageUrl": "LOGO_URL",
                      "altText": "LOGO_ALT_TEXT"
                    }
                  },
                  {
                    "divider": {}
                  },
                  {
                    "textParagraph": {
                      "text": "DESCRIPTION"
                    }
                  },
                  {
                    "buttonList": {
                      "buttons": [
                        {
                          "text": "Sign in",
                          "onClick": {
                            "openLink": {
                              "url": "AUTHORIZATION_REDIRECT",
                              "onClose": "RELOAD",
                              "openAs": "OVERLAY"
                            }
                          },
                          "color": {
                            "red": 0,
                            "green": 0,
                            "blue": 1,
                            "alpha": 1,
                          }
                        }
                      ]
                    }
                  },
                  {
                    "textParagraph": {
                      "text": "TEXT_SIGN_UP"
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }
}

استبدل ما يلي:

• LOGO_URL: عنوان URL لشعار أو صورة يجب أن يكون عنوان URL متاحًا للجميع.
• LOGO_ALT_TEXT: نص بديل للشعار أو الصورة، مثل Cymbal Labs Logo
• DESCRIPTION: عبارة تحث المستخدمين على اتخاذ إجراء، مثل Sign in to get started
• لتعديل زر تسجيل الدخول:
  • AUTHORIZATION_REDIRECT: عنوان URL لتطبيق الويب الذي يعالج المصادقة.
  • اختياري: لتغيير لون الزر، عدِّل القيم العائمة الخاصة بنموذج RGBA في الحقل color.
• TEXT_SIGN_UP: نص يطالب المستخدمين بإنشاء حساب إذا لم يكن لديهم حساب. مثلاً: New to Cymbal Labs? <a href=\"https://www.example.com/signup\">Sign up</a> here