پیاده‌سازی بازیابی اعتبارنامه‌ها با Credential Manager

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

سازگاری نسخه

قابلیت Restore Credentials در Credential Manager روی دستگاه‌هایی که اندروید ۹ و بالاتر، نسخه هسته سرویس‌های گوگل پلی (GMS) 24220000 یا بالاتر و نسخه ۱.۵.۰ یا بالاتر از کتابخانه androidx.credentials را اجرا می‌کنند، کار می‌کند.

پیش‌نیازها

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

وابستگی‌ها

وابستگی‌های زیر را به فایل build.gradle ماژول برنامه خود اضافه کنید:

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha03")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha03")
}

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha03"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha03"
}

بازیابی اعتبارنامه‌ها از نسخه ۱.۵.۰ و بالاتر کتابخانه androidx.credentials در دسترس است. با این حال، توصیه می‌شود در صورت امکان از آخرین نسخه‌های پایدار وابستگی‌ها استفاده کنید.

نمای کلی

1. ایجاد کلید بازیابی : برای ایجاد کلید بازیابی، مراحل زیر را انجام دهید:
   1. نمونه‌سازی مدیر اعتبارنامه : یک شیء CredentialManager ایجاد کنید.
   2. دریافت گزینه‌های ایجاد اعتبارنامه از سرور برنامه : جزئیات مورد نیاز برای ایجاد کلید بازیابی از سرور برنامه خود را برای برنامه کلاینت ارسال کنید.
   3. ایجاد کلید بازیابی : اگر کاربر وارد برنامه شما شده است، یک کلید بازیابی برای حساب کاربری او ایجاد کنید.
   4. مدیریت پاسخ ایجاد اعتبارنامه : اعتبارنامه‌ها را از برنامه‌ی کلاینت خود برای پردازش به سرور برنامه ارسال کنید و هرگونه استثنا را مدیریت کنید.
2. ورود با کلید بازیابی : برای ورود به سیستم با کلید بازیابی، مراحل زیر را انجام دهید:
   1. دریافت گزینه‌های بازیابی اعتبارنامه از سرور برنامه : جزئیات مورد نیاز برای بازیابی کلید بازیابی از سرور برنامه خود را برای برنامه کلاینت ارسال کنید.
   2. دریافت کلید بازیابی : وقتی کاربر دستگاه جدیدی را راه‌اندازی می‌کند، کلید بازیابی را از Credential Manager درخواست کنید. این به کاربر اجازه می‌دهد بدون وارد کردن اطلاعات اضافی وارد سیستم شود.
   3. مدیریت پاسخ بازیابی اعتبارنامه : ارسال کلید بازیابی از برنامه‌ی کلاینت به سرور برنامه برای ورود کاربر.
3. یک کلید بازیابی را حذف کنید .

ایجاد کلید بازیابی

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

• اگر کاربر وارد سیستم شده باشد و کلید بازیابی از قبل ایجاد نشده باشد (مانند متد onCreate برای Activity اصلی).
• وقتی کاربر در حال ورود به سیستم یا تکمیل فرآیند ثبت نام حساب جدید است.

برای بهینه‌سازی عملکرد و جلوگیری از سربار ایجاد یا بررسی اعتبارنامه بازیابی در هر ورود، یک پرچم boolean یا یک مهر زمانی ایجاد اعتبارنامه در حافظه محلی، مانند has_synced_restore_credential ، تنظیم کنید تا ردیابی شود که آیا کلید قبلاً ایجاد شده است یا خیر.

مدیر اعتبارنامه را به صورت نمونه معرفی کنید

از زمینه فعالیت برنامه خود برای نمونه‌سازی یک شیء CredentialManager استفاده کنید.

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

گزینه‌های ایجاد اعتبارنامه را از سرور برنامه خود دریافت کنید

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

کلید بازیابی را ایجاد کنید

پس از تجزیه گزینه‌های ایجاد کلید عمومی ارسال شده توسط سرور، با قرار دادن این گزینه‌ها در یک شیء CreateRestoreCredentialRequest و فراخوانی متد createCredential() با شیء CredentialManager یک کلید بازیابی ایجاد کنید.

// createRestoreRequest contains the details sent by the server 
val response = credentialManager.createCredential(context, createRestoreRequest)

نکات کلیدی در مورد کد

• شیء CreateRestoreCredentialRequest شامل فیلدهای زیر است:

  • requestJson : گزینه‌های ایجاد اعتبارنامه که توسط سرور برنامه در قالب API احراز هویت وب برای PublicKeyCredentialCreationOptionsJSON ارسال می‌شود.

  • isCloudBackupEnabled : فیلد Boolean برای تعیین اینکه آیا کلید بازیابی باید در فضای ابری پشتیبان‌گیری شود یا خیر. به طور پیش‌فرض، این پرچم true است. این فیلد دارای این مقادیر است:

    • true : ( توصیه می‌شود ) این مقدار در صورتی که کاربر Google Backup و رمزگذاری سرتاسری، مانند قفل صفحه، را فعال کرده باشد، امکان پشتیبان‌گیری از کلیدهای بازیابی در فضای ابری را فراهم می‌کند.
    • false : این مقدار کلید را به صورت محلی ذخیره می‌کند و نه در فضای ابری. اگر کاربر بازیابی از فضای ابری را انتخاب کند، کلید در دستگاه جدید در دسترس نخواهد بود.

مدیریت پاسخ ایجاد اعتبارنامه

رابط برنامه‌نویسی مدیریت اعتبارنامه (Credential Manager API) پاسخی از نوع CreateRestoreCredentialResponse برمی‌گرداند. این پاسخ، کلید عمومی پاسخ ثبت اعتبارنامه را در قالب JSON نگه می‌دارد.

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

در طول فرآیند ایجاد کلید بازیابی، این استثنائات را مدیریت کنید:

• CreateRestoreCredentialDomException : این استثنا زمانی رخ می‌دهد که requestJson نامعتبر باشد و از قالب WebAuthn برای PublicKeyCredentialCreationOptionsJSON پیروی نکند.
• E2eeUnavailableException : این استثنا در صورتی رخ می‌دهد که isCloudBackupEnabled true باشد، اما دستگاه کاربر فاقد پشتیبان‌گیری از داده‌ها یا رمزگذاری سرتاسری مانند قفل صفحه باشد.
  برای اطمینان از اینکه Restore Credentials در همه موارد ایجاد می‌شود، باید E2eeUnavailableException را به طور صریح با فراخوانی createCredential با isCloudBackupEnabled تنظیم شده روی true مدیریت کنید. اگر E2eeUnavailableException رخ داد، catch را بگیرید و createCredential را دوباره با isCloudBackupEnabled تنظیم شده روی false فراخوانی کنید.
• IllegalArgumentException : این استثنا در صورتی رخ می‌دهد که createRestoreRequest خالی باشد یا JSON معتبری نداشته باشد، یا اگر user.id معتبری مطابق با مشخصات WebAuthn نداشته باشد.

با کلید بازیابی وارد شوید

از گزینه‌ی «بازگرداندن اعتبارنامه‌ها» برای ورود بی‌سروصدای کاربر در طول فرآیند راه‌اندازی دستگاه استفاده کنید.

گزینه‌های بازیابی اعتبارنامه را از سرور برنامه دریافت کنید

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

کلید بازیابی را دریافت کنید

برای دریافت کلید بازیابی در دستگاه جدید، متد getCredential() را در شیء CredentialManager فراخوانی کنید.

توصیه می‌شود در هر دو سناریوی زیر، کلید بازیابی را دریافت کنید:

• در اولین اجرای برنامه روی دستگاه. بازیابی اعتبارنامه در این سناریو مستقل از بازیابی داده‌های برنامه است.
• اگر پشتیبان‌گیری و بازیابی داده‌های برنامه فعال است، کلید بازیابی را بلافاصله پس از بازیابی داده‌های برنامه دریافت کنید. از BackupAgent برای پیکربندی پشتیبان‌گیری برنامه خود استفاده کنید و مطمئن شوید که عملکرد getCredential را در فراخوانی onRestoreFinished تکمیل کرده‌اید. از متد onRestore استفاده نکنید، زیرا فقط برای پشتیبان‌گیری‌های key-value فراخوانی می‌شود، در حالی که onRestoreFinished به طور قابل اعتمادی برای هر نوع بازیابی پشتیبان فراخوانی می‌شود. این کار از تأخیرهای احتمالی هنگام باز کردن دستگاه جدید توسط کاربران برای اولین بار جلوگیری می‌کند و به کاربران اجازه می‌دهد بدون انتظار برای باز کردن برنامه شما، با برنامه تعامل داشته باشند. به عنوان مثال، این به برنامه شما اجازه می‌دهد قبل از باز کردن برنامه برای اولین بار در دستگاه جدید، اعلان‌هایی را برای کاربر ارسال کند، که به ویژه برای برنامه‌های پیام‌رسانی یا ارتباطی مرتبط است.

// Fetch the options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

val response = credentialManager.getCredential(context, getRequest)

// Type-check and extract the restore credential
val credential = response.credential as RestoreCredential

رابط‌های برنامه‌نویسی مدیریت اعتبارنامه، پاسخی از نوع GetCredentialResponse برمی‌گردانند. اعتبارنامه‌ی موجود در این پاسخ، صراحتاً از نوع RestoreCredential است که کلید عمومی را در خود جای داده است.

مدیریت پاسخ ورود به سیستم

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

کلید بازیابی را حذف کنید

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

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

کلیدهای بازیابی فقط در شرایط زیر حذف می‌شوند:

• اقدامات سطح سیستم : کاربران برنامه را حذف نصب می‌کنند یا داده‌های آن را پاک می‌کنند.
• فراخوانی‌های سطح برنامه : با فراخوانی clearCredentialState() هنگام مدیریت خروج کاربر در کد برنامه، کلید را به صورت برنامه‌نویسی حذف کنید.

وقتی کاربر از برنامه شما خارج می‌شود، متد clearCredentialState() را روی شیء CredentialManager فراخوانی کنید.

// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)