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

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

سازگاری نسخه

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

پیش‌نیازها

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

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

وابستگی‌ها

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

کاتلین

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

شیار

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

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

نکته: ویژگی Restore Credentials صرف نظر از اینکه allowBackup در manifest تنظیم شده باشد یا خیر، کار می‌کند.

نمای کلی

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

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

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

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

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

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

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

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

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

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

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

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
val response = credentialManager.createCredential(context, createRestoreRequest)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• ( توصیه می‌شود ) بلافاصله پس از بازیابی داده‌های برنامه. از BackupAgent برای پیکربندی پشتیبان برنامه خود استفاده کنید و عملکرد getCredential را در فراخوانی onRestore تکمیل کنید تا اطمینان حاصل شود که اعتبارنامه‌های برنامه بلافاصله پس از بازیابی داده‌های برنامه بازیابی می‌شوند. این کار از تأخیرهای احتمالی هنگام باز کردن دستگاه جدید کاربران برای اولین بار جلوگیری می‌کند و به کاربران اجازه می‌دهد بدون انتظار برای باز کردن برنامه شما، تعامل داشته باشند.
• در اولین اجرای برنامه روی دستگاه.

برای ارسال اعلان به کاربر قبل از اینکه برنامه را برای اولین بار در یک دستگاه جدید باز کند، کلید بازیابی را در تابع onRestore از BackupAgent دریافت کنید. این امر به ویژه برای برنامه‌های پیام‌رسان یا ارتباطی اهمیت دارد.

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

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

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

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

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

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

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

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

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

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

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

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

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

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

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)