Android uygulamanız için doğru geçiş anahtarı uygulamasını seçme

Geçiş anahtarları, güvenli ve kullanıcı dostu kimlik doğrulama için standart haline geldi ve giderek daha fazla hizmet, hem web sitelerinde hem de Android uygulamalarında geçiş anahtarlarını kullanmaya başladı. Ancak bir Android uygulamasına geçiş anahtarı eklemeye başladığınızda genellikle önemli bir mimari soruyla karşılaşırsınız: Yerel API'leri doğrudan mı çağırıyorsunuz, mevcut web oturum açma sayfanızı bir tarayıcı sekmesinde mi açıyorsunuz yoksa geçiş anahtarlarını uygulama içi WebView'da mı çalıştırıyorsunuz?

Genel Bakış

Android uygulamalarında geçiş anahtarlarını üç ana yaklaşımla destekleyebilirsiniz: Kimlik Bilgisi Yöneticisi, Auth Tab ve WebView. Resmi belgelerde her seçeneğin adım adım uygulama ayrıntıları yer alır. Geliştirme ve bakım maliyetlerini yönetilebilir düzeyde tutarken kullanıcı sürtüşmesini en aza indiren bir mimari seçmek, her seçeneğin özelliklerini ve kısıtlamalarını üst düzeyde anlamaya bağlıdır. Bu kılavuzda, uygulamanızın tasarımına ve mevcut kimlik doğrulama altyapısına göre doğru yaklaşımı nasıl seçeceğiniz açıklanmaktadır. Aşağıdaki tabloda bu yaklaşımlar karşılaştırılmaktadır:

Özellik Kimlik Bilgisi Yöneticisi Auth Tab WebView
Önerilen kullanım alanı Yerel oturum açma kullanıcı arayüzüne sahip uygulamalar Mevcut bir web oturum açma sayfasını veya OAuth ya da OpenID Connect (OIDC) kimlik sağlayıcısını (IdP) yeniden kullanma Mevcut karma WebView uygulamaları (yalnızca birinci taraf alan adı)
Kullanıcı arayüzü ve kullanıcı deneyimi Yerel OS alt sayfası ve klavye otomatik doldurma entegrasyonu Kimlik doğrulama için özel, minimal tarayıcı sekmesi Yerel OS alt sayfası içeren yerleşik web sayfası
Otomatik doldurma ve koşullu kullanıcı arayüzü Desteklenir (Kimlik Bilgisi Yöneticisi otomatik doldurma) Desteklenir (WebAuthn Koşullu Kullanıcı Arayüzü) Desteklenmiyor
Oturum ve kimlik bilgisi paylaşımı assetlinks.json ve paylaşılan rpId kullanarak web ve uygulama genelinde geçiş anahtarlarını paylaşır (Chrome çerezleri paylaşılmaz) Çerezleri ve kimlik bilgisi durumunu Chrome ile paylaşır (geçici tarama kullanılarak devre dışı bırakılabilir) Geçiş anahtarlarını assetlinks.json kullanarak paylaşır ancak çerezleri ve oturumları Chrome'dan ayırır.
Digital Asset Links (assetlinks.json) Bağlı taraf web alan adında zorunlu HTTPS yönlendirmeleri için yönlendirme URI'si alanınızda gereklidir (bunu gerektirmeyen özel şemalara tercih edilir) Bağlı taraf web alanında gereklidir (harici veya üçüncü taraf IdP'lerle kullanılamaz)

Kimlik Bilgisi Yöneticisi

Android uygulamanızda yerel oturum açma veya kayıt ekranları varsa Kimlik Bilgisi Yöneticisi Jetpack kitaplığı, önerilen birincil yaklaşımdır.

Kimlik Bilgisi Yöneticisi'nin en önemli avantajı; geçiş anahtarlarını, şifreleri ve Google ile oturum açma özelliğini tek bir sistem alt sayfasında birleştirmesidir. Kullanıcılar oturum açarken uygulamanızdan ayrılmadan tek dokunuşla biyometrik kimlik doğrulama işlemini tamamlayabilir. Bu sayede oturum açma sürecindeki zorluklar azalır. Kullanıcı ilk alt sayfayı kapatıp bir kullanıcı adı veya şifre giriş alanına dokunsa bile geçiş anahtarlarını, şifreleri ve Google ile oturum açma seçeneğini doğrudan klavyede veya açılır otomatik doldurma önerilerinde göstermek için PendingGetCredentialRequest yöntemini kullanabilirsiniz. Bu yedek, WebAuthn koşullu kullanıcı arayüzüne eşdeğer yerel bir otomatik doldurma entegrasyonu sağlar.

