احراز هویت با استفاده از مایکروسافت با جاوا اسکریپت، احراز هویت با استفاده از مایکروسافت با جاوا اسکریپت

شما می‌توانید با ادغام ورود عمومی OAuth در برنامه خود با استفاده از Firebase SDK برای انجام جریان ورود به سیستم سرتاسری، به کاربران خود اجازه دهید تا با استفاده از ارائه‌دهندگان OAuth مانند Microsoft Azure Active Directory، با Firebase احراز هویت کنند.

قبل از اینکه شروع کنی

برای ورود کاربران با استفاده از حساب‌های مایکروسافت (Azure Active Directory و حساب‌های شخصی مایکروسافت)، ابتدا باید مایکروسافت را به عنوان ارائه‌دهنده ورود به سیستم برای پروژه Firebase خود فعال کنید:

1. فایربیس را به پروژه جاوا اسکریپت خود اضافه کنید .
2. در کنسول Firebase ، به بخش امنیت > احراز هویت بروید.
3. در تب روش ورود ، ارائه دهنده ورود به سیستم مایکروسافت را فعال کنید.
4. شناسه کلاینت و راز کلاینت را از کنسول توسعه‌دهنده آن ارائه‌دهنده به پیکربندی ارائه‌دهنده اضافه کنید:
   1. برای ثبت یک کلاینت Microsoft OAuth، دستورالعمل‌های موجود در Quickstart را دنبال کنید: یک برنامه را با نقطه پایانی Azure Active Directory v2.0 ثبت کنید . توجه داشته باشید که این نقطه پایانی از ورود به سیستم با استفاده از حساب‌های شخصی مایکروسافت و همچنین حساب‌های Azure Active Directory پشتیبانی می‌کند. درباره Azure Active Directory v2.0 بیشتر بدانید.
   2. هنگام ثبت برنامه‌ها در این ارائه‌دهندگان، حتماً دامنه *.firebaseapp.com را برای پروژه خود به عنوان دامنه تغییر مسیر برای برنامه خود ثبت کنید.
5. روی ذخیره کلیک کنید.

مدیریت جریان ورود به سیستم با Firebase SDK

اگر در حال ساخت یک برنامه وب هستید، ساده‌ترین راه برای تأیید اعتبار کاربران خود با Firebase با استفاده از حساب‌های مایکروسافت آنها، مدیریت کل جریان ورود به سیستم با Firebase JavaScript SDK است.

برای مدیریت جریان ورود به سیستم با استفاده از Firebase JavaScript SDK، مراحل زیر را دنبال کنید:

1. با استفاده از شناسه ارائه دهنده microsoft.com، یک نمونه از OAuthProvider ایجاد کنید.

   Web

   import { OAuthProvider } from "firebase/auth";
   
   const provider = new OAuthProvider('microsoft.com');
   auth_msft_create_provider.js

   Web

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

2. اختیاری : پارامترهای سفارشی اضافی OAuth را که می‌خواهید با درخواست OAuth ارسال کنید، مشخص کنید.

   Web

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

   Web

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

   برای پارامترهایی که مایکروسافت پشتیبانی می‌کند، به مستندات OAuth مایکروسافت مراجعه کنید. توجه داشته باشید که نمی‌توانید پارامترهای مورد نیاز Firebase را با setCustomParameters() ارسال کنید. این پارامترها عبارتند از client_id ، response_type ، redirect_uri ، state ، scope و response_mode .

   برای اینکه فقط کاربران یک مستاجر خاص Azure AD بتوانند وارد برنامه شوند، می‌توان از نام دامنه آشنای مستاجر Azure AD یا شناسه GUID مستاجر استفاده کرد. این کار را می‌توان با مشخص کردن فیلد "مستاجر" در شیء پارامترهای سفارشی انجام داد.

   Web

   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

   Web

   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');

   برای کسب اطلاعات بیشتر، به مستندات مجوزها و رضایت‌نامه‌های مایکروسافت مراجعه کنید.

