پیاده‌سازی گذرکلید مناسب را برای برنامه Android خود انتخاب کنید

گذرکلیدها به استانداردی برای اصالت‌سنجی امن و کاربرپسند تبدیل شده‌اند و تعداد فزاینده‌ای از سرویس‌ها درحال پذیرش آن‌ها در وب‌سایت‌ها و برنامه‌های Android هستند. بااین‌حال، وقتی شروع به افزودن گذرکلید به برنامه Android می‌کنید، اغلب با یک سؤال معماری کلیدی مواجه می‌شوید: آیا مستقیماً با میاناهای برنامه‌سازی کاربردی بومی تماس می‌گیرید، صفحه ورود به سیستم وب موجود خود را در برگه مرورگر باز می‌کنید، یا گذرکلیدها را در WebView درون‌برنامه اجرا می‌کنید؟

نمای کلی

می‌توانید از گذرکلیدها در برنامه‌های Android ازطریق سه رویکرد اصلی پشتیبانی کنید: Credential Manager، برگه اصالت‌سنجی، و وب‌نما. اسناد رسمی جزئیات پیاده‌سازی گام‌به‌گام را برای هر گزینه پوشش می‌دهد. انتخاب معماری‌ای که اصطکاک کاربر را به‌حداقل برساند و درعین‌حال هزینه‌های توسعه و نگهداری را قابل‌مدیریت نگه دارد، به درک ویژگی‌ها و محدودیت‌های هر گزینه در سطح بالا بستگی دارد. این راهنما توضیح می‌دهد که چگونه رویکرد مناسب را براساس طراحی برنامه و زیرساخت اصالت‌سنجی موجود انتخاب کنید. جدول زیر این رویکردها را مقایسه می‌کند:

ویژگی مدیر اطلاعات اعتباری برگه اصالت‌سنجی وب‌نما
کاربرد توصیه‌شده برنامه‌هایی که واسط کاربر ورود به سیستم بومی دارند استفاده مجدد از صفحه ورود به سیستم وب موجود، یا ارائه‌دهنده هویت (IdP) از نوع OAuth یا OpenID Connect (OIDC) برنامه‌های «وب‌نمای» ترکیبی موجود (فقط دامنه شخص اول)
میانای کاربر و تجربه کاربری یکپارچه‌سازی تکمیل خودکار صفحه‌کلید و برگ زیرین سیستم‌عامل بومی برگه مرورگر اختصاصی و کوچک برای اصالت‌سنجی صفحه وب جاسازی‌شده با برگ زیرین سیستم‌عامل بومی
تکمیل خودکار و میانای کاربر شرطی پشتیبانی می‌شود (تکمیل خودکار Credential Manager) پشتیبانی‌شده (میانای کاربر شرطی WebAuthn) پشتیبانی نمی‌شود
هم‌رسانی اطلاعات اعتباری و جلسه گذرکلیدها را بااستفاده از assetlinks.json و rpId مشترک در سراسر وب و برنامه هم‌رسانی می‌کند (کوکی‌های Chrome هم‌رسانی نمی‌شود) کوکی‌ها و وضعیت اعتبارنامه را با Chrome هم‌رسانی می‌کند (بااستفاده از مرور زودگذر می‌توان آن را غیرفعال کرد) گذرکلیدها را بااستفاده از assetlinks.json هم‌رسانی می‌کند، اما کوکی‌ها و جلسه‌ها را از Chrome جدا می‌کند
پیوندهای دارایی دیجیتال (assetlinks.json) در دامنه وب طرف متکی الزامی است برای تغییرمسیرهای HTTPS در دامنه URI تغییرمسیر شما الزامی است (نسبت‌به طرح‌های سفارشی که به آن نیاز ندارند توصیه می‌شود) در دامنه وب طرف متکی الزامی است (نمی‌تواند با ارائه‌دهندگان هویت خارجی یا طرف سوم استفاده شود)

مدیر اطلاعات اعتباری

