اعتبارنامه‌های خود را با ارائه‌دهندگان اعتبارنامه‌ها هماهنگ نگه دارید

وقتی کاربری رمز عبور ایجاد می‌کند، سرور طرفِ متکی جزئیات خاصی را ذخیره می‌کند، در حالی که ارائه‌دهنده‌ی اعتبارنامه، مانند Google Password Manager، سایر جزئیات را ذخیره می‌کند. به طور خاص:

• سرور طرف اعتمادکننده، اعتبارنامه کلید عمومی را ذخیره می‌کند.
• ارائه‌دهنده‌ی اعتبارنامه، نام کاربری، نام نمایشی، کلید خصوصی و سایر فراداده‌های مرتبط را ذخیره می‌کند. این فراداده‌ها به کاربران کمک می‌کنند تا هنگام ورود به سیستم، کلید عبور مورد نیاز را شناسایی و انتخاب کنند.

ناسازگاری‌های احتمالی بین داده‌های ذخیره شده در سرور طرف اعتمادکننده و ارائه‌دهنده اعتبارنامه می‌تواند منجر به تجربه‌های کاربری بد شود. مشکلات ممکن است در سناریوهای زیر ایجاد شوند:

• یک اعتبارنامه روی سرور طرفِ متکی حذف می‌شود اما روی ارائه‌دهنده‌ی اعتبارنامه حذف نمی‌شود، که منجر به نمایش اعتبارنامه‌ی حذف‌شده توسط ارائه‌دهنده‌ی اعتبارنامه به کاربر می‌شود.
• نام کاربری یا نام نمایشی در سرور طرف متکی به‌روزرسانی می‌شود اما در ارائه‌دهنده‌ی اعتبارنامه به‌روزرسانی نمی‌شود، که منجر به نمایش جزئیات قدیمی توسط ارائه‌دهنده‌ی اعتبارنامه می‌شود.

رابط برنامه‌نویسی کاربردی سیگنالِ مدیریت اعتبارنامه (Credential Manager) به طرفینِ متکی اجازه می‌دهد تا با ارائه‌دهندگان اعتبارنامه ارتباط برقرار کنند تا اعتبارنامه‌ها را حذف کرده و فراداده‌های کاربر، مانند نام کاربری و نام نمایشی را به‌روزرسانی کنند. سه نوع درخواست پشتیبانی‌شده برای سناریوهای مختلف وجود دارد:

• SignalUnknownCredentialRequest

  • نشان می‌دهد که یک اعتبارنامه خاص دیگر معتبر نیست و باید از ارائه‌دهنده اعتبارنامه پنهان یا حذف شود.

• SignalAllAcceptedCredentialIdsRequest

  • فهرستی از شناسه‌های اعتبارنامه‌ی پذیرفته‌شده را در اختیار ارائه‌دهنده‌ی اعتبارنامه قرار می‌دهد.

• SignalCurrentUserDetailsRequest

  • جزئیات فراداده کاربر را به‌روزرسانی می‌کند.

سازگاری نسخه

API سیگنال در دستگاه‌هایی که اندروید ۱۵ یا بالاتر را اجرا می‌کنند، موجود است و از نسخه 1.6.0-beta03 کتابخانه androidx.credentials شروع می‌شود.

پیاده‌سازی

برای استفاده از API سیگنال، مراحل زیر را دنبال کنید:

1. وابستگی Credential Manager را به پروژه خود اضافه کنید.

   توجه: API سیگنال از credentials 1.6.0-beta03 به بعد در دسترس است، با این حال در صورت امکان، از آخرین نسخه کتابخانه استفاده کنید.

   کاتلین

   dependencies {
       implementation("androidx.credentials:credentials:1.6.0-rc01")
   }

   شیار

   dependencies {
       implementation "androidx.credentials:credentials:1.6.0-rc01"
   }

