احراز هویت بااستفاده از GitHub در Android

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

قبل از شروع

برای ورود به سیستم کاربران بااستفاده از حساب‌های GitHub، ابتدا باید GitHub را به‌عنوان ارائه‌دهنده ورود به سیستم برای پروژه Firebase خود فعال کنید:

1. اگر قبلاً این کار را نکرده‌اید، ‫Firebase را به پروژه Android خود اضافه کنید.

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

6. در فایل Gradle واحد (سطح برنامه) (معمولاً <project>/<app-module>/build.gradle.kts یا <project>/<app-module>/build.gradle)، وابستگی کتابخانه Firebase Authentication را برای Android اضافه کنید. توصیه می‌کنیم از Firebase Android BoM برای کنترل نسخه‌بندی کتابخانه استفاده کنید.

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:35.0.0"))
   
       // Add the dependency for the Firebase Authentication library
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-auth")
   }

   بااستفاده از Firebase Android BoM، برنامه شما همیشه از نسخه‌های سازگار کتابخانه‌های Firebase Android استفاده خواهد کرد.

   (جایگزین)  افزودن وابستگی‌های کتابخانه Firebase بدون استفاده از BoM

   اگر انتخاب کنید که از Firebase BoM استفاده نکنید، باید نسخه هر کتابخانه Firebase را در خط وابستگی آن مشخص کنید.

   توجه داشته باشید که اگر از چند کتابخانه Firebase در برنامه‌تان استفاده می‌کنید، قویاً توصیه می‌کنیم از BoM برای مدیریت نسخه‌های کتابخانه استفاده کنید، که تضمین می‌کند همه نسخه‌ها سازگار باشند.

   dependencies {
       // Add the dependency for the Firebase Authentication library
       // When NOT using the BoM, you must specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-auth:25.0.0")
   }

7. اگر قبلاً اثر انگشت SHA-1 برنامه‌تان را مشخص نکرده‌اید، آن را مشخص کنید.

   1. در کنسول Firebase، به settings تنظیمات > زبانه کلی بروید.

   2. به کارت برنامه‌های شما پیمایش کنید، برنامه Android خود را انتخاب کنید، و اثر انگشت SHA-1 خود را در فیلد اثر انگشت‌های گواهینامه SHA اضافه کنید.

   برای جزئیات مربوط به نحوه دریافت اثر انگشت SHA برنامه، به اصالت‌سنجی مشتری مراجعه کنید.

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

اگر درحال ساختن برنامه Android هستید، ساده‌ترین راه برای اصالت‌سنجی کاربران با Firebase بااستفاده از حساب‌های GitHub آن‌ها این است که کل جریان ورود به سیستم را با «کیت توسعه نرم‌افزار Firebase ویژه Android» مدیریت کنید.

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

1. بااستفاده از سازنده آن با شناسه ارائه‌دهنده github.com، نمونه‌ای از OAuthProvider بسازید

   Kotlin

   val provider = OAuthProvider.newBuilder("github.com")
   GenericIdpActivity.kt

   Java

   OAuthProvider.Builder provider = OAuthProvider.newBuilder("github.com");
   GenericIdpActivity.java

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

   Kotlin

   // Target specific email with login hint.
   provider.addCustomParameter("login", "your-email@gmail.com")
   GenericIdpActivity.kt

   Java

   // Target specific email with login hint.
   provider.addCustomParameter("login", "your-email@gmail.com");
   GenericIdpActivity.java

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

3. اختیاری: دامنه‌های OAuth 2.0 اضافی را فراتر از نمایه پایه که می‌خواهید از ارائه‌دهنده اصالت‌سنجی درخواست کنید مشخص کنید. اگر برنامه شما نیاز به دسترسی به داده‌های خصوصی کاربر از GitHub APIs دارد، باید در کنسول توسعه‌دهندگان GitHub، تحت اجازه‌های API، اجازه‌های دسترسی به GitHub APIs را درخواست کنید. محدوده‌های OAuth درخواستی باید دقیقاً با محدوده‌های ازپیش‌پیکربندی‌شده در اجازه‌های API برنامه مطابقت داشته باشند.

   Kotlin

   // Request read access to a user's email addresses.
   // This must be preconfigured in the app's API permissions.
   provider.scopes = listOf("user:email")
   GenericIdpActivity.kt

   Java

   // Request read access to a user's email addresses.
   // This must be preconfigured in the app's API permissions.
   List<String> scopes =
           new ArrayList<String>() {
               {
                   add("user:email");
               }
           };
   provider.setScopes(scopes);
   GenericIdpActivity.java