اگر برنامه Android شما صفحه‌های ثبت‌نام یا ورود به سیستم بومی دارد، کتابخانه Jetpack Credential Manager رویکرد اصلی توصیه‌شده است.

مزیت اصلی Credential Manager این است که گذرکلیدها، گذرواژه‌ها، و «ورود به سیستم با Google» را در یک برگه پایین سیستم ساده و یکپارچه می‌کند. وقتی کاربر به سیستم وارد می‌شود، اصالت‌سنجی زیست‌سنجشی را با یک ضربه و بدون ترک کردن برنامه شما تکمیل می‌کند و این امر باعث کاهش اصطکاک ورود به سیستم می‌شود. حتی اگر کاربر برگه پایین اولیه را ببندد و روی فیلد ورودی نام کاربری یا گذرواژه تک‌ضرب بزند، می‌توانید از PendingGetCredentialRequest برای نمایش گذرکلیدها، گذرواژه‌ها، و «ورود به سیستم با Google» مستقیماً در صفحه‌کلید یا پیشنهادهای تکمیل خودکار منو کرکره‌ای استفاده کنید. این جایگزین، ادغام تکمیل خودکار بومی معادل WebAuthn Conditional UI را ارائه می‌دهد.

برگه پایین Credential Manager که گذرکلید، «ورود به سیستم با Google»، و گزینه‌های گذرواژه را نشان می‌دهد.
شکل ۱. ‫Credential Manager گذرکلیدها، «ورود به سیستم با Google»، و گذرواژه‌ها را در یک برگه پایین سیستم یکپارچه می‌کند.

«مدیر اطلاعات کاربری» همچنین برابری کامل ویژگی‌ها را با قابلیت‌های چرخه حیات گذرکلید وب مدرن ارائه می‌دهد. با «مدیر اطلاعات کاربری» می‌توانید کارهای زیر را انجام دهید:

  • از ایجاد خودکار گذرکلید (isConditional = true در CreatePublicKeyCredentialRequest) برای ایجاد بی‌صدا گذرکلید پس‌از ورود موفق به سیستم با گذرواژه استفاده کنید.
  • از Signal API استفاده کنید تا اطلاعات کاربری و نام‌های کاربری‌تان با ارائه‌دهندگان اطلاعات کاربری سازگار بماند.
  • بازگرداندن اعتبارنامه‌ها را پیاده‌سازی کنید تا وقتی کاربران دستگاه جدیدی راه‌اندازی می‌کنند، به‌طور خودکار دوباره به سیستم برنامه شما وارد شوند.

گذرکلیدها در دستگاه‌های دارای Android 9 (سطح میانای برنامه‌سازی کاربردی ۲۸) و بالاتر پشتیبانی می‌شوند، درحالی‌که سایر اطلاعات کاربری، مانند گذرواژه‌ها، همچنان در نسخه‌های پایین‌تر Android ازطریق خدمات Google Play پشتیبانی می‌شوند. در Android 14 (سطح API‏ ۳۴) و بالاتر، Credential Manager با هر ارائه‌دهنده اطلاعات کاربری طرف سومی که کاربر انتخاب کرده باشد نیز کار می‌کند. قابلیت‌های اضافی، مانند ادغام تکمیل خودکار مبتنی بر View (PendingGetCredentialRequest) و Signal API، به Android 15 (سطح API‏ ۳۵) و بالاتر نیاز دارند.

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

برای شروع، پیش‌نیازهای میزبانی فایل «پیوندهای دارایی دیجیتال» (assetlinks.json) را در دامنه وب خود دنبال کنید تا وب‌سایت و برنامه Android خود را مرتبط کنید. مرتبط کردن وب‌سایت و برنامه ازطریق assetlinks.json به این معنی است که آن‌ها شناسه طرف معتمد (rpId) یکسانی دارند، بنابراین گذرکلیدهای ایجادشده در وب‌سایت شما در Chrome در برنامه Android بومی شما ازطریق Credential Manager کار می‌کنند و گذرکلیدهای ایجادشده در برنامه شما در وب‌سایت شما کار می‌کنند. ‫Credential Manager اطلاعات اعتباری را در وب‌سایت و برنامه شما هم‌رسانی می‌کند؛ فقط زمانی به Auth Tab نیاز دارید که بخواهید از میانای کاربر ورود به سیستم وب یا صفحه IdP خودتان مجدداً استفاده کنید.

