المصادقة باستخدام Microsoft مع JavaScript

يمكنك السماح للمستخدمين بالمصادقة مع Firebase باستخدام موفّري بروتوكول OAuth مثل Microsoft Azure Active Directory، وذلك من خلال دمج عملية تسجيل الدخول العامة باستخدام بروتوكول OAuth في تطبيقك باستخدام حزمة تطوير البرامج (SDK) لمنصّة Firebase لإجراء عملية تسجيل الدخول من البداية إلى النهاية.

قبل البدء

لتسجيل دخول المستخدمين باستخدام حسابات Microsoft (Azure Active Directory وحسابات Microsoft الشخصية)، عليك أولاً تفعيل Microsoft كخدمة تسجيل الدخول لمشروعك على Firebase:

  1. أضِف Firebase إلى مشروع JavaScript.
  2. في وحدة تحكُّم Firebase، افتح قسم المصادقة.
  3. في علامة التبويب طريقة تسجيل الدخول، فعِّل موفّر خدمة Microsoft.
  4. أضِف Client ID وClient Secret من وحدة تحكّم المطوّرين الخاصة بالموفّر إلى إعدادات الموفّر:
    1. لتسجيل عميل Microsoft OAuth، اتّبِع التعليمات الواردة في Quickstart: تسجيل تطبيق باستخدام نقطة نهاية Azure Active Directory v2.0. تجدر الإشارة إلى أنّ نقطة النهاية هذه تتيح تسجيل الدخول باستخدام حسابات Microsoft الشخصية بالإضافة إلى حسابات Azure Active Directory. مزيد من المعلومات حول الإصدار 2.0 من Azure Active Directory.
    2. عند تسجيل التطبيقات لدى مقدّمي الخدمة هؤلاء، احرص على تسجيل نطاق *.firebaseapp.com لمشروعك باعتباره نطاق إعادة التوجيه لتطبيقك.
  5. انقر على حفظ.

معالجة عملية تسجيل الدخول باستخدام حزمة تطوير البرامج (SDK) لمنصّة Firebase

إذا كنت تنشئ تطبيق ويب، إنّ أسهل طريقة لمصادقة المستخدمين من خلال Firebase باستخدام حساباتهم على Microsoft هي معالجة عملية تسجيل الدخول بالكامل باستخدام حزمة تطوير البرامج (SDK) لمنصّة Firebase JavaScript.

لمعالجة عملية تسجيل الدخول باستخدام حزمة تطوير البرامج (SDK) لمنصّة Firebase JavaScript، اتّبِع الخطوات التالية:

  1. إنشاء نسخة افتراضية من OAuthProvider باستخدام رقم تعريف الموفِّر microsoft.com

    واجهة برمجة التطبيقات Web modular API

    import { OAuthProvider } from "firebase/auth";