4. بااستفاده از شیء ارائه‌دهنده OAuth، با Firebase اصالت‌سنجی کنید. توجه داشته باشید که برخلاف دیگر عملیات FirebaseAuth، این عملیات با بالا آوردن برگه سفارشی Chrome کنترل واسط کاربر شما را دراختیار می‌گیرد. درنتیجه، به «فعالیت» خود در OnSuccessListener و OnFailureListener که پیوست می‌کنید ارجاع ندهید زیرا وقتی عملکرد رابط کاربری شروع می‌شود، بلافاصله جدا می‌شوند.

   ابتدا باید بررسی کنید که قبلاً پاسخی دریافت کرده‌اید یا نه. ورود به سیستم ازطریق این روش «فعالیت» شما را در پس‌زمینه قرار می‌دهد، به این معنی که سیستم می‌تواند آن را درطول جریان ورود به سیستم پس بگیرد. برای اینکه مطمئن شوید اگر این اتفاق افتاد کاربر را مجبور به تلاش مجدد نمی‌کنید، باید بررسی کنید که آیا نتیجه‌ای ازقبل وجود دارد یا نه.

   برای بررسی اینکه نتیجه معلقی وجود دارد یا نه، با getPendingAuthResult تماس بگیرید:

   Kotlin

   val pendingResultTask = firebaseAuth.pendingAuthResult
   if (pendingResultTask != null) {
       // There's something already here! Finish the sign-in for your user.
       pendingResultTask
           .addOnSuccessListener {
               // User is signed in.
               // IdP data available in
               // authResult.getAdditionalUserInfo().getProfile().
               // The OAuth access token can also be retrieved:
               // ((OAuthCredential)authResult.getCredential()).getAccessToken().
               // The OAuth secret can be retrieved by calling:
               // ((OAuthCredential)authResult.getCredential()).getSecret().
           }
           .addOnFailureListener {
               // Handle failure.
           }
   } else {
       // There's no pending result so you need to start the sign-in flow.
       // See below.
   }
   GenericIdpActivity.kt

   Java

   Task<AuthResult> pendingResultTask = firebaseAuth.getPendingAuthResult();
   if (pendingResultTask != null) {
       // There's something already here! Finish the sign-in for your user.
       pendingResultTask
               .addOnSuccessListener(
                       new OnSuccessListener<AuthResult>() {
                           @Override
                           public void onSuccess(AuthResult authResult) {
                               // User is signed in.
                               // IdP data available in
                               // authResult.getAdditionalUserInfo().getProfile().
                               // The OAuth access token can also be retrieved:
                               // ((OAuthCredential)authResult.getCredential()).getAccessToken().
                               // The OAuth secret can be retrieved by calling:
                               // ((OAuthCredential)authResult.getCredential()).getSecret().
                           }
                       })
               .addOnFailureListener(
                       new OnFailureListener() {
                           @Override
                           public void onFailure(@NonNull Exception e) {
                               // Handle failure.
                           }
                       });
   } else {
       // There's no pending result so you need to start the sign-in flow.
       // See below.
   }
   GenericIdpActivity.java

   برای شروع جریان ورود به سیستم، startActivityForSignInWithProvider را فراخوانی کنید:

   Kotlin

   firebaseAuth
       .startActivityForSignInWithProvider(activity, provider.build())
       .addOnSuccessListener {
           // User is signed in.
           // IdP data available in
           // authResult.getAdditionalUserInfo().getProfile().
           // The OAuth access token can also be retrieved:
           // ((OAuthCredential)authResult.getCredential()).getAccessToken().
           // The OAuth secret can be retrieved by calling:
           // ((OAuthCredential)authResult.getCredential()).getSecret().
       }
       .addOnFailureListener {
           // Handle failure.
       }
   GenericIdpActivity.kt

   Java

   firebaseAuth
           .startActivityForSignInWithProvider(/* activity= */ this, provider.build())
           .addOnSuccessListener(
                   new OnSuccessListener<AuthResult>() {
                       @Override
                       public void onSuccess(AuthResult authResult) {
                           // User is signed in.
                           // IdP data available in
                           // authResult.getAdditionalUserInfo().getProfile().
                           // The OAuth access token can also be retrieved:
                           // ((OAuthCredential)authResult.getCredential()).getAccessToken().
                           // The OAuth secret can be retrieved by calling:
                           // ((OAuthCredential)authResult.getCredential()).getSecret().
                       }
                   })
           .addOnFailureListener(
                   new OnFailureListener() {
                       @Override
                       public void onFailure(@NonNull Exception e) {
                           // Handle failure.
                       }
                   });
   GenericIdpActivity.java

   پس‌از تکمیل موفقیت‌آمیز، کد دسترسی OAuth مرتبط با ارائه‌دهنده را می‌توان از شیء OAuthCredential برگشتی بازیابی کرد.

   بااستفاده از کد دسترسی OAuth، می‌توانید GitHub API را فراخوانی کنید.

   برای مثال، برای دریافت اطلاعات نمایه پایه، می‌توانید با REST API تماس بگیرید و گذر دسترسی را در سرایند Authorization ارسال کنید:

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

   Kotlin

   // The user is already signed-in.
   val firebaseUser = firebaseAuth.currentUser!!
   firebaseUser
       .startActivityForLinkWithProvider(activity, provider.build())
       .addOnSuccessListener {
           // Provider credential is linked to the current user.
           // IdP data available in
           // authResult.getAdditionalUserInfo().getProfile().
           // The OAuth access token can also be retrieved:
           // authResult.getCredential().getAccessToken().
           // The OAuth secret can be retrieved by calling:
           // authResult.getCredential().getSecret().
       }
       .addOnFailureListener {
           // Handle failure.
       }
   GenericIdpActivity.kt

   Java

   // The user is already signed-in.
   FirebaseUser firebaseUser = firebaseAuth.getCurrentUser();
   
   firebaseUser
           .startActivityForLinkWithProvider(/* activity= */ this, provider.build())
           .addOnSuccessListener(
                   new OnSuccessListener<AuthResult>() {
                       @Override
                       public void onSuccess(AuthResult authResult) {
                           // Provider credential is linked to the current user.
                           // IdP data available in
                           // authResult.getAdditionalUserInfo().getProfile().
                           // The OAuth access token can also be retrieved:
                           // authResult.getCredential().getAccessToken().
                           // The OAuth secret can be retrieved by calling:
                           // authResult.getCredential().getSecret().
                       }
                   })
           .addOnFailureListener(
                   new OnFailureListener() {
                       @Override
                       public void onFailure(@NonNull Exception e) {
                           // Handle failure.
                       }
                   });
   GenericIdpActivity.java