همان‌طور که در ایجاد گذرکلید شرح داده شده است، باید سرورتان را نیز پیکربندی کنید تا مبدأ برنامه Android را درستی‌سنجی کند (android:apk-key-hash:ENCODED_SHA256_HASH، قالب‌بندی‌شده بااستفاده از درهم‌سازی SHA-256 کدگذاری‌شده با Base64URL بدون فاصله گواهینامه امضای APK شما). اگر برنامه‌تان میانای کاربر بومی دارد و می‌خواهید تجربه ادغام‌شده با سیستم‌عامل برای ورود به سیستم با گذرکلید داشته باشید، Credential Manager را انتخاب کنید.

برگه اصالت‌سنجی

بسیاری از سرویس‌ها ریزسرویس ارائه‌دهنده هویت (IdP) را که بر OAuth یا OpenID Connect (OIDC) ساخته شده است اجرا می‌کنند، یا می‌خواهند از صفحه ورود به سیستم وب موجود با قابلیت گذرکلید در برنامه‌های تلفن همراه استفاده مجدد کنند. در گذشته، برنامه‌ها از برگه‌های سفارشی برای این جریان‌ها استفاده می‌کردند. از Chrome 137 و AndroidX Browser 1.9.0، برگه اصالت‌سنجی یک زبانه مرورگر اختصاصی ارائه می‌دهد که به‌طور خاص برای جریان‌های اصالت‌سنجی طراحی شده است.

«برگه اصالت‌سنجی» که واسط ورود به سیستم مرورگر را به‌صورت حداقلی و بدون موارد منو مرورگر چندمنظوره نمایش می‌دهد.
شکل ۲. «برگه اصالت‌سنجی» یک میانای مرورگر متمرکز ارائه می‌دهد که برای جریان‌های اصالت‌سنجی سفارشی شده است.

«زبانه سفارشی» استاندارد به‌عنوان مرورگر درون‌برنامه با هدف عمومی طراحی شده است، عناصر میانای کاربر غیرمرتبط با ورود به سیستم را نمایش می‌دهد—مثل منو هم‌رسانی، نشانک‌ها، و باز کردن در Chrome—که می‌تواند حواس کاربران را پرت کند. همچنین لازم است فیلترهای قصد را در فایل مانیفست خود اعلام کنید تا تغییرمسیرهای پس‌از اصالت‌سنجی را دریافت کنید، کد متن استاندارد اضافه کنید، و به تدابیر امنیتی دربرابر رهگیری قصد توسط برنامه‌های مخرب نیاز دارید.

«برگه اصالت‌سنجی» این چالش‌های خاص اصالت‌سنجی را حل می‌کند. این ویژگی واسط کاربر غیرضروری مرورگر، مثل دکمه کوچک کردن و منو هم‌رسانی، را برمی‌دارد و میانای متمرکزی را ارائه می‌دهد که فقط قابلیت‌های ضروری ورود به سیستم، ازجمله تکمیل خودکار گذرکلید و گذرواژه، را دارد. «برگه اصالت‌سنجی» به‌جای مسیریابی ازطریق هدف‌های سیستم‌عامل، تغییرمسیرهای اصالت‌سنجی را مستقیماً بااستفاده از طرح سفارشی یا نشانی وب HTTPS تأییدشده با «پیوندهای دارایی دیجیتال» به فراخوانی درون‌برنامه ارائه می‌دهد که این امر امنیت را تقویت می‌کند و کدهای تکراری پیاده‌سازی را کاهش می‌دهد.

هم‌رسانی جلسه و بازگشت به «برگه‌های سفارشی»