const provider = new OAuthProvider('microsoft.com');
    auth_msft_create_provider.js

    واجهة برمجة التطبيقات لمساحة الاسم على الويب

    var provider = new firebase.auth.OAuthProvider('microsoft.com');
    microsoft-oauth.js

  2. اختياري: حدِّد مَعلمات OAuth المخصّصة الإضافية التي تريد إرسالها مع طلب OAuth.

    واجهة برمجة التطبيقات Web modular API

    provider.setCustomParameters({
  // Force re-consent.
  prompt: 'consent',
  // Target specific email with login hint.
  login_hint: 'user@firstadd.onmicrosoft.com'
});
    auth_msft_provider_params.js

    واجهة برمجة التطبيقات لمساحة الاسم على الويب

    provider.setCustomParameters({
  // Force re-consent.
  prompt: 'consent',
  // Target specific email with login hint.
  login_hint: 'user@firstadd.onmicrosoft.com'
});
    microsoft-oauth.js

    لمعرفة المَعلمات المتوافقة مع Microsoft، يُرجى الاطّلاع على مستندات Microsoft OAuth. تجدر الإشارة إلى أنّه لا يمكنك ضبط المعلَمات المطلوبة في Firebase مع setCustomParameters(). وهذه المَعلمات هي client_id وresponse_type وredirect_uri وstate وscope وresponse_mode.

    للسماح فقط للمستخدمين من مستأجر Azure AD بتسجيل الدخول إلى التطبيق، يمكن استخدام إمّا اسم النطاق المألوف لمستأجر Azure AD أو المعرّف الفريد العام الخاص بالمستأجر. ويمكن إجراء ذلك من خلال تحديد حقل "المستأجر" في كائن المعلمات المخصصة.

    واجهة برمجة التطبيقات Web modular API

    provider.setCustomParameters({
  // Optional "tenant" parameter in case you are using an Azure AD tenant.
  // eg. '8eaef023-2b34-4da1-9baa-8bc8c9d6a490' or 'contoso.onmicrosoft.com'
  // or "common" for tenant-independent tokens.
  // The default value is "common".
  tenant: 'TENANT_ID'
});
    auth_msft_provider_params_tenant.js

    واجهة برمجة التطبيقات لمساحة الاسم على الويب

    provider.setCustomParameters({
  // Optional "tenant" parameter in case you are using an Azure AD tenant.
  // eg. '8eaef023-2b34-4da1-9baa-8bc8c9d6a490' or 'contoso.onmicrosoft.com'
  // or "common" for tenant-independent tokens.
  // The default value is "common".
  tenant: 'TENANT_ID'
});
    microsoft-oauth.js

  3. اختياري: حدِّد نطاقات OAuth 2.0 الإضافية بخلاف الملف الشخصي الأساسي الذي تريد طلبه من موفِّر المصادقة.

    provider.addScope('mail.read');
provider.addScope('calendars.read');

    لمزيد من المعلومات، يمكنك الاطّلاع على مستندات الموافقة والأذونات في Microsoft.

  4. عليك المصادقة مع Firebase باستخدام كائن موفّر بروتوكول OAuth. يمكنك توجيه المستخدمين إلى تسجيل الدخول باستخدام حساباتهم على Microsoft إما من خلال فتح نافذة منبثقة أو عن طريق إعادة التوجيه إلى صفحة تسجيل الدخول. ومفضلة طريقة إعادة التوجيه على الأجهزة المحمولة.

    • لتسجيل الدخول عبر نافذة منبثقة، اتصل بالرقم signInWithPopup:

    واجهة برمجة التطبيقات Web modular API

    import { getAuth, signInWithPopup, OAuthProvider } from "firebase/auth";

const auth = getAuth();
signInWithPopup(auth, provider)
  .then((result) => {
    // User is signed in.
    // IdP data available in result.additionalUserInfo.profile.

    // Get the OAuth access token and ID Token
    const credential = OAuthProvider.credentialFromResult(result);
    const accessToken = credential.accessToken;
    const idToken = credential.idToken;
  })
  .catch((error) => {
    // Handle error.
  });
    auth_msft_signin_popup.js

    واجهة برمجة التطبيقات لمساحة الاسم على الويب

    firebase.auth().signInWithPopup(provider)
  .then((result) => {
    // IdP data available in result.additionalUserInfo.profile.
    // ...

    /** @type {firebase.auth.OAuthCredential} */
    var credential = result.credential;

    // OAuth access and id tokens can also be retrieved:
    var accessToken = credential.accessToken;
    var idToken = credential.idToken;
  })
  .catch((error) => {
    // Handle error.
  });
    microsoft-oauth.js
    • لتسجيل الدخول عن طريق إعادة التوجيه إلى صفحة تسجيل الدخول، اتصل بالرقم signInWithRedirect:

    اتّبِع أفضل الممارسات عند استخدام signInWithRedirect أو linkWithRedirect أو reauthenticateWithRedirect.

    واجهة برمجة التطبيقات Web modular API

    import { getAuth, signInWithRedirect } from "firebase/auth";

