Autentikasi di perangkat wearable: Pengelola Kredensial

Aplikasi Wear OS dapat berjalan secara mandiri, tanpa aplikasi pendamping. Ini berarti aplikasi Wear OS perlu mengelola autentikasi sendiri saat mengakses data dari internet. Ukuran layar smartwatch yang kecil dan kemampuan input yang berkurang membatasi opsi autentikasi yang dapat digunakan aplikasi Wear OS.

Panduan ini memberikan petunjuk untuk metode autentikasi yang direkomendasikan untuk aplikasi Wear OS, yaitu Pengelola Kredensial.

Untuk mempelajari lebih lanjut cara mendesain pengalaman login yang baik, lihat Panduan UX login.

Pertimbangan awal

Sebelum memulai penerapan, pertimbangkan poin-poin berikut.

Mode tamu

Tidak mewajibkan autentikasi untuk semua fungsi. Sebagai gantinya, sediakan fitur sebanyak mungkin kepada pengguna tanpa mengharuskannya login.

Pengguna mungkin menemukan dan menginstal aplikasi Wear tanpa menggunakan aplikasi seluler, sehingga mereka mungkin tidak memiliki akun dan mungkin tidak mengetahui fitur yang ditawarkannya. Pastikan fungsi mode tamu menampilkan fitur aplikasi Anda secara akurat.

Beberapa perangkat mungkin tetap tidak terkunci lebih lama

Di perangkat yang didukung yang menjalankan Wear OS 5 atau yang lebih baru, sistem mendeteksi apakah pengguna memakai perangkat di pergelangan tangannya. Jika pengguna menonaktifkan deteksi pergelangan tangan, lalu melepaskan perangkat dari pergelangan tangannya, sistem akan membuat perangkat tetap tidak terkunci untuk jangka waktu yang lebih lama daripada biasanya.

Jika aplikasi Anda memerlukan tingkat keamanan yang lebih tinggi—seperti saat menampilkan data yang berpotensi sensitif atau pribadi—periksa terlebih dahulu apakah deteksi pergelangan tangan diaktifkan:

val wristDetectionEnabled =
        isWristDetectionAutoLockingEnabled(applicationContext)

Jika nilai hasil dari metode ini adalah false, minta pengguna untuk login ke akun di aplikasi Anda sebelum menampilkan konten khusus pengguna.

Credential Manager

Credential Manager adalah API yang direkomendasikan untuk autentikasi di Wear OS. Fitur ini memberikan lingkungan yang lebih aman bagi pengguna untuk login ke aplikasi Wear OS dalam setelan mandiri, tanpa memerlukan ponsel yang terhubung dan dipasangkan, serta tanpa perlu mengingat sandi mereka.

Dokumen ini menguraikan informasi yang dibutuhkan developer untuk menerapkan solusi Pengelola Kredensial dengan mekanisme autentikasi standar yang dihostingnya, yaitu:

• Kunci sandi
• Sandi
• Identitas Gabungan (seperti Login dengan Google)

Panduan ini juga memberikan petunjuk tentang cara memigrasikan metode autentikasi Wear OS lain yang dapat diterima (Berbagi Token Lapisan Data dan OAuth) sebagai cadangan untuk Credential Manager, dan petunjuk khusus untuk menangani transisi dari Tombol Login dengan Google mandiri yang kini tidak digunakan lagi ke versi Credential Manager yang disematkan.

Kunci sandi di Wear OS

Developer sangat dianjurkan untuk menerapkan kunci sandi dalam penerapan Credential Manager Wear OS mereka. Kunci sandi adalah standar industri baru untuk autentikasi pengguna akhir, dan kunci sandi memiliki beberapa manfaat signifikan bagi pengguna.

Kunci sandi lebih mudah

• Pengguna dapat memilih akun yang akan digunakan untuk login. Pengguna tidak perlu mengetik nama pengguna.
• Pengguna dapat melakukan autentikasi menggunakan kunci layar perangkat.
• Setelah kunci sandi dibuat dan didaftarkan, pengguna dapat beralih ke perangkat baru dengan lancar dan langsung menggunakannya tanpa perlu mendaftar ulang.

Kunci sandi lebih aman

