این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

احراز هویت در پوشیدنی ها: مدیر اعتبار

برنامه‌های Wear OS می‌توانند به صورت مستقل و بدون نیاز به برنامه‌ی همراه اجرا شوند. این بدان معناست که یک برنامه‌ی Wear OS هنگام دسترسی به داده‌ها از اینترنت، باید احراز هویت را به تنهایی مدیریت کند. اما اندازه‌ی کوچک صفحه نمایش ساعت و قابلیت‌های ورودی محدود، گزینه‌های احراز هویتی را که یک برنامه‌ی Wear OS می‌تواند استفاده کند، محدود می‌کند.

این راهنما، دستورالعمل‌هایی برای روش تأیید اعتبار پیشنهادی برای برنامه‌های Wear OS، یعنی Credential Manager، ارائه می‌دهد.

برای کسب اطلاعات بیشتر در مورد چگونگی طراحی یک تجربه ورود خوب، به راهنمای UX ورود مراجعه کنید.

ملاحظات اولیه

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

حالت مهمان

برای همه عملکردها نیازی به احراز هویت نداشته باشید. در عوض، تا حد امکان ویژگی‌های بیشتری را بدون نیاز به ورود به سیستم در اختیار کاربر قرار دهید.

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

ممکن است برخی از دستگاه‌ها مدت بیشتری آنلاک بمانند

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

اگر برنامه شما به سطح بالاتری از امنیت نیاز دارد - مانند نمایش داده‌های حساس یا خصوصی - ابتدا بررسی کنید که آیا تشخیص مچ دست فعال است یا خیر:

val wristDetectionEnabled =
        isWristDetectionAutoLockingEnabled(applicationContext)

اگر مقدار بازگشتی این متد false باشد، قبل از نمایش محتوای خاص کاربر، از او بخواهید که در برنامه شما وارد حساب کاربری شود.

مدیر اعتبارنامه

مدیریت اعتبارنامه (Credential Manager) رابط برنامه‌نویسی کاربردی (API) پیشنهادی برای احراز هویت در Wear OS است. این رابط، محیطی امن‌تر را برای کاربران فراهم می‌کند تا بتوانند بدون نیاز به اتصال به تلفن همراه و به خاطر سپردن رمز عبور، به صورت مستقل وارد برنامه‌های Wear OS شوند.

این سند، اطلاعاتی را که توسعه‌دهندگان برای پیاده‌سازی راهکار مدیریت اعتبارنامه (Credential Manager) با سازوکارهای احراز هویت استاندارد میزبان آن نیاز دارند، تشریح می‌کند:

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

این راهنما همچنین دستورالعمل‌هایی برای نحوه انتقال سایر روش‌های تأیید هویت قابل قبول Wear OS ( Data Layer Token Sharing و OAuth ) به عنوان پشتیبان برای Credential Manager و دستورالعمل‌های ویژه‌ای برای مدیریت انتقال از دکمه ورود مستقل Google که اکنون منسوخ شده است به نسخه Credential Manager تعبیه شده ارائه می‌دهد.

محدودیت‌ها و تفاوت‌های Wear OS

توسعه‌دهندگان باید محدودیت‌ها و تفاوت‌های زیر را در مورد Wear OS در نظر داشته باشند:

مدیریت اعتبارنامه فقط در Wear OS 4 و بالاتر در دسترس است.
ایجاد اعتبارنامه در Wear OS امکان‌پذیر نیست
نه «بازیابی اعتبارنامه‌ها» و نه جریان‌های ورود ترکیبی پشتیبانی نمی‌شوند.
فقط ارائه‌دهندگان اعتبارنامه که با Wear OS یکپارچه شده‌اند، می‌توانند از طریق موبایل دوباره استفاده شوند.

کلیدهای عبور در Wear OS

به توسعه‌دهندگان اکیداً توصیه می‌شود که در پیاده‌سازی‌های Wear OS Credential Manager خود، از کلیدهای عبور استفاده کنند. کلیدهای عبور، استاندارد جدید صنعتی برای احراز هویت کاربر نهایی هستند و مزایای قابل توجهی برای کاربران دارند.

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

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

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

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

پیاده‌سازی کلیدهای عبور

شامل تنظیمات و راهنمایی برای انواع پیاده‌سازی.

راه‌اندازی

سطح API هدف را در فایل build.gradle ماژول برنامه خود روی ۳۵ تنظیم کنید:
```
android {
    defaultConfig {
        targetSdkVersion(35)
    }
}
```
خطوط زیر را با استفاده از آخرین نسخه پایدار از مرجع androidx.credentials releases ، به فایل build.gradle برنامه یا ماژول خود اضافه کنید.
```
androidx.credentials:credentials:1.5.0
androidx.credentials:credentials-play-services-auth:1.5.0
```

روش‌های احراز هویت داخلی

از آنجایی که Credential Manager یک API یکپارچه است، مراحل پیاده‌سازی آن برای Wear OS مشابه هر نوع دستگاه دیگری است.

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

مراحل افزودن پشتیبانی از ورود با گوگل به Credential Manager مختص توسعه موبایل است، اما مراحل در Wear OS نیز یکسان است. برای ملاحظات ویژه در این مورد، به بخش «گذار از ورود با گوگل قدیمی» مراجعه کنید.

توجه داشته باشید که از آنجایی که نمی‌توان اعتبارنامه‌ها را در Wear OS ایجاد کرد، نیازی به پیاده‌سازی روش‌های ایجاد اعتبارنامه ذکر شده در دستورالعمل‌های موبایل ندارید.

روش‌های احراز هویت پشتیبان

دو روش احراز هویت قابل قبول دیگر برای برنامه‌های Wear OS وجود دارد: OAuth 2.0 (هر دو نوع) و Mobile Auth Token Data Layer Sharing. اگرچه این روش‌ها نقاط ادغام در API مدیریت اعتبارنامه ندارند، اما می‌توانند در جریان UX مدیریت اعتبارنامه شما به عنوان روش‌های جایگزین در صورتی که کاربران صفحه مدیریت اعتبارنامه را رد کنند، گنجانده شوند.

برای مدیریت اقدام کاربر در رد کردن صفحه مدیریت اعتبارنامه، یک NoCredentialException به عنوان بخشی از منطق GetCredential خود دریافت کنید و به رابط کاربری احراز هویت سفارشی خود بروید.

yourCoroutineScope.launch {
    try {
      val response = credentialManager.getCredential(activity, request)
      signInWithCredential(response.credential)
    } catch (e: GetCredentialCancellationException) {
      navigateToFallbackAuthMethods()
    }
}

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

اشتراک‌گذاری توکن لایه داده

برنامه همراه تلفن می‌تواند با استفاده از API لایه داده پوشیدنی، داده‌های احراز هویت را به صورت ایمن به برنامه Wear OS منتقل کند. اعتبارنامه‌ها را به صورت پیام یا به عنوان اقلام داده منتقل کنید.

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

مهم: برنامه Wear OS شما باید حداقل یک روش احراز هویت دیگر ارائه دهد، زیرا این گزینه فقط در ساعت‌های جفت‌شده با اندروید و در صورت نصب برنامه تلفن همراه مربوطه کار می‌کند. برای کاربرانی که برنامه تلفن همراه مربوطه را ندارند یا دستگاه Wear OS آنها با دستگاه iOS جفت شده است، یک روش احراز هویت جایگزین ارائه دهید.

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

val token = "..." // Auth token to transmit to the Wear OS device.
val dataClient: DataClient = Wearable.getDataClient(context)
val putDataReq: PutDataRequest = PutDataMapRequest.create("/auth").run {
    dataMap.putString("token", token)
    asPutDataRequest()
}
val putDataTask: Task<DataItem> = dataClient.putDataItem(putDataReq)

همانطور که در مثال زیر نشان داده شده است، به رویدادهای تغییر داده در برنامه Wear OS گوش دهید:

val dataClient: DataClient = Wearable.getDataClient(context)
dataClient.addListener{ dataEvents ->
    dataEvents.forEach { event ->
        if (event.type == DataEvent.TYPE_CHANGED) {
            val dataItemPath = event.dataItem.uri.path ?: ""
            if (dataItemPath.startsWith("/auth")) {
                val token = DataMapItem.fromDataItem(event.dataItem).dataMap.getString("token")
                // Display an interstitial screen to notify the user that
                // they're being signed in.
                // Then, store the token and use it in network requests.
            }
        }
    }
}

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

از OAuth 2.0 استفاده کنید

Wear OS از دو جریان مبتنی بر OAuth 2.0 پشتیبانی می‌کند که در بخش‌های بعدی توضیح داده شده‌اند:

اعطای کد مجوز با کلید اثبات برای تبادل کد (PKCE)، همانطور که در RFC 7636 تعریف شده است
مجوز دستگاه (DAG)، همانطور که در RFC 8628 تعریف شده است

کلید اثبات برای تبادل کد (PKCE)

برای استفاده‌ی مؤثر از PKCE، از RemoteAuthClient استفاده کنید. سپس، برای ارسال درخواست احراز هویت از برنامه‌ی Wear OS خود به یک ارائه‌دهنده‌ی OAuth، یک شیء OAuthRequest ایجاد کنید. این شیء شامل یک URL به نقطه‌ی پایانی OAuth شما برای دریافت توکن و یک شیء CodeChallenge است.

کد زیر نمونه‌ای از ایجاد یک درخواست احراز هویت را نشان می‌دهد:

val request = OAuthRequest.Builder(this.applicationContext)
    .setAuthProviderUrl(Uri.parse("https://...."))
    .setClientId(clientId)
    .setCodeChallenge(codeChallenge)
    .build()

پس از ساخت درخواست احراز هویت، آن را با استفاده از متد sendAuthorizationRequest() به برنامه همراه ارسال کنید:

val client = RemoteAuthClient.create(this)
client.sendAuthorizationRequest(request,
    { command -> command?.run() },
    object : RemoteAuthClient.Callback() {
        override fun onAuthorizationResponse(
            request: OAuthRequest,
            response: OAuthResponse
        ) {
            // Extract the token from the response, store it, and use it in
            // network requests.
        }

        override fun onAuthorizationError(errorCode: Int) {
            // Handle any errors.
        }
    }
)

این درخواست باعث فراخوانی برنامه همراه می‌شود که سپس یک رابط کاربری مجوز را در یک مرورگر وب روی تلفن همراه کاربر نمایش می‌دهد. ارائه دهنده OAuth 2.0 کاربر را احراز هویت می‌کند و رضایت کاربر را برای مجوزهای درخواستی دریافت می‌کند. پاسخ به URL هدایت شده که به طور خودکار ایجاد شده است، ارسال می‌شود.

پس از احراز هویت موفق یا ناموفق، سرور OAuth 2.0 به URL مشخص شده در درخواست هدایت می‌شود. اگر کاربر درخواست دسترسی را تأیید کند، پاسخ حاوی یک کد تأیید است. اگر کاربر درخواست را تأیید نکند، پاسخ حاوی یک پیام خطا است.

پاسخ به صورت یک رشته پرس و جو (query string) است و شبیه یکی از مثال‌های زیر به نظر می‌رسد:

  https://wear.googleapis.com/3p_auth/com.your.package.name?code=xyz
  https://wear.googleapis-cn.com/3p_auth/com.your.package.name?code=xyz

این صفحه‌ای را بارگذاری می‌کند که کاربر را به برنامه‌ی همراه هدایت می‌کند. برنامه‌ی همراه، URL پاسخ را تأیید می‌کند و با استفاده از API onAuthorizationResponse ، پاسخ را به برنامه‌ی Wear OS شما ارسال می‌کند.

سپس برنامه ساعت می‌تواند کد مجوز را با یک توکن دسترسی تعویض کند.

مجوز دستگاه

هنگام استفاده از مجوز دستگاه، کاربر URI تأیید را در دستگاه دیگری باز می‌کند. سپس سرور تأیید از او می‌خواهد که درخواست را تأیید یا رد کند.

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

// Request access from the authorization server and receive Device Authorization
// Response.
val verificationUri = "..." // Extracted from the Device Authorization Response.
RemoteActivityHelper.startRemoteActivity(
    this,
    Intent(Intent.ACTION_VIEW)
        .addCategory(Intent.CATEGORY_BROWSABLE)
        .setData(Uri.parse(verificationUri)),
    null
)
// Poll the authorization server to find out if the user completed the user
// authorization step on their mobile device.

اگر یک برنامه iOS دارید، به جای تکیه بر مرورگر برای تأیید توکن، از لینک‌های جهانی برای رهگیری این هدف در برنامه خود استفاده کنید.

انتقال از نسخه قدیمی ورود با گوگل

Credential Manager یک نقطه ادغام اختصاصی برای دکمه ورود با گوگل دارد. پیش از این، این دکمه می‌توانست در هر جایی از تجربه کاربری احراز هویت برنامه اضافه شود، اما با گنجاندن آن در Credential Manager، گزینه قدیمی اکنون منسوخ شده است.

توجه: نسخه Credential Manager از برنامه Sign in With Google موقتاً در دستگاه‌های Wear OS که Wear OS 3 (سطح API 30) را اجرا می‌کنند، در دسترس نیست. اگر برنامه‌ای Credential Manager را در دستگاهی که از آن پشتیبانی نمی‌کند، فراخوانی کند، جریان GetCredential یک NoCredentialException ایجاد می‌کند که معمولاً نشان می‌دهد هیچ اعتبارنامه‌ای برای برنامه فراخوانی در دستگاه کاربر موجود نیست.

برای رفع این مشکل، توصیه می‌کنیم نسخه قدیمی دکمه را به عنوان بخشی از جریان UX احراز هویت جایگزین خود اضافه کنید و منطق بولی را برای غیرفعال کردن آن دکمه در صورت اجرا روی دستگاهی که Wear OS 4 (سطح API 33) یا بالاتر دارد، اضافه کنید. این به کاربران اجازه می‌دهد صرف نظر از قابلیت‌های دستگاه خود، به دکمه ورود با گوگل آشنای خود دسترسی داشته باشند، در حالی که یک گزینه احراز هویت معتبر واحد نیز نشان داده می‌شود.

// Define a basic SDK check.
fun isCredentialManagerAvailable(): Boolean {
 return android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.VANILLA_ICE_CREAM
}

// Elsewhere in the code, use it to selectively disable the legacy option.
Button(
  onClick = {
    if (isCredentialManagerAvailable()) {
      Log.w(TAG, "Devices on API level 35 or higher should use
                  Credential Manager for Sign in with Google")
    } else {
      navigateToSignInWithGoogle()
    }},
  enabled = !isCredentialManagerAvailable(),
  label = { Text(text = stringResource(R.string.sign_in_with_google)) },
  secondaryLabel = { Text(text = "Disabled on API level 35+")
  }
)