const auth = getAuth();
signInWithRedirect(auth, provider);
    auth_msft_signin_redirect.js

    واجهة برمجة التطبيقات لمساحة الاسم على الويب

    firebase.auth().signInWithRedirect(provider);
    microsoft-oauth.js

    بعد أن يكمل المستخدم عملية تسجيل الدخول ثم يعود إلى الصفحة، يمكنك الحصول على نتيجة تسجيل الدخول من خلال الاتصال على getRedirectResult.

    واجهة برمجة التطبيقات Web modular API

    import { getAuth, getRedirectResult, OAuthProvider } from "firebase/auth";

const auth = getAuth();
getRedirectResult(auth)
  .then((result) => {
    // User is signed in.
    // IdP data available in result.additionalUserInfo.profile.

    // Get the OAuth access token and ID Token
    const credential = OAuthProvider.credentialFromResult(result);
    const accessToken = credential.accessToken;
    const idToken = credential.idToken;
  })
  .catch((error) => {
    // Handle error.
  });
    auth_msft_signin_redirect_result.js

    واجهة برمجة التطبيقات لمساحة الاسم على الويب

    firebase.auth().getRedirectResult()
  .then((result) => {
    // IdP data available in result.additionalUserInfo.profile.
    // ...

    /** @type {firebase.auth.OAuthCredential} */
    var credential = result.credential;

    // OAuth access and id tokens can also be retrieved:
    var accessToken = credential.accessToken;
    var idToken = credential.idToken;
  })
  .catch((error) => {
    // Handle error.
  });
    microsoft-oauth.js

    وعند إتمام العملية بنجاح، يمكن استرداد رمز الدخول عبر بروتوكول OAuth المرتبط بالموفِّر من عنصر firebase.auth.UserCredential الذي تم إرجاعه.

    باستخدام رمز الدخول المميز عبر OAuth، يمكنك طلب Microsoft Graph API.

    على سبيل المثال، للحصول على معلومات الملف الشخصي الأساسية، يمكن استدعاء واجهة برمجة تطبيقات REST التالية:

    curl -i -H "Authorization: Bearer ACCESS_TOKEN" https://graph.microsoft.com/v1.0/me

    على عكس مقدمي الخدمة الآخرين الذين يتيحون مصادقة Firebase، لا توفر Microsoft عنوان URL للصورة، وبدلاً من ذلك، يجب طلب البيانات الثنائية لصورة الملف الشخصي عبر Microsoft Graph API.

    بالإضافة إلى رمز الدخول عبر OAuth، يمكن أيضًا استرداد رمز OAuth المميز الخاص بالمستخدم من كائن firebase.auth.UserCredential. إنّ مطالبة sub في الرمز المميّز للمعرّف خاصة بالتطبيق ولن تتطابق مع معرّف المستخدم الموحّد الذي تستخدمه مصادقة Firebase ويمكن الوصول إليه من خلال user.providerData[0].uid. يجب استخدام حقل المطالبة oid بدلاً من ذلك. عند استخدام مستأجر Azure AD لتسجيل الدخول، ستكون المطالبة oid مطابقة تمامًا. ومع ذلك، في حالة غير المستأجر، تتم تعبئة الحقل oid. بالنسبة إلى المعرّف الموحّد 4b2eabcdefghijkl، سيكون للمعرّف oid نموذج 00000000-0000-0000-4b2e-abcdefghijkl.

  5. مع أنّ الأمثلة أعلاه تركّز على مسارات تسجيل الدخول، يمكنك أيضًا ربط موفِّر خدمة Microsoft بمستخدم حالي باستخدام linkWithPopup/linkWithRedirect. على سبيل المثال، يمكنك ربط عدة مقدّمي خدمة بالمستخدم نفسه الذي يسمح لهم بتسجيل الدخول باستخدام أي منهما.

    واجهة برمجة التطبيقات Web modular API

    import { getAuth, linkWithPopup, OAuthProvider } from "firebase/auth";

const provider = new OAuthProvider('microsoft.com');
const auth = getAuth();

linkWithPopup(auth.currentUser, provider)
    .then((result) => {
      // Microsoft credential is linked to the current user.
      // IdP data available in result.additionalUserInfo.profile.

      // Get the OAuth access token and ID Token
      const credential = OAuthProvider.credentialFromResult(result);
      const accessToken = credential.accessToken;
      const idToken = credential.idToken;
    })
    .catch((error) => {
      // Handle error.
    });
    auth_msft_link_popup.js

    واجهة برمجة التطبيقات لمساحة الاسم على الويب

    var provider = new firebase.auth.OAuthProvider('microsoft.com');
firebase.auth().currentUser.linkWithPopup(provider)
    .then((result) => {
      // Microsoft credential is linked to the current user.
      // IdP data available in result.additionalUserInfo.profile.
      // OAuth access token can also be retrieved:
      // result.credential.accessToken
      // OAuth ID token can also be retrieved:
      // result.credential.idToken
    })
    .catch((error) => {
      // Handle error.
    });
    microsoft-oauth.js

  6. يمكن استخدام النمط نفسه مع reauthenticateWithPopup/reauthenticateWithRedirect الذي يمكن استخدامه لاسترداد بيانات الاعتماد الجديدة للعمليات الحسّاسة التي تتطلب تسجيل دخول حديث.

    واجهة برمجة التطبيقات Web modular API

    import { getAuth, reauthenticateWithPopup, OAuthProvider } from "firebase/auth";

const provider = new OAuthProvider('microsoft.com');
const auth = getAuth();
reauthenticateWithPopup(auth.currentUser, provider)
    .then((result) => {
      // User is re-authenticated with fresh tokens minted and
      // should be able to perform sensitive operations like account
      // deletion and email or password update.
      // IdP data available in result.additionalUserInfo.profile.

      // Get the OAuth access token and ID Token
      const credential = OAuthProvider.credentialFromResult(result);
      const accessToken = credential.accessToken;
      const idToken = credential.idToken;
    })
    .catch((error) => {
      // Handle error.
    });
    auth_msft_reauth_popup.js

    واجهة برمجة التطبيقات لمساحة الاسم على الويب

    var provider = new firebase.auth.OAuthProvider('microsoft.com');
firebase.auth().currentUser.reauthenticateWithPopup(provider)
    .then((result) => {
      // User is re-authenticated with fresh tokens minted and
      // should be able to perform sensitive operations like account
      // deletion and email or password update.
      // IdP data available in result.additionalUserInfo.profile.
      // OAuth access token can also be retrieved:
      // result.credential.accessToken
      // OAuth ID token can also be retrieved:
      // result.credential.idToken
    })
    .catch((error) => {
      // Handle error.
    });
    microsoft-oauth.js

المصادقة باستخدام Firebase في إحدى إضافات Chrome

إذا كنت تنشئ تطبيقًا لإضافة Chrome، يمكنك الاطّلاع على دليل المستندات خارج الشاشة.

الخطوات اللاحقة

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

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

  • في قاعدة بيانات Firebase في الوقت الفعلي وقواعد أمان Cloud Storage، يمكنك الحصول على رقم تعريف المستخدم الفريد للمستخدم الذي سجّل الدخول من المتغيّر auth واستخدامه للتحكّم في البيانات التي يمكن للمستخدم الوصول إليها.

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

لتسجيل خروج مستخدم، يمكنك الاتصال بالرقم signOut:

واجهة برمجة التطبيقات Web modular API

import { getAuth, signOut } from "firebase/auth";

const auth = getAuth();
signOut(auth).then(() => {
  // Sign-out successful.
}).catch((error) => {
  // An error happened.
});
auth_sign_out.js

واجهة برمجة التطبيقات لمساحة الاسم على الويب

firebase.auth().signOut().then(() => {
  // Sign-out successful.
}).catch((error) => {
  // An error happened.
});
index.js