Geçiş anahtarı, Google ile oturum açma ve şifre seçeneklerini gösteren Kimlik Bilgisi Yöneticisi alt sayfası.
Şekil 1. Kimlik Bilgisi Yöneticisi; geçiş anahtarlarını, Google ile oturum açma özelliğini ve şifreleri sistemin alt sayfasında birleştirir.

Kimlik Bilgisi Yöneticisi, modern web geçiş anahtarı yaşam döngüsü özellikleriyle tam özellik eşitliği de sağlar. Kimlik Bilgisi Yöneticisi ile şunları yapabilirsiniz:

Geçiş anahtarları, Android 9 (API düzeyi 28) ve sonraki sürümleri çalıştıran cihazlarda desteklenir. Şifreler gibi diğer kimlik bilgileri ise Google Play Hizmetleri aracılığıyla daha eski Android sürümlerinde desteklenmeye devam eder. Android 14 (API düzeyi 34) ve sonraki sürümlerde Kimlik Bilgisi Yöneticisi, kullanıcı tarafından seçilen tüm üçüncü taraf kimlik bilgisi sağlayıcılarla da çalışır. View tabanlı otomatik doldurma entegrasyonu (PendingGetCredentialRequest) ve Signal API gibi ek özellikler için Android 15 (API düzeyi 35) ve sonraki sürümler gerekir.

Kimlik bilgilerini web ve uygulama arasında paylaşma

Başlamak için web sitenizi ve Android uygulamanızı ilişkilendirmek üzere web alan adınızda bir Digital Asset Links (assetlinks.json) dosyası barındırmak için Ön koşullar'ı uygulayın. Web sitenizi ve uygulamanızı assetlinks.json aracılığıyla ilişkilendirmek, aynı bağlı taraf kimliğini (rpId) paylaştıkları anlamına gelir. Böylece, Chrome'da web sitenizde oluşturulan geçiş anahtarları, Kimlik Bilgisi Yöneticisi aracılığıyla yerel Android uygulamanızda çalışır ve uygulamanızda oluşturulan geçiş anahtarları web sitenizde çalışır. Kimlik Bilgisi Yöneticisi, kimlik bilgilerini web siteniz ve uygulamanız arasında paylaşır. Auth Tab'i yalnızca web oturum açma kullanıcı arayüzünüzü veya IdP sayfanızı yeniden kullanmak istediğinizde kullanmanız gerekir.

Geçiş anahtarı oluşturma bölümünde açıklandığı gibi, sunucunuzu Android uygulama kaynaklarını doğrulayacak şekilde de yapılandırmanız gerekir (android:apk-key-hash:ENCODED_SHA256_HASH, APK imzalama sertifikanızın doldurulmamış Base64URL ile kodlanmış SHA-256 karması kullanılarak biçimlendirilmiş). Uygulamanızın yerel bir kullanıcı arayüzü varsa ve geçiş anahtarlarıyla oturum açmak için işletim sistemine entegre bir deneyim istiyorsanız Kimlik Bilgisi Yöneticisi'ni seçin.

Auth Tab

Birçok hizmet, OAuth veya OpenID Connect (OIDC) üzerine kurulu bir kimlik sağlayıcı (IdP) mikro hizmeti kullanır ya da geçiş anahtarı özellikli mevcut bir web oturum açma sayfasını mobil uygulamalarda yeniden kullanmak ister. Geçmişte uygulamalar bu akışlar için Özel Sekmeler'i kullanıyordu. Chrome 137 ve AndroidX Browser 1.9.0'dan itibaren, Kimlik Doğrulama Sekmesi, kimlik doğrulama akışları için özel olarak tasarlanmış bir tarayıcı sekmesi sunar.

Genel amaçlı tarayıcı menü öğeleri olmadan minimal bir tarayıcı oturum açma arayüzü gösteren Auth Tab.
Şekil 2. Auth Tab, kimlik doğrulama akışları için özel olarak tasarlanmış, odaklanmış bir tarayıcı arayüzü sunar.