• Developer hanya menyimpan kunci publik ke server, bukan menyimpan sandi, yang berarti aktor jahat akan jauh lebih sulit meretas server, dan jauh lebih sedikit pembersihan yang harus dilakukan jika terjadi pelanggaran.
• Kunci sandi memberikan perlindungan yang tahan terhadap phishing. Kunci sandi hanya berfungsi di situs dan aplikasi yang telah didaftarkan pengguna; pengguna tidak dapat ditipu untuk melakukan autentikasi di situs penipu karena browser atau OS menangani verifikasi.
• Kunci sandi mengurangi kebutuhan untuk mengirim SMS, sehingga membuat autentikasi lebih hemat biaya.

Mengimplementasikan kunci sandi

Mencakup penyiapan dan panduan untuk semua jenis penerapan.

Penyiapan

1. Tetapkan level API target ke 35 di file build.gradle modul aplikasi Anda:

   android {
       defaultConfig {
           targetSdkVersion(35)
       }
   }
   

2. Tambahkan baris berikut ke file build.gradle untuk aplikasi atau modul Anda, menggunakan versi stabil terbaru dari referensi rilis androidx.credentials.

   androidx.credentials:credentials:1.5.0
   androidx.credentials:credentials-play-services-auth:1.5.0
   

Metode autentikasi bawaan

Karena Credential Manager adalah API terpadu, langkah-langkah implementasi untuk Wear OS sama dengan jenis perangkat lainnya.

Gunakan petunjuk arah seluler untuk memulai dan menerapkan dukungan kunci sandi dan sandi.

Langkah-langkah untuk menambahkan dukungan Login dengan Google ke Credential Manager ditujukan untuk pengembangan seluler, tetapi langkah-langkahnya sama di Wear OS. Lihat bagian, Beralih dari Login dengan Google Lama untuk pertimbangan khusus untuk kasus ini.

Perhatikan bahwa karena kredensial tidak dapat dibuat di Wear OS, Anda tidak perlu menerapkan metode pembuatan kredensial yang disebutkan dalam petunjuk seluler.

Metode autentikasi cadangan

Ada dua metode autentikasi lain yang dapat diterima untuk aplikasi Wear OS: OAuth 2.0 (salah satu varian), dan Berbagi Lapisan Data Token Autentikasi Seluler. Meskipun metode ini tidak memiliki titik integrasi di Credential Manager API, metode ini dapat disertakan dalam alur UX Credential Manager sebagai penggantian jika pengguna menutup layar Credential Manager.

Untuk menangani tindakan pengguna yang menutup layar Pengelola Kredensial, tangkap NoCredentialException sebagai bagian dari logika GetCredential Anda, lalu buka UI autentikasi kustom Anda sendiri.

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

UI autentikasi kustom Anda kemudian dapat menyediakan metode autentikasi lain yang dapat diterima yang dijelaskan dalam panduan UX login.

Berbagi token lapisan data

Aplikasi pendamping ponsel dapat mentransfer data autentikasi ke aplikasi Wear OS dengan aman menggunakan Wearable Data Layer API. Transfer kredensial sebagai pesan atau sebagai item data.

Jenis autentikasi ini biasanya tidak meminta pengguna untuk melakukan tindakan apa pun. Namun, hindari melakukan autentikasi tanpa memberi tahu pengguna bahwa mereka sedang login. Anda dapat memberi tahu pengguna menggunakan layar yang dapat ditutup, yang menunjukkan bahwa akun mereka sedang ditransfer dari perangkat seluler.

Penting: Aplikasi Wear OS Anda harus menawarkan minimal satu metode autentikasi lain, karena opsi ini hanya berfungsi pada smartwatch yang tersambung ke Android saat aplikasi seluler yang terkait diinstal. Berikan metode autentikasi alternatif bagi pengguna yang tidak memiliki aplikasi seluler yang sesuai atau yang perangkat Wear OS-nya disambungkan dengan perangkat iOS.

Teruskan token menggunakan lapisan data dari aplikasi seluler, seperti yang ditunjukkan dalam contoh berikut:

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)

Proses peristiwa perubahan data di aplikasi Wear OS, seperti yang ditunjukkan dalam contoh berikut:

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.
            }
        }
    }
}

Untuk informasi lengkap tentang penggunaan Lapisan Data Wearable, lihat Mengirim dan menyinkronkan data di Wear OS.

Menggunakan OAuth 2.0

Wear OS mendukung dua alur berbasis OAuth 2.0, yang dijelaskan di bagian berikut:

• Pemberian Kode Otorisasi dengan Kunci Bukti untuk Pertukaran Kode (PKCE), seperti yang dijelaskan dalam RFC 7636
• Pemberian Otorisasi Perangkat (DAG), seperti yang dijelaskan dalam RFC 8628

