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

با ادغام اصالت‌سنجی GitHub در برنامه‌تان، می‌توانید به کاربران اجازه دهید بااستفاده از حساب‌های GitHub خود با Firebase اصالت‌سنجی کنند. می‌توانید اصالت‌سنجی GitHub را بااستفاده از «کیت توسعه نرم‌افزار Firebase» برای انجام جریان ورود به سیستم یا با انجام جریان GitHub OAuth 2.0 به‌صورت دستی و انتقال کد دسترسی حاصل به Firebase ادغام کنید.

قبل از شروع

1. ‫Firebase را به پروژه جاوا اسکریپت خود اضافه کنید.
2. در کنسول Firebase، به امنیت > اصالت‌سنجی بروید.
3. در برگه روش ورود به سیستم، ارائه‌دهنده ورود به سیستم GitHub را فعال کنید.
4. شناسه کارخواه و رمز کارخواه را از کنسول توسعه‌دهنده آن ارائه‌دهنده به پیکربندی ارائه‌دهنده اضافه کنید:
   1. برنامه‌تان را به‌عنوان برنامه توسعه‌دهنده در GitHub ثبت کنید و شناسه مشتری و رمز مشتری برنامه خود را در OAuth 2.0 دریافت کنید.
   2. مطمئن شوید که نشانی وب هدایت OAuth در Firebase (برای مثال، my-app-12345.firebaseapp.com/__/auth/handler) به‌عنوان نشانی وب برگشت به تماس مجوز در صفحه تنظیمات برنامه شما در پیکربندی برنامه GitHub تنظیم شده باشد.
5. روی ذخیره کردن کلیک کنید.

مدیریت جریان ورود به سیستم با «کیت توسعه نرم‌افزار Firebase»

اگر درحال ساختن برنامه وب هستید، ساده‌ترین راه برای اصالت‌سنجی کاربران با Firebase بااستفاده از حساب‌های GitHub آن‌ها این است که جریان ورود به سیستم را با «کیت توسعه نرم‌افزار Firebase JavaScript» مدیریت کنید. (اگر می‌خواهید کاربری را در Node.js یا محیط غیرمرورگر دیگری اصالت‌سنجی کنید، باید جریان ورود به سیستم را به‌صورت دستی مدیریت کنید.)

برای مدیریت جریان ورود به سیستم با «کیت توسعه نرم‌افزار جاوا اسکریپت Firebase»، این مراحل را دنبال کنید:

1. نمونه‌ای از شیء ارائه‌دهنده GitHub ایجاد کنید:

   Web

   import { GithubAuthProvider } from "firebase/auth";
   
   const provider = new GithubAuthProvider();
   auth_github_provider_create.js

   Web

   var provider = new firebase.auth.GithubAuthProvider();
   github.js

2. اختیاری: دامنه‌های OAuth 2.0 اضافی را که می‌خواهید از ارائه‌دهنده اصالت‌سنجی درخواست کنید مشخص کنید. برای افزودن محدوده، addScope را فراخوانی کنید. برای مثال:

   Web

   provider.addScope('repo');
   auth_github_provider_scopes.js

   Web

   provider.addScope('repo');
   github.js

   مستندات ارائه‌دهنده اصالت‌سنجی را ببینید.