Standart Özel Sekmeler, genel amaçlı uygulama içi tarayıcılar olarak tasarlanmıştır. Oturum açmayla ilgili olmayan kullanıcı arayüzü öğelerini (ör. paylaşım menüsü, yer işaretleri ve Chrome'da aç) göstererek kullanıcıların dikkatini dağıtabilir. Ayrıca, kimlik doğrulama sonrası yönlendirmeleri almak için manifest dosyanızda intent filtreleri tanımlamanız, ortak metin kodu eklemeniz ve kötü amaçlı uygulamaların intent'leri ele geçirmesine karşı önlemler almanız gerekir.

Auth Tab, kimlik doğrulamaya özgü bu zorlukları çözer. Küçültme düğmesi ve paylaşım menüsü gibi gereksiz tarayıcı kullanıcı arayüzü öğelerini kaldırır ve geçiş anahtarı ile şifre otomatik doldurma gibi yalnızca temel oturum açma özelliklerini içeren odaklanmış bir arayüz sunar. Auth Tab, kimlik doğrulama yönlendirmelerini OS intent'leri üzerinden yönlendirmek yerine, özel bir şema veya Digital Asset Links ile doğrulanmış bir HTTPS URL'si kullanarak doğrudan uygulama içi geri çağırmaya iletir. Bu sayede güvenliği artırır ve uygulama şablonunu azaltır.

Oturum paylaşımı ve Özel Sekmeler yedek seçeneği

Kimlik Doğrulama Sekmesi, varsayılan olarak çerezleri ve kimlik bilgisi durumunu doğrudan sistem Chrome tarayıcısıyla da paylaşır. Bu paylaşım, uygulamanızın Chrome'daki etkin oturum açma oturumlarından yararlanmasına ve mevcut WebAuthn uygulamanızı olduğu gibi çalıştırmasına olanak tanır. Buna Koşullu kullanıcı arayüzü ve Anında kullanıcı arayüzü modu (Kimlik Bilgisi Yöneticisi'nin preferImmediatelyAvailableCredentials özelliğinin web eşdeğeri) dahildir. Diğer yandan, kullanım alanınız tarayıcıyla çerezleri veya tarama geçmişini paylaşmayan izole bir kimlik doğrulama oturumu gerektiriyorsa AuthTabIntent.Builder.setEphemeralBrowsingEnabled(true) yöntemini çağırarak geçici taramayı etkinleştirebilirsiniz.

androidx.browser:browser (sürüm 1.9.0 veya sonraki sürümler) uygulamanızla birlikte paketlenirken Auth Tab'in çalışma zamanında çalışıp çalışmayacağı, kullanıcının varsayılan tarayıcısına bağlıdır. Varsayılan tarayıcı, Chrome'un 137'den eski bir sürümü veya Auth Tab'i desteklemeyen üçüncü taraf bir tarayıcıysa Auth Tab otomatik olarak standart bir Özel Sekme başlatır. Bu yedek gerçekleştiğinde, kimlik doğrulama sonrası yönlendirme, Auth Tab'ın geri çağırma işlevi (ActivityResultCallback) yerine standart Özel Sekmeler'de olduğu gibi AndroidManifest.xml içindeki bir intent filtresi aracılığıyla döndürülür. Üretimde Google, akışınızı dallandırmak için CustomTabsClient.isAuthTabSupported(context, provider) kullanarak varsayılan tarayıcı desteğini önceden kontrol etmenizi veya uygulamanızın her iki yoldan gelen sonuçları işleyebilmesi için manifest intent filtresini korumanızı önerir. Somut yedek uygulama örnekleri için Android Tarayıcı Yardımcısı'na bakın.

OAuth ve OIDC güvenlik şartları

Auth Tab, yalnızca tarayıcıdan uygulamanıza geri dönen istemci tarafı yönlendirme kanalının güvenliğini sağlar ve bu kanalı basitleştirir. OAuth veya OIDC protokolünün güvenliğini otomatik olarak sağlamaz. Özellikle Özel Sekmeler yedek davranışı göz önüne alındığında, Yerel Uygulamalar için OAuth 2.0 (RFC 8252)'yi uygulamanız gerekir. Özellikle, yetkilendirme kodunun ele geçirilmesini önlemek için code_challenge ve code_verifier parametrelerini kullanarak PKCE'yi (Kod Değişimi İçin Doğrulama Anahtarı, RFC 7636), siteler arası istek sahteciliği (CSRF) ve oturum sabitleme saldırılarını önlemek için state parametre doğrulamasını ve kimlik jetonu yeniden oynatma saldırılarını önlemek için OpenID Connect'te nonce parametre oluşturma ve doğrulamayı birleştirin. Bu korumalar sayesinde Google, web tabanlı oturum açma mimarilerinin standart özel sekmelerden Auth Tab'e taşınmasını önerir.

WebView

