Aplikasi Wear OS dapat berjalan secara mandiri tanpa aplikasi pendamping. Ini berarti aplikasi Wear OS perlu mengelola autentikasi sendiri saat mengakses data dari internet. Namun, 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, 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
Pada perangkat yang didukung yang menjalankan Wear OS 5 atau yang lebih baru, sistem mendeteksi apakah pengguna mengenakan perangkat di pergelangan tangan. Jika pengguna menonaktifkan deteksi pergelangan tangan, lalu melepas perangkat dari pergelangan tangan, sistem akan membuat perangkat tetap tidak terkunci selama jangka waktu yang lebih lama.
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
Pengelola Kredensial adalah API yang direkomendasikan untuk autentikasi di Wear OS. Fitur ini menyediakan lingkungan yang lebih aman bagi pengguna untuk login ke aplikasi Wear OS dalam setelan mandiri, tanpa memerlukan ponsel yang terhubung dan disambungkan serta tanpa perlu mengingat sandi mereka.
Dokumen ini menguraikan informasi yang diperlukan 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 lainnya yang dapat diterima (Berbagi Token Lapisan Data dan OAuth) sebagai cadangan untuk Pengelola Kredensial, dan petunjuk khusus untuk menangani transisi dari Tombol Login Google mandiri yang kini tidak digunakan lagi ke versi Pengelola Kredensial tersemat.
Kunci sandi di Wear OS
Developer sangat dianjurkan untuk menerapkan kunci sandi dalam penerapan Pengelola Kredensial Wear OS mereka. Kunci sandi adalah standar industri baru untuk autentikasi pengguna akhir, dan memiliki beberapa manfaat yang signifikan bagi pengguna.
Kunci sandi lebih mudah
- Pengguna dapat memilih akun yang akan digunakan untuk login. Mereka tidak perlu mengetik nama pengguna.
- Pengguna dapat melakukan autentikasi menggunakan kunci layar perangkat.
- Setelah kunci sandi dibuat dan terdaftar, pengguna dapat beralih dengan lancar ke perangkat baru dan langsung menggunakannya tanpa perlu mendaftar ulang.
Kunci sandi lebih aman
- Developer hanya menyimpan kunci publik ke server, bukan menyimpan sandi, yang berarti nilai yang diperoleh pelaku kejahatan untuk meretas server jauh lebih sedikit, dan pembersihan yang harus dilakukan jauh lebih sedikit jika terjadi pelanggaran.
- Kunci sandi memberikan perlindungan yang tahan terhadap phishing. Kunci sandi hanya berfungsi di situs dan aplikasi yang terdaftar; pengguna tidak dapat tertipu untuk melakukan autentikasi di situs yang menipu karena browser atau OS menangani verifikasi.
- Kunci sandi mengurangi kebutuhan untuk mengirim SMS, sehingga autentikasi lebih hemat biaya.
Mengimplementasikan kunci sandi
Menyertakan penyiapan dan panduan untuk semua jenis penerapan.
Penyiapan
Tetapkan API level target ke 35 di file build.gradle modul aplikasi Anda:
android { defaultConfig { targetSdkVersion(35) } }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 penerapan untuk Wear OS sama dengan jenis perangkat lainnya.
Gunakan petunjuk seluler untuk memulai dan menerapkan dukungan kunci sandi dan sandi.
Langkah-langkah untuk menambahkan dukungan Login dengan Google ke Pengelola Kredensial diarahkan untuk pengembangan seluler, tetapi langkah-langkahnya sama di Wear OS. Lihat bagian, Bertransisi 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 pengganti jika pengguna menutup layar Credential Manager.
Untuk menangani tindakan pengguna menutup layar Pengelola Kredensial, tangkap
NoCredentialException sebagai bagian dari
logika
GetCredential, dan 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 memberikan 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 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 ponsel 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 pada 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
Kunci Bukti untuk Pertukaran Kode (PKCE)
Untuk menggunakan PKCE secara efektif, gunakan RemoteAuthClient.
Kemudian, untuk melakukan 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 menampilkan UI otorisasi di browser web pada ponsel pengguna. Penyedia OAuth 2.0 akan mengautentikasi pengguna dan memperoleh izin pengguna untuk izin yang diminta. Respons akan dikirim ke URL alihan 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.
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.
Bertransisi 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 dalam Pengelola Kredensial, opsi lama kini tidak digunakan lagi.
// 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+")
}
)