Catatan: Untuk meminimalkan kemungkinan aplikasi Anda ditutup saat perangkat Wear OS beralih ke mode standby, aktifkan mode Selalu Aktif menggunakan AmbientModeSupport.attach dalam aktivitas yang melakukan autentikasi. Untuk mengetahui informasi selengkapnya tentang praktik terbaik dalam Mode Standby, lihat Menjaga aplikasi Anda tetap terlihat di Wear.

Kunci Bukti untuk Pertukaran Kode (PKCE)

Untuk menggunakan PKCE secara efektif, gunakan RemoteAuthClient. Kemudian, untuk membuat permintaan autentikasi dari aplikasi Wear OS ke penyedia OAuth, buat objek OAuthRequest. Objek ini terdiri dari URL ke endpoint OAuth Anda untuk mendapatkan token dan objek CodeChallenge.

Kode berikut menunjukkan contoh pembuatan permintaan autentikasi:

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

Setelah Anda membuat permintaan autentikasi, kirimkan ke aplikasi pendamping menggunakan metode 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.
        }
    }
)

Permintaan ini memicu panggilan ke aplikasi pendamping yang kemudian akan menampilkan UI otorisasi di browser web pada ponsel pengguna. Penyedia OAuth 2.0 mengautentikasi pengguna dan memperoleh izin pengguna untuk izin yang diminta. Respons akan dikirim ke URL pengalihan yang dibuat secara otomatis.

Setelah otorisasi berhasil atau gagal, server OAuth 2.0 akan mengalihkan ke URL yang ditentukan dalam permintaan. Jika pengguna menyetujui permintaan akses, respons akan berisi kode otorisasi. Jika pengguna tidak menyetujui permintaan, respons akan berisi pesan error.

Respons berupa string kueri, dan akan terlihat seperti salah satu contoh berikut:

  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

Tindakan ini akan memuat halaman yang mengarahkan pengguna ke aplikasi pendamping. Aplikasi pendamping memverifikasi URL respons dan meneruskan respons ke aplikasi Wear OS Anda menggunakan onAuthorizationResponse API.

Kemudian aplikasi smartwatch dapat menukar kode otorisasi dengan token akses.

Catatan: Setelah OAuthRequest dibuat, Anda dapat menemukan URL pengalihan dengan mengakses redirectUrl.

Pemberian Otorisasi Perangkat

Saat menggunakan Pemberian Otorisasi Perangkat, pengguna akan membuka URI verifikasi di perangkat lain. Kemudian, server otorisasi akan meminta mereka untuk menyetujui atau menolak permintaan tersebut.

Untuk mempermudah proses ini, gunakan RemoteActivityHelper untuk membuka halaman web di perangkat seluler pengguna yang disambungkan, seperti yang ditunjukkan dalam contoh berikut:

// 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.

Jika Anda memiliki aplikasi iOS, gunakan link universal untuk menangkap intent ini di aplikasi Anda, bukan mengandalkan browser untuk melakukan otorisasi token.

Melakukan transisi dari Login dengan Google Versi Lama

Credential Manager memiliki titik integrasi khusus untuk tombol Login dengan Google. Sebelumnya, tombol ini dapat ditambahkan di mana saja dalam UX autentikasi aplikasi, tetapi dengan penyertaannya di Credential Manager, opsi lama kini tidak digunakan lagi.

Catatan: Versi Credential Manager dari Login dengan Google untuk sementara tidak tersedia di perangkat Wear OS yang menjalankan Wear OS 3 (level API 30). Jika aplikasi memanggil Pengelola Kredensial di perangkat yang tidak mendukungnya, alur GetCredential akan memunculkan NoCredentialException, yang biasanya menunjukkan bahwa tidak ada kredensial yang tersedia di perangkat pengguna untuk aplikasi yang memanggil.

Untuk mengatasi hal ini, sebaiknya tambahkan tombol versi lama sebagai bagian dari alur UX autentikasi penggantian Anda dan tambahkan logika boolean untuk menonaktifkan tombol tersebut jika dijalankan di perangkat yang memiliki Wear OS 4 (level API 33) atau yang lebih tinggi. Hal ini memungkinkan pengguna memiliki akses ke tombol Login dengan Google yang sudah biasa mereka gunakan, terlepas dari kemampuan perangkat mereka, sekaligus menampilkan satu opsi autentikasi yang valid.

// 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+")
  }
)