3. اختیاری: پارامترهای سفارشی ارائه‌دهنده OAuth اضافی را که می‌خواهید با درخواست OAuth ارسال کنید مشخص کنید. برای افزودن پارامتر سفارشی، setCustomParameters را در رساننده مقداردهی‌شده با شیئی که حاوی کلید طبق مشخصات مستندات رساننده OAuth و مقدار مربوطه است فراخوانی کنید. برای مثال:

   Web

   provider.setCustomParameters({
     'allow_signup': 'false'
   });
   auth_github_provider_params.js

   Web

   provider.setCustomParameters({
     'allow_signup': 'false'
   });
   github.js

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

     Web

     import { getAuth, signInWithPopup, GithubAuthProvider } from "firebase/auth";
     
     const auth = getAuth();
     signInWithPopup(auth, provider)
       .then((result) => {
         // This gives you a GitHub Access Token. You can use it to access the GitHub API.
         const credential = GithubAuthProvider.credentialFromResult(result);
         const token = credential.accessToken;
     
         // The signed-in user info.
         const user = result.user;
         // IdP data available using getAdditionalUserInfo(result)
         // ...
       }).catch((error) => {
         // Handle Errors here.
         const errorCode = error.code;
         const errorMessage = error.message;
         // The email of the user's account used.
         const email = error.customData.email;
         // The AuthCredential type that was used.
         const credential = GithubAuthProvider.credentialFromError(error);
         // ...
       });
     auth_github_signin_popup.js

     Web

     firebase
       .auth()
       .signInWithPopup(provider)
       .then((result) => {
         /** @type {firebase.auth.OAuthCredential} */
         var credential = result.credential;
     
         // This gives you a GitHub Access Token. You can use it to access the GitHub API.
         var token = credential.accessToken;
     
         // The signed-in user info.
         var user = result.user;
         // IdP data available in result.additionalUserInfo.profile.
           // ...
       }).catch((error) => {
         // Handle Errors here.
         var errorCode = error.code;
         var errorMessage = error.message;
         // The email of the user's account used.
         var email = error.email;
         // The firebase.auth.AuthCredential type that was used.
         var credential = error.credential;
         // ...
       });
     github.js

     همچنین توجه داشته باشید که می‌توانید نشان OAuth ارائه‌دهنده GitHub را بازیابی کنید که می‌توان از آن برای واکشی داده‌های اضافی بااستفاده از GitHub APIs استفاده کرد.

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

   • برای ورود به سیستم با هدایت به صفحه ورود به سیستم، signInWithRedirect را فراخوانی کنید: هنگام استفاده از `signInWithRedirect`، روال‌های مطلوب را دنبال کنید.

     Web

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

     Web

     firebase.auth().signInWithRedirect(provider);
     index.js

     سپس، می‌توانید با فراخوانی getRedirectResult هنگام بار شدن صفحه‌تان، رمز OAuth ارائه‌دهنده GitHub را نیز بازیابی کنید:

     Web

     import { getAuth, getRedirectResult, GithubAuthProvider } from "firebase/auth";
     
     const auth = getAuth();
     getRedirectResult(auth)
       .then((result) => {
         const credential = GithubAuthProvider.credentialFromResult(result);
         if (credential) {
           // This gives you a GitHub Access Token. You can use it to access the GitHub API.
           const token = credential.accessToken;
           // ...
         }
     
         // The signed-in user info.
         const user = result.user;
         // IdP data available using getAdditionalUserInfo(result)
         // ...
       }).catch((error) => {
         // Handle Errors here.
         const errorCode = error.code;
         const errorMessage = error.message;
         // The email of the user's account used.
         const email = error.customData.email;
         // The AuthCredential type that was used.
         const credential = GithubAuthProvider.credentialFromError(error);
         // ...
       });
     auth_github_signin_redirect_result.js

     Web

     firebase.auth()
       .getRedirectResult()
       .then((result) => {
         if (result.credential) {
           /** @type {firebase.auth.OAuthCredential} */
           var credential = result.credential;
     
           // This gives you a GitHub Access Token. You can use it to access the GitHub API.
           var token = credential.accessToken;
           // ...
         }
     
         // The signed-in user info.
         var user = result.user;
         // IdP data available in result.additionalUserInfo.profile.
           // ...
       }).catch((error) => {
         // Handle Errors here.
         var errorCode = error.code;
         var errorMessage = error.message;
         // The email of the user's account used.
         var email = error.email;
         // The firebase.auth.AuthCredential type that was used.
         var credential = error.credential;
         // ...
       });
     github.js

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

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

try {
  // Step 1: User tries to sign in using GitHub.
  let result = await signInWithPopup(getAuth(), new GitHubAuthProvider());
} catch (error) {
  // Step 2: User's email already exists.
  if (error.code === "auth/account-exists-with-different-credential") {
    // The pending GitHub 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 GitHub 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) {
  // ...
}

جریان ورود به سیستم را به‌صورت دستی مدیریت کنید

همچنین می‌توانید بااستفاده از حساب GitHub و با مدیریت جریان ورود به سیستم ازطریق فراخوانی نقطه‌های پایانی GitHub OAuth 2.0، با Firebase اصالت‌سنجی کنید:

1. با دنبال کردن مستندات توسعه‌دهنده، اصالت‌سنجی GitHub را در برنامه‌تان ادغام کنید. در پایان جریان ورود به سیستم GitHub، کد دسترسی OAuth 2.0 دریافت خواهید کرد.
2. اگر باید در برنامه Node.js به سیستم وارد شوید، رمز دسترسی OAuth را به برنامه Node.js ارسال کنید.
3. پس‌از اینکه کاربری باموفقیت با GitHub به سیستم وارد شد، کد دسترسی OAuth 2.0 را با اطلاعات اعتباری Firebase مبادله کنید:

   Web

   import { GithubAuthProvider } from "firebase/auth";
   
   const credential = GithubAuthProvider.credential(token);
   auth_github_provider_credential.js

   Web

   var credential = firebase.auth.GithubAuthProvider.credential(token);
   github.js

4. بااستفاده از اطلاعات اعتباری Firebase، با Firebase اصالت‌سنجی کنید:

   Web

   import { getAuth, signInWithCredential } from "firebase/auth";
   
   // Sign in with the credential from the user.
   const auth = getAuth();
   signInWithCredential(auth, credential)
     .then((result) => {
       // Signed in 
       // ...
     })
     .catch((error) => {
       // Handle Errors here.
       const errorCode = error.code;
       const errorMessage = error.message;
       // The email of the user's account used.
       const email = error.customData.email;
       // ...
     });
   auth_signin_credential.js

   Web

   // Sign in with the credential from the user.
   firebase.auth()
     .signInWithCredential(credential)
     .then((result) => {
       // Signed in 
       // ...
     })
     .catch((error) => {
       // Handle Errors here.
       const errorCode = error.code;
       const errorMessage = error.message;
       // The email of the user's account used.
       const email = error.email;
       // ...
     });
   index.js

اصالت‌سنجی با Firebase در افزونه Chrome

اگر درحال ساختن برنامه افزونه Chrome هستید، راهنمای «سندهای خارج از صفحه» را ببینید.

مراحل بعدی

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

• در برنامه‌هایتان، روش توصیه‌شده برای اطلاع از وضعیت اصالت‌سنجی کاربر این است که روی شیء Auth ناظر تنظیم کنید. سپس می‌توانید اطلاعات نمایه پایه کاربر را از شیء User دریافت کنید. به مدیریت کاربران مراجعه کنید.

• در Firebase Realtime Database و Cloud Storage قوانین امنیتی، می‌توانید شناسه کاربر یکتای کاربر واردشده به سیستم را از متغیر 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