6. از همین الگو می‌توان با startActivityForReauthenticateWithProvider استفاده کرد که می‌توان از آن برای بازیابی اعتبارنامه‌های جدید برای عملیات حساس که نیاز به ورود به سیستم اخیر دارند استفاده کرد.

   Kotlin

   // The user is already signed-in.
   val firebaseUser = firebaseAuth.currentUser!!
   firebaseUser
       .startActivityForReauthenticateWithProvider(activity, provider.build())
       .addOnSuccessListener {
           // User is re-authenticated with fresh tokens and
           // should be able to perform sensitive operations
           // like account deletion and email or password
           // update.
       }
       .addOnFailureListener {
           // Handle failure.
       }
   GenericIdpActivity.kt

   Java

   // The user is already signed-in.
   FirebaseUser firebaseUser = firebaseAuth.getCurrentUser();
   
   firebaseUser
           .startActivityForReauthenticateWithProvider(/* activity= */ this, provider.build())
           .addOnSuccessListener(
                   new OnSuccessListener<AuthResult>() {
                       @Override
                       public void onSuccess(AuthResult authResult) {
                           // User is re-authenticated with fresh tokens and
                           // should be able to perform sensitive operations
                           // like account deletion and email or password
                           // update.
                       }
                   })
           .addOnFailureListener(
                   new OnFailureListener() {
                       @Override
                       public void onFailure(@NonNull Exception e) {
                           // Handle failure.
                       }
                   });
   GenericIdpActivity.java

مراحل بعدی

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

• در برنامه‌هایتان، می‌توانید اطلاعات نمایه پایه کاربر را از FirebaseUser شیء دریافت کنید. مدیریت کاربران را ببینید.

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

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

برای خروج از سیستم کاربر، signOut را فراخوانی کنید:

Firebase.auth.signOut()
MainActivity.kt

FirebaseAuth.getInstance().signOut();
MainActivity.java