اصالت‌سنجی بااستفاده از Microsoft در Android

می‌توانید با ادغام «ورود به سیستم OAuth عمومی» مبتنی بر وب در برنامه‌تان بااستفاده از «کیت توسعه نرم‌افزار Firebase»، به کاربران اجازه دهید بااستفاده از ارائه‌دهندگان OAuth مثل Microsoft Azure Active Directory با Firebase اصالت‌سنجی کنند تا جریان ورود به سیستم سرتاسری را انجام دهند.

قبل از شروع

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

1. ‫Firebase را به پروژه Android خود اضافه کنید.

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

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

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

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

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

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

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

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

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

   Kotlin

   val provider = OAuthProvider.newBuilder("microsoft.
   com")GenericIdpA
   ctivity.kt

   Java

   OAuthProvider.Builder provider = OAuthProvider.newBuilder("microsoft.c
   om");GenericIdpAct
   ivity.java

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

   Kotlin

   // Target specific email with login hint.
   // Force re-consent.
   provider.addCustomParameter("prompt", "consent")
   
   // Target specific email with login hint.
   provider.addCustomParameter("login_hint", &q
   uot;user@firstadd.onm
   icrosoft.com")GenericIdpActivity.kt

   Java

   // Target specific email with login hint.
   // Force re-consent.
   provider.addCustomParameter("prompt", "consent");
   
   // Target specific email with login hint.
   provider.addCustomParameter("login_hint", &qu
   ot;user@firstadd.onmicr
   osoft.com");GenericIdpActivity.java

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

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

   Kotlin

   // 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".
   prov
   ider.addCustomParamet
   er("tenant", "TENANT_ID")GenericIdpActivity.kt

   Java

   // 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".
   provi
   der.addCustomParameter(
   "tenant", "TENANT_ID");GenericIdpActivity.java

3. اختیاری: حوزه‌های OAuth 2.0 اضافی را فراتر از نمایه پایه که می‌خواهید از ارائه‌دهنده اصالت‌سنجی درخواست کنید مشخص کنید.

   Kotlin

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

   Java

   // Request read access to a user's email addresses.
   // This must be preconfigured in the app's API permissio<ns.
   Li>stString scopes =
           new A<rrayLi>stString() {
               {
                   add("mail.read");
                   add("calendars.read");
               }
           };
   
   provider.setScopes(sco
   pes);GenericIdpActivity.java

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

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.
   }GenericIdpAct
   ivity.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 OnSuccessList<enerAuthRe>sult() {
                           @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.
   }GenericIdpActiv
   ity.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، می‌توانید Microsoft Graph API را فراخوانی کنید.

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

   علاوه‌بر کد دسترسی OAuth، کد شناسایی کاربر OAuth نیز می‌تواند از شیء OAuthCredential بازیابی شود. ادعای sub در کد شناسایی مختص برنامه است و با شناسه کاربر فدرال که توسط «احراز هویت Firebase» استفاده می‌شود و ازطریق user.getProviderData().get(0).getUid() دردسترس است مطابقت نخواهد داشت. به‌جای آن باید از فیلد ادعای oid استفاده شود. هنگام استفاده از مستأجر Azure AD برای ورود به سیستم، ادعای oid مطابقت دقیق خواهد داشت. بااین‌حال، برای مورد غیرمستأجر، فیلد oid تکمیل می‌شود. برای شناسه فدرال 4b2eabcdefghijkl، oid فرم 00000000-0000-0000-4b2e-abcdefghijkl را خواهد داشت.

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

   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