Bazı uygulamalar, yalnızca oturum açma ekranını yerel kullanıcı arayüzüne (Kimlik Bilgisi Yöneticisi) veya tarayıcı sekmesine (Kimlik Doğrulama Sekmesi) ayırmanın pratik olmadığı karma bir WebView mimarisi üzerine kurulmuştur. Bu durumlarda WebAuthn desteğini doğrudan WebView içinde etkinleştirebilirsiniz.

WebView'da geçiş anahtarlarını kullanmak için hem AndroidX WebKit kitaplığını (androidx.webkit:webkit 1.12.0 veya sonraki bir sürüm) hem de Kimlik Bilgisi Yöneticisi bağımlılıklarını (androidx.credentials:credentials ve androidx.credentials:credentials-play-services-auth) build.gradle dosyanıza ekleyin. Ardından, WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION) kullanarak özellik desteğini kontrol edin ve WebSettingsCompat.setWebAuthenticationSupport(webView.settings, WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP) yöntemini çağırarak WebAuthn desteğini açıkça etkinleştirin. Bu yapılandırma, WebView'daki web sayfalarından gelen geçiş anahtarı oluşturma ve kimlik doğrulama isteklerini otomatik olarak Kimlik Bilgisi Yöneticisi'ne bağlar.

Alan ve kullanıcı deneyimi kısıtlamaları

Yerel Kimlik Bilgisi Yöneticisi entegrasyonlarında olduğu gibi, uygulamanızı ilişkilendirmek için bağlı taraf web alan adınızda bir Digital Asset Links (assetlinks.json) dosyası barındırmak üzere Ön koşullar'ı uygulamanız gerekir. Sunucunuz, kaynak olarak android:apk-key-hash:ENCODED_SHA256_HASH (Base64URL ile kodlanmış SHA-256 sertifika karması) alır. Bu yaklaşım, Android uygulamanızın imzalama sertifikasına güvenmek için assetlinks.json dosyasının, güvenen taraf web alan adında barındırılmasını gerektirdiğinden yalnızca güvenen taraf web alan adını kontrol ettiğinizde (birinci taraf web oturum açma) çalışır. Kimlik doğrulama akışınız, uygulama paketiniz için assetlinks.json barındıramayacağınız harici veya üçüncü taraf bir IdP'ye yönlendiriyorsa WebView yerine Auth Tab (veya Kimlik Bilgisi Yöneticisi aracılığıyla yerel Google ile oturum açma) kullanmanız gerekir.

Kullanıcı deneyimi ve işlevsel kısıtlamalarla ilgili iki noktaya dikkat edin: WebView, koşullu kullanıcı arayüzünü (kullanıcı bir giriş alanına odaklandığında mediation: "conditional" otomatik doldurma entegrasyonu) desteklemez ve çerezleri ya da oturum açma oturumlarını sistem Chrome tarayıcısıyla paylaşmaz. Bu kısıtlamalar nedeniyle Google, yeni kimlik doğrulama akışları tasarlarken Kimlik Bilgisi Yöneticisi'ni veya Auth sekmesini kullanmanızı önerir. Ancak büyük mimari değişiklikler yapmadan mevcut bir birinci taraf hibrit uygulamaya geçiş anahtarı desteği eklemek istiyorsanız geçiş anahtarlarını WebView ile entegre edebilirsiniz.

Özet

Uygulamanızın mevcut kullanıcı arayüzü ve kimlik doğrulama altyapısından başlamak, doğru geçiş anahtarı yaklaşımını seçmenize yardımcı olur:

  • Uygulamanızda yerel bir oturum açma kullanıcı arayüzü varsa ve tarayıcı ekranına geçmeden işletim sistemine entegre bir deneyim istiyorsanız geçiş anahtarıyla oturum açmak için Kimlik Bilgisi Yöneticisi'ni seçin.
  • OAuth veya OIDC IdP mikro hizmeti çalıştırıyorsanız, harici bir IdP'ye yönlendiriyorsanız ya da mevcut geçiş anahtarı özellikli web oturum açma sayfanızı (koşullu kullanıcı arayüzü dahil) yeniden kullanmak ve etkin tarayıcı oturumlarını Chrome ile paylaşmak istiyorsanız Auth Tab'i kullanın ve Yerel Uygulamalar için OAuth 2.0 (RFC 8252)'deki güvenlik şartlarını (özellikle PKCE, state ve nonce) uygulayın.
  • Uygulamanız, oturum açma işleminin yerleşik birinci taraf web ekranlarında kalması gereken karma bir WebView mimarisi üzerine kuruluysa koşullu kullanıcı arayüzü desteğinin ve izole çerezlerin eksikliğini hesaba katarak WebView'ı kullanın.

Sonraki adımlar