به‌طور پیش‌فرض، «برگه اصالت‌سنجی» کوکی‌ها و وضعیت اعتبارنامه را نیز مستقیماً با مرورگر Chrome سیستم هم‌رسانی می‌کند. این هم‌رسانی به برنامه شما اجازه می‌دهد از جلسه‌های فعال واردشده به سیستم در Chrome استفاده کند و پیاده‌سازی WebAuthn موجود شما را همان‌طور که هست اجرا کند—ازجمله میانای کاربر شرطی و حالت میانای کاربر فوری (معادل وب preferImmediatelyAvailableCredentials در Credential Manager). برعکس، اگر مورد استفاده شما به یک جلسه اصالت‌سنجی مجزا نیاز دارد که کوکی‌ها یا سابقه مرور را با مرورگر هم‌رسانی نکند، می‌توانید با فراخوانی AuthTabIntent.Builder.setEphemeralBrowsingEnabled(true)، مرور موقت را فعال کنید.

وقتی androidx.browser:browser (نسخه ۱.۹.۰ یا بالاتر) را با برنامه‌تان بسته‌بندی می‌کنید، اینکه «برگه اصالت‌سنجی» در زمان اجرا اجرا شود یا نه به مرورگر پیش‌فرض کاربر بستگی دارد. اگر مرورگر پیش‌فرض نسخه‌ای از Chrome پایین‌تر از ۱۳۷ یا مرورگر طرف سومی باشد که از «زبانه اصالت‌سنجی» پشتیبانی نمی‌کند، «زبانه اصالت‌سنجی» به‌طور خودکار به راه‌اندازی «زبانه سفارشی» استاندارد برمی‌گردد. When this fallback occurs, the post-authentication redirect returns through an intent filter in AndroidManifest.xml as in standard Custom Tabs, rather than through Auth Tab's callback (ActivityResultCallback). In production, Google recommends either checking default browser support beforehand using CustomTabsClient.isAuthTabSupported(context, provider) to branch your flow or retaining the manifest intent filter so your app can handle results from either path. برای نمونه‌های پیاده‌سازی جایگزین واقعی، راهنمای مرورگر Android را ببینید.

الزامات امنیتی OAuth و OIDC

«برگه اصالت‌سنجی» فقط کانال بازهدایت سمت کارخواه را از مرورگر به برنامه شما ایمن و ساده می‌کند؛ این برگه به‌طور خودکار پروتکل OAuth یا OIDC را ایمن نمی‌کند. به‌ویژه با توجه به رفتار بازگشت «برگه‌های سفارشی»، باید OAuth 2.0 برای برنامه‌های بومی (RFC 8252) را دنبال کنید. به‌طور خاص، PKCE (کلید اثبات برای تبادل کد، RFC 7636) را بااستفاده از پارامترهای code_challenge و code_verifier ترکیب کنید تا از رهگیری کد مجوز جلوگیری شود، اعتبارسنجی پارامتر state برای جلوگیری از جعل درخواست بین‌سایتی (CSRF) و حملات تثبیت جلسه، و تولید و اعتبارسنجی پارامتر nonce در OpenID Connect برای جلوگیری از حملات بازپخش کد شناسه. با وجود این محافظت‌ها، Google توصیه می‌کند معماری‌های ورود به سیستم مبتنی بر وب از «برگه‌های سفارشی» استاندارد به «برگه اصالت‌سنجی» منتقل شوند.

وب‌نما

برخی‌از برنامه‌ها براساس معماری WebView ترکیبی ساخته شده‌اند که در آن‌ها جدا کردن فقط صفحه ورود به سیستم در میانای کاربر بومی (Credential Manager) یا زبانه مرورگر (زبانه Auth) عملی نیست. در این موارد، می‌توانید پشتیبانی WebAuthn را مستقیماً در WebView فعال کنید.