4. با استفاده از شیء ارائه دهنده OAuth، با Firebase احراز هویت کنید. می‌توانید با باز کردن یک پنجره پاپ‌آپ یا با هدایت به صفحه ورود، کاربران خود را به ورود با حساب‌های مایکروسافتشان ترغیب کنید. روش هدایت در دستگاه‌های تلفن همراه ترجیح داده می‌شود.

   • برای ورود به سیستم با یک پنجره پاپ‌آپ، تابع signInWithPopup را فراخوانی کنید:

   Web

   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

   Web

   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

   import { getAuth, signInWithRedirect } from "firebase/auth";
   
   const auth = getAuth();
   signInWithRedirect(auth, provider);
   auth_msft_signin_redirect.js

   Web

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

   پس از اینکه کاربر ورود به سیستم را تکمیل کرد و به صفحه بازگشت، می‌توانید با فراخوانی getRedirectResult نتیجه ورود به سیستم را دریافت کنید.

   Web

   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

   Web

   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 API زیر را فراخوانی کرد:

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

   برخلاف سایر ارائه‌دهندگان پشتیبانی‌شده توسط Firebase Auth، مایکروسافت آدرس اینترنتی عکس ارائه نمی‌دهد و در عوض، داده‌های دودویی برای عکس پروفایل باید از طریق Microsoft Graph API درخواست شوند.

   علاوه بر توکن دسترسی OAuth، توکن شناسه OAuth کاربر نیز می‌تواند از شیء firebase.auth.UserCredential بازیابی شود. ادعای sub در توکن شناسه مختص برنامه است و با شناسه کاربر فدرال مورد استفاده توسط Firebase Auth که از طریق user.providerData[0].uid قابل دسترسی است، مطابقت نخواهد داشت. به جای آن باید از فیلد oid claim استفاده شود. هنگام استفاده از یک مستاجر Azure AD برای ورود به سیستم، ادعای oid دقیقاً مطابقت خواهد داشت. با این حال، برای مورد غیر مستاجر، فیلد oid پر شده است. برای یک شناسه فدرال 4b2eabcdefghijkl ، oid فرمی به شکل 00000000-0000-0000-4b2e-abcdefghijkl خواهد داشت.

5. در حالی که مثال‌های بالا بر جریان‌های ورود به سیستم تمرکز دارند، شما همچنین می‌توانید با استفاده از linkWithPopup / linkWithRedirect ، یک ارائه‌دهنده مایکروسافت را به یک کاربر موجود پیوند دهید. به عنوان مثال، می‌توانید چندین ارائه‌دهنده را به یک کاربر پیوند دهید و به آنها اجازه دهید با هر یک از آنها وارد سیستم شوند.

   Web

   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

   Web

   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

   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

   Web

   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

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

try {
  // Step 1: User tries to sign in using Microsoft.
  let result = await signInWithPopup(getAuth(), new OAuthProvider());
} catch (error) {
  // Step 2: User's email already exists.
  if (error.code === "auth/account-exists-with-different-credential") {
    // The pending Microsoft credential.
    let pendingCred = error.credential;

    // Step 3: Save the pending credential in temporary storage,

    // Step 4: Let the user know that they already have an account
    // but with a different provider, and let them choose another
    // sign-in method.
  }
}

// ...

try {
  // Step 5: Sign the user in using their chosen method.
  let result = await signInWithPopup(getAuth(), userSelectedProvider);

  // Step 6: Link to the Microsoft credential.
  // TODO: implement `retrievePendingCred` for your app.
  let pendingCred = retrievePendingCred();

  if (pendingCred !== null) {
    // As you have access to the pending credential, you can directly call the
    // link method.
    let user = await linkWithCredential(result.user, pendingCred);
  }

  // Step 7: Continue to app.
} catch (error) {
  // ...
}

احراز هویت با Firebase در افزونه Chrome

اگر در حال ساخت یک برنامه افزونه کروم هستید، به راهنمای اسناد Offscreen مراجعه کنید.

مراحل بعدی

پس از اینکه کاربر برای اولین بار وارد سیستم می‌شود، یک حساب کاربری جدید ایجاد می‌شود و به اطلاعات احراز هویت - یعنی نام کاربری و رمز عبور، شماره تلفن یا اطلاعات ارائه دهنده مجوز - که کاربر با آن وارد سیستم شده است، پیوند داده می‌شود. این حساب جدید به عنوان بخشی از پروژه Firebase شما ذخیره می‌شود و می‌تواند برای شناسایی کاربر در هر برنامه در پروژه شما، صرف نظر از نحوه ورود کاربر، مورد استفاده قرار گیرد.

• در برنامه‌های شما، روش پیشنهادی برای اطلاع از وضعیت احراز هویت کاربر، تنظیم یک ناظر (observer) روی شیء Auth است. سپس می‌توانید اطلاعات اولیه پروفایل کاربر را از شیء User دریافت کنید. به بخش مدیریت کاربران (Manage Users) مراجعه کنید.

• در قوانین امنیتی پایگاه داده و Cloud Storage Firebase Realtime Database ، می‌توانید شناسه کاربری منحصر به فرد کاربر وارد شده را از متغیر auth دریافت کنید و از آن برای کنترل داده‌هایی که کاربر می‌تواند به آنها دسترسی داشته باشد، استفاده کنید.

شما می‌توانید با پیوند دادن اعتبارنامه‌های ارائه‌دهنده‌ی احراز هویت به یک حساب کاربری موجود، به کاربران اجازه دهید با استفاده از چندین ارائه‌دهنده‌ی احراز هویت به برنامه‌ی شما وارد شوند.

برای خروج کاربر، signOut را فراخوانی کنید:

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