2. فراخوانی API سیگنال

   برای ارسال درخواست سیگنال به ارائه دهنده اعتبارنامه، از یک درخواست سیگنال پشتیبانی شده استفاده کنید. هر یک از انواع درخواست سیگنال به یک درخواست JSON نیاز دارد، همانطور که در مثال‌های زیر نشان داده شده است:

   • اعتبارنامه‌ی ناشناخته ( SignalUnknownCredentialRequest )

     از SignalUnknownCredentialRequest برای اعلام اینکه یک اعتبارنامه رد شده و ناشناخته تلقی می‌شود، استفاده کنید. وقتی ارائه‌دهنده اعتبارنامه این سیگنال را دریافت می‌کند، اعتبارنامه را پنهان یا حذف می‌کند.

     کاربرد

     از این سیگنال زمانی استفاده کنید که طرف اعتمادکننده نتواند ادعای کلید عبور را تأیید کند. این بدان معناست که کلید عبور نامعتبر است و باید از ارائه‌دهنده اعتبارنامه پنهان یا حذف شود.

     پارامترهای JSON مورد نیاز برای این درخواست rpId و credentialId هستند. برای اطلاعات بیشتر در مورد ساختار JSON، به گزینه‌های signalUnknownCredential مراجعه کنید.

     credentialManager.signalCredentialState(
         SignalUnknownCredentialRequest(
             requestJson = JSONObject().apply {
                 put("rpId", rpId /* [String] RP ID of the relying party */)
                 put("credentialId", credentialId /* [String] Credential ID of the credential to be hidden or deleted */)
             }.toString()
         )
     )
     

   • همه اعتبارنامه‌های پذیرفته‌شده ( SignalAllAcceptedCredentialIdsRequest )

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

     نکته: وقتی کاربری احراز هویت می‌شود، این سیگنال را به SignalUnknownCredentialRequest ترجیح دهید.

     کاربرد

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

     پارامترهای JSON مورد نیاز برای این درخواست عبارتند از rpId ، userId و allAcceptedCredentialIds . برای اطلاعات بیشتر در مورد ساختار JSON، به گزینه‌های signalAllAcceptedCredential مراجعه کنید.

     credentialManager.signalCredentialState(
         SignalAllAcceptedCredentialIdsRequest(
             requestJson = JSONObject().apply {
                 put("rpId", rpId /* [String] RP ID of the relying party */)
                 put("userId", userId /* [String] User ID of the current user */)
                 put(
                     "allAcceptedCredentialIds",
                     JSONArray(credentialIdsList /* [List<String>] List of accepted Credential IDs */)
                 )
             }.toString()
         )
     )
     

   • جزئیات کاربر فعلی ( SignalCurrentUserDetailsRequest )

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

     کاربرد

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

     پارامترهای JSON مورد نیاز برای این درخواست عبارتند از rpId ، userId ، name و displayName . برای اطلاعات بیشتر در مورد ساختار JSON، به گزینه‌های signalCurrentUserDetails مراجعه کنید.

     credentialManager.signalCredentialState(
         SignalCurrentUserDetailsRequest(
             requestJson = JSONObject().apply {
                 put("rpId", rpId /* [String] RP ID of the relying party */)
                 put("userId", userId /* [String] User ID of the current user */)
                 put("name", name /* [String] New Name to be updated for the current user */)
                 put("displayName", displayName /* [String] New display name to be updated for the current user */)
             }.toString()
         )
     )
     

   توجه: رابط برنامه‌نویسی کاربردی سیگنال مدیریت اعتبارنامه از اجرای پس‌زمینه پشتیبانی می‌کند، اگرچه طرفین متکی باید فرکانس تماس را به حداکثر 10 تماس در هر پنجره زمانی 120 ثانیه محدود کنند تا در آستانه‌های محدودیت سرعت تعیین‌شده باقی بمانند. سیگنال‌دهی بیش از حد ممکن است منجر به اختلال در سرویس یا رد درخواست شود.

پیاده‌سازی را آزمایش کنید

برای آزمایش پیاده‌سازی Signal API خود، مراحل زیر را انجام دهید:

1. نمونه ارائه دهنده اعتبارنامه با نام MyVault را نصب کنید.

   توجه: برنامه MyVault فقط برای اهداف آزمایشی است.

2. MyVault را به عنوان ارائه دهنده اعتبارنامه در تنظیمات > رمزهای عبور، کلیدهای عبور و حساب‌ها > سرویس ترجیحی فعال کنید.

   

3. همه اعلان‌های MyVault را در تنظیمات > برنامه‌ها > MyVault > اعلان‌ها فعال کنید.

   

4. مطمئن شوید که قابلیت «باز شدن روی صفحه» برای اعلان‌ها در تنظیمات > برنامه‌ها > من‌ولت > اعلان‌ها > دسته‌بندی‌ها > کانال اعلان API سیگنال فعال است.

   

5. در برنامه خود، جریان‌هایی را فعال کنید که درخواست‌های سیگنال را به ارائه‌دهنده اعتبارنامه ارسال می‌کنند. باید اعلان‌هایی از MyVault را روی صفحه مشاهده کنید. این تأیید می‌کند که ارائه‌دهنده اعتبارنامه درخواست‌ها را دریافت کرده است.