برای استفاده از گذرکلیدها در WebView، هم کتابخانه AndroidX WebKit (androidx.webkit:webkit نسخه ۱.۱۲.۰ یا بالاتر) و هم وابستگی‌های Credential Manager (androidx.credentials:credentials و androidx.credentials:credentials-play-services-auth) را به فایل build.gradle خود اضافه کنید. سپس، بااستفاده از WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION) بررسی کنید که از این ویژگی پشتیبانی می‌شود یا نه و با فراخوانی WebSettingsCompat.setWebAuthenticationSupport(webView.settings, WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP)، پشتیبانی از WebAuthn را صریحاً فعال کنید. این پیکربندی به‌طور خودکار درخواست‌های اصالت‌سنجی و ایجاد گذرکلید را از صفحه‌های وب در «وب‌نما» به Credential Manager پل می‌کند.

محدودیت‌های دامنه و تجربه کاربری

همانند ادغام‌های Credential Manager بومی، باید پیش‌نیازها را دنبال کنید تا فایل «پیوندهای دارایی دیجیتال» (assetlinks.json) را در دامنه وب طرف متکی خود میزبانی کنید تا برنامه‌تان را مرتبط کنید. سرور شما android:apk-key-hash:ENCODED_SHA256_HASH (درهم‌سازی گواهی SHA-256 کدبندی‌شده با Base64URL) را به‌عنوان مبدأ دریافت می‌کند. چون این رویکرد مستلزم میزبانی assetlinks.json در دامنه طرف متکی برای اعتماد به گواهی امضای برنامه Android شما است، فقط زمانی کار می‌کند که دامنه وب طرف متکی را کنترل کنید (ورود به سیستم وب طرف اول). اگر جریان اصالت‌سنجی شما به IdP خارجی یا طرف سومی هدایت می‌شود که نمی‌توانید assetlinks.json را برای بسته برنامه‌تان میزبانی کنید، باید به‌جای WebView از «برگه اصالت‌سنجی» (یا «ورود به سیستم با Google» بومی ازطریق Credential Manager) استفاده کنید.

به دو محدودیت UX و عملکردی توجه داشته باشید: WebView از میانای کاربر شرطی (ادغام تکمیل خودکار mediation: "conditional" وقتی کاربر روی فیلد ورودی تمرکز می‌کند) پشتیبانی نمی‌کند و کوکی‌ها یا جلسه‌های ورود به سیستم را با مرورگر Chrome سیستم هم‌رسانی نمی‌کند. به‌دلیل این محدودیت‌ها، Google توصیه می‌کند هنگام طراحی جریان‌های اصالت‌سنجی جدید از «مدیر اطلاعات کاربری» یا «برگه اصالت‌سنجی» استفاده کنید. بااین‌حال، اگر می‌خواهید پشتیبانی از گذرکلید را بدون تغییرات عمده در معماری به برنامه ترکیبی شخص اول موجود اضافه کنید، می‌توانید گذرکلیدها را با WebView ادغام کنید.

خلاصه

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

  • اگر برنامه‌تان میانای کاربر ورود به سیستم بومی دارد و می‌خواهید تجربه ادغام‌شده با سیستم‌عامل داشته باشید بدون اینکه به صفحه مرورگر بروید، Credential Manager را برای ورود به سیستم با گذرکلید انتخاب کنید.
  • اگر ریزسرویس OAuth یا OIDC IdP را اجرا می‌کنید، به IdP خارجی هدایت کنید، یا می‌خواهید از صفحه ورود به سیستم وب فعال‌شده با گذرکلید موجود خود (ازجمله میانای کاربر شرطی) مجدداً استفاده کنید و جلسه‌های فعال مرورگر را با Chrome هم‌رسانی کنید، برگه Auth را اتخاذ کنید و الزامات امنیتی را در OAuth 2.0 برای برنامه‌های بومی (RFC 8252)—به‌ویژه PKCE،‏ state، و nonce پیاده‌سازی کنید.
  • اگر برنامه‌تان براساس معماری «وب‌نمای» ترکیبی ساخته شده است که در آن ورود به سیستم باید در صفحه‌های وب جاسازی‌شده طرف اول باقی بماند، از وب‌نما استفاده کنید و عدم پشتیبانی از «میانای کاربر شرطی» و کوکی‌های مجزا را درنظر بگیرید.

مراحل بعدی