Yerel Uygulama Geçiş Anahtarları: Native ve WebView Uygulaması

Not: Sistem ve Gömülü WebView genellikle birleştirilir; Sistem WebView girişi yönetirken (otomatik kimlik bilgisi paylaşımı ile), Gömülü WebView ayarlarda geçiş anahtarı yönetimini işler.

Önemli Karar Faktörleri:

• OAuth tabanlı giriş mi? → Sistem WebView (ASWebAuthenticationSession, Chrome Custom Tabs)
• Web kimlik doğrulamasını native kabukta yeniden kullanmak mı istiyorsunuz? → Gömülü WebView (WKWebView, Android WebView ve WebKit 1.12.1+)
• Öncelikle native uygulama mı geliştiriyorsunuz? → Native Uygulama (Apple AuthenticationServices, Google Credential Manager)

Modern mobil platformlar, geçiş anahtarlarını yerel uygulamanıza entegre etmek için kullanıcı deneyimi, teknik karmaşıklık ve OAuth uyumluluğu açısından farklı ödünleşimleri olan üç farklı yaklaşım sunar:

1. Native Uygulama: Platform API'lerini (iOS AuthenticationServices, Android Credential Manager) kullanarak geçiş anahtarı akışlarını doğrudan uygulamanıza oluşturun. Sorunsuz biyometrik kimlik doğrulama ile en iyi kullanıcı deneyimini sağlar, ancak orta ile yüksek teknik uygulama çabası gerektirir.

2. Sistem WebView: Kimlik doğrulamayı yönetmek için platformun tarayıcı bileşenini (iOS ASWebAuthenticationSession / SFSafariViewController, Android Chrome Custom Tabs) kullanın. OAuth tabanlı giriş akışları için mükemmeldir ve kimlik bilgilerini sistem tarayıcısıyla paylaşır.

3. Gömülü WebView: Web kimlik doğrulamasını native bir uygulama iskeletiyle yeniden kullanmak için uygulamanızın içine özelleştirilebilir bir web görünümü (iOS WKWebView, Android WebView) gömün. URL çubukları olmadan native benzeri bir görünüm ve web görünümü kullanıcı arayüzü üzerinde tam kontrol sağlar. Geçiş anahtarı işlevselliğini etkinleştirmek için izinler ve yetkilendirmeler (iOS) ile AndroidX WebKit 1.12.1+ (Android) ile WebView yapılandırması dahil olmak üzere ek kurulum gerektirir.

Doğru seçim, uygulamanızın kimlik doğrulama mimarisine, OAuth sağlayıcıları kullanıp kullanmadığınıza, kullanıcı arayüzü üzerinde ne kadar kontrole ihtiyacınız olduğuna ve öncelikle native olarak mı geliştirdiğinize yoksa web bileşenlerini mi yeniden kullandığınıza bağlıdır.

Kurumsal Passkey Whitepaper. Passkey programları için pratik rehberler, geçiş kalıpları ve KPI'lar.

Whitepaper al

Native bir geçiş anahtarı uygulaması, platforma özgü API'ler kullanılarak doğrudan uygulamanızın kullanıcı arayüzüne yerleştirilen kimlik doğrulama akışları ile optimum kullanıcı deneyimini sağlar. Kullanıcılar platforma özgü iletişim kutularından, sorunsuz biyometrik doğrulamadan ve mümkün olan en hızlı giriş sürelerinden yararlanır.

Native Uygulamayı ne zaman seçmelisiniz:

• Yeni bir yerel uygulama geliştirirken veya kimlik doğrulamayı yeniden yapılandırırken (refactoring)
• Anında, sessiz kimlik doğrulama ile mümkün olan en iyi kullanıcı deneyimini istiyorsanız
• Uygulama başlangıcında otomatik geçiş anahtarı istemleri: Native uygulamalar, geçiş anahtarları mevcut olduğunda otomatik olarak geçiş anahtarı katmanını görüntülemek için preferImmediatelyAvailableCredentials kullanabilir ve tanımlayıcı girişi gerektirmeden en hızlı giriş deneyimini sunar.
• Kimlik doğrulama kullanıcı arayüzü ve akışı üzerinde tam kontrole ihtiyaç duyuyorsanız
• Platforma özgü uygulamaya (iOS Swift, Android Kotlin) yatırım yapmaya istekliyseniz

Temel Avantaj: preferImmediatelyAvailableCredentials()

Native uygulamalar, geçiş anahtarları mevcut olduğunda uygulama başlar başlamaz görünen bir otomatik geçiş anahtarı katmanı oluşturmak için preferImmediatelyAvailableCredentials() yönteminden yararlanabilir. Bu kullanıcı adı gerektirmeyen (usernameless) akış, mümkün olan en hızlı giriş deneyimini sağlar; kullanıcılar önce bir tanımlayıcı girmeden geçiş anahtarlarını anında görürler. Bu özellik yalnızca native uygulamalara özeldir ve WebView varyantlarında bulunmaz.

Aşağıdaki diyagram, native kimlik doğrulamanın WebView'in Conditional UI yaklaşımına kıyasla nasıl daha hızlı bir kullanıcı yolculuğu sunduğunu göstermektedir:

Native'in otomatik katmanı, WebView uygulamaları kullanıcıların önce giriş alanlarıyla etkileşime girmesini gerektirirken, kimlik doğrulama uygulama başlatılır başlatılmaz başladığından, daha yüksek geçiş anahtarı kullanım oranlarıyla üstün UX sağlar.

Teknik Gereksinimlere Genel Bakış:

Native geçiş anahtarı entegrasyonu, uygulamanız ile web etki alanınız arasında kriptografik güven gerektirir. Bu olmadan OS tüm WebAuthn işlemlerini reddedecektir. Temel gereksinimler:

1. /.well-known/ adresinde barındırılan Uygulama-Etki Alanı İlişkilendirme Dosyaları
2. Web etki alanınızla eşleşen Doğru Relying Party ID
3. Platforma Özgü Yetenekler (Bölüm 4'te detaylandırılmıştır)

En büyük fayda: Web sitenizde oluşturulan geçiş anahtarları uygulamanızda sorunsuz çalışır ve bunun tersi de geçerlidir.

Geçiş anahtarlarını iOS'ta native olarak uygulamak, WebAuthn işlemleri için bir API sağlayan Apple'ın AuthenticationServices çerçevesini içerir:

Temel Bileşenler:

• ASAuthorizationController: Kimlik doğrulama akışını yönetir
• ASAuthorizationPlatformPublicKeyCredentialProvider: Geçiş anahtarı istekleri oluşturur
• Geçiş anahtarı girişlerini yönetmek için üç farklı kullanıcı arayüzü (UI) modu:
  • Metin alanı girişi: Düğme gönderiminde geçiş anahtarı girişiyle başlayan geleneksel kullanıcı adı alanı
  • Geçiş anahtarı modal katmanı: Mevcut geçiş anahtarlarını listeleyen OS iletişim kutusu
  • Conditional UI: Klavyenin üzerindeki QuickType çubuğunda geçiş anahtarı önerileri

Geliştirme İpuçları

• AASA Önbelleğe Alma: Apple, AASA dosyasını agresif bir şekilde (24 saate kadar) önbelleğe alır, bu da test etmeyi zorlaştırabilir. Çözüm: Test cihazınızda Geliştirici Modunu etkinleştirin ve yeni getirmeleri zorlamak için AASA URL'nizin sonuna ?mode=developer ekleyin.
• Performans Testi: Gerçek dünya gecikmesini gözlemlemek için yüzlerce kimlik bilgisi içeren iCloud hesaplarıyla test yapın. Sistem katmanı, birçok kayıtlı geçiş anahtarı olduğunda hafif bir gecikme gösterebilir.

Android'in native geçiş anahtarı uygulaması, Credential Manager API'yi (veya geriye dönük uyumluluk için eski FIDO2 API'sini) kullanır:

Temel Bileşenler:

• CredentialManager: Tüm kimlik bilgisi işlemleri için merkezi API
• CreatePublicKeyCredentialRequest: Geçiş anahtarı kaydı için
• GetCredentialRequest: Geçiş anahtarı kimlik doğrulaması için
• İki ana kullanıcı arayüzü (UI) modu:
  • Metin alanı girişi: Düğme gönderiminde geçiş anahtarı girişiyle başlayan geleneksel kullanıcı adı alanı
  • Geçiş anahtarı modal katmanı: Mevcut geçiş anahtarlarını listeleyen OS iletişim kutusu

Not: Android şu anda native uygulamalarda iOS'un Conditional UI klavye önerilerinden yoksundur (gerçi Conditional UI web uygulamalarında çalışır).

Geçiş anahtarlarını native olarak uygulamanın önemli zorlukları ve çıkarılan dersleri vardır: OS düzeyinde entegre olmak, farklı cihazlar ve OS sürümlerinde sorunları ortaya çıkarabilir.

1. Örneğin, ekibimiz apple-app-site-association dosyasının (uygulama/web kimlik bilgisi bağlantısı için kullanılan) Apple tarafından agresif bir şekilde önbelleğe alınması ve belirli Android OEM biyometrik istemlerindeki ince UI farklılıkları gibi sorunlarla karşılaştı.
2. Ayrıca, bazı kurumsal senaryolarda, yönetilen cihazların geçiş anahtarı senkronizasyonunun ilke tarafından devre dışı bırakılmış olabileceğini göz önünde bulundurun. iCloud Keychain veya Google Password Manager senkronizasyonunun kapatıldığı kurumsal ortamlarda, geçiş anahtarları cihaza bağlı hale gelir ve dolaşamaz - bu, plan yapılması gereken önemli bir senaryodur (ör. kullanıcıların yeni bir telefon aldıklarında hala giriş yapabilmelerini sağlamak).
3. Ek olarak, üçüncü taraf kimlik bilgisi yöneticisi uygulamaları akışı etkileyebilir. Örneğin, bir kullanıcının aktif bir kimlik bilgisi sağlayıcısı olarak 1Password gibi bir parola yöneticisi ayarlanmışsa, bu genellikle geçiş anahtarı oluşturmayı ve depolamayı engelleyerek platformun native kimlik bilgisi yöneticisine göre öncelik alır.

Geçiş anahtarlarını ham platform API'lerini kullanarak uygulayabilirsiniz, ancak amaca yönelik oluşturulmuş SDK'lar WebAuthn karmaşıklığını, uç durumları ele alarak ve yerleşik telemetri sağlayarak geliştirmeyi önemli ölçüde hızlandırır. SDK'lar ayrıca birim testi için mocklanabilir arayüzler sunar (simülatörlerde biyometriyi test edemeyeceğiniz için bu çok önemlidir).

Öneri: Native uygulamalar için, üretim dağıtımları aracılığıyla keşfedilen çok sayıda uç durumu ele alan, ek telemetri ve test sağlayan Corbado SDK'larını (iOS Swift Passkey SDK, Android Kotlin Passkey SDK) kullanmanızı öneririz.

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

We hit 80% mobile passkey activation across 5M+ users without replacing our IDP.

See how VicRoads scaled passkeys to 5M+ users — alongside their existing IDP.

Read the case study

Sistem WebView'leri, uygulamanız içinde kimlik doğrulamayı yönetmek için platformun native tarayıcı bileşenini kullanır. Tamamen native uygulamaların aksine, Sistem WebView'leri gerçek sistem tarayıcısını (iOS'ta Safari, Android'de Chrome) kullanarak web içeriğini görüntüler ve paylaşılan çerezleri, kayıtlı kimlik bilgilerini ve tanıdık tarayıcı güvenlik göstergelerini korur.

Sistem WebView'i ne zaman seçmelisiniz:

• Uygulamanız OAuth tabanlı giriş kullanıyorsa: Sistem WebView, güvenli kimlik doğrulama sağlayan OAuth2/OIDC akışları için önerilen yaklaşımdır
• Mobil uygulamalarda yeniden kullanmak istediğiniz mevcut web tabanlı kimlik doğrulaması varsa
• Native olarak yeniden oluşturmadan birden fazla kimlik doğrulama yöntemini (parolalar, sosyal giriş, geçiş anahtarları) desteklemeniz gerekiyorsa
• Web ve mobil arasında tek bir kimlik doğrulama kod tabanını korumak istiyorsanız

Temel Avantajlar:

• OAuth uyumluluğu: OAuth/OIDC kimlik doğrulama akışları için amaca yönelik oluşturulmuştur
• Güvenlik göstergeleri: Kullanıcılar gerçek URL'yi ve SSL sertifikalarını görerek güven oluşturur
• Düşük uygulama çabası: Minimum native kod gerektirir
• Tutarlı UX: Kullanıcıların zaten güvendiği tanıdık tarayıcı arayüzü

Platform Bileşenleri:

• iOS: ASWebAuthenticationSession (kimlik doğrulama akışları için önerilir) veya SFSafariViewController (genel tarama)
• Android: Chrome Custom Tabs (CCT)

Google ve GitHub gibi büyük şirketler, mevcut web kimlik doğrulama sayfalarında WebView katmanları aracılığıyla mobil uygulamalarına geçiş anahtarı girişi eklemek için bu yaklaşımı benimsedi. Bu, tamamen native kimlik doğrulama yeniden yapılandırmaları hemen mümkün olmadığında iyi çalışır.

iOS, kimlik doğrulama için iki ana Sistem WebView bileşeni sağlar:

ASWebAuthenticationSession (Kimlik Doğrulama İçin Önerilir):

• OAuth/OIDC ve güvenli giriş akışları için amaca yönelik olarak oluşturulmuştur
• Kullanıcıya, uygulamanın kimlik doğrulamak istediğini otomatik olarak sorar
• Çerezleri ve kimlik bilgilerini Safari ile paylaşır
• iCloud Keychain aracılığıyla geçiş anahtarlarını destekler

SFSafariViewController (Genel Tarama):

• Uygulama içinde tam Safari deneyimi
• URL çubuğunu ve güvenlik göstergelerini gösterir
• iOS 11+ sürümlerinde Safari çerezlerini paylaşmaz; Safari oturumu paylaşımı gerektiğinde ASWebAuthenticationSession kullanın
• Daha az özelleştirilebilir ancak kullanıcılar için daha güvenilirdir

Uygulamanız OAuth tabanlı giriş kullanıyorsa, özellikle kimlik doğrulama senaryoları için tasarlandığından ve güvenlik ile kullanıcı deneyiminin en iyi dengesini sağladığından ASWebAuthenticationSession önerilen seçimdir.

Chrome Custom Tabs (CCT), uygulamanız içinde Chrome destekli bir kimlik doğrulama deneyimi sağlar:

Temel Özellikler:

• Çerezleri ve kimlik bilgilerini Chrome tarayıcı ile paylaşır
• URL'yi ve güvenlik göstergelerini gösterir
• Araç çubuğu rengini ve markalamayı özelleştirebilir
• Daha hızlı yükleme süreleri için ön ısıtma (pre-warming)

OAuth Entegrasyonu: Chrome Custom Tabs, iOS ASWebAuthenticationSession'ın Android eşdeğeridir ve saklanan geçiş anahtarlarına erişimi korurken mükemmel OAuth desteği sağlar.

Canlı demo ile passkeys deneyin.

Passkeys dene

Gömülü WebView'ler, uygulamanızdaki web içeriği oluşturma işlemi üzerinde tam kontrol sağlayarak URL çubuğu olmadan çerezlerin, oturumların ve gezinmenin doğrudan manipülasyonuna olanak tanır. Ancak, bu kontrol geçiş anahtarı işlevselliğini etkinleştirmek için ek teknik gereksinimlerle birlikte gelir.

Gömülü WebView'i ne zaman seçmelisiniz:

• Native benzeri deneyim: Uygulamanız, native bir görünümü ve hissi korumak için kimlik doğrulamayı zaten özelleştirilmiş bir web görünümünün içine yerleştiriyorsa ve bu tutarlı kullanıcı deneyimini korumak istiyorsanız
• Oturum/çerez kontrolüne ihtiyaç duyuyorsanız: Uygulamanız, OAuth kimlik doğrulaması tamamlandıktan sonra kimlik doğrulama token'larının ve oturum durumunun doğrudan manipülasyonunu gerektiriyorsa
• Sistem WebView kimlik doğrulamasının bir kimlik doğrulama kodu döndürdüğü ancak gömülü bağlamlarda oturum döndürmediği mevcut bir kimlik doğrulama akışı varsa
• Birden fazla gömülü web ekranında doğrulanmış durumu korumanız gerekiyorsa
• Yalnızca birinci taraf kimlik doğrulama: Uygulamanız kimlik doğrulamayı doğrudan yönetir, üçüncü taraf geçiş anahtarı uygulamaları için buraya bakın
• Çalışma zamanı özellik algılaması ile AndroidX WebKit 1.12.1+
• Giriş için Conditional UI sınırlamasını (Gömülü WebView'de desteklenmez) kabul ediyorsanız, yönetim ayarları için geçerli değildir

Önemli Bağlam:

Pek çok uygulama hibrit bir yaklaşım kullanır: Sistem WebView ilk OAuth kimlik doğrulamasını (geçiş anahtarlarının sorunsuz çalıştığı yer) yönetir, ardından ayarlardaki geçiş anahtarlarını yönetmek için kimlik doğrulama sonrası Gömülü WebView'e geçer. Zorluk, geçiş anahtarlarını doğrudan Gömülü WebView'ler içinde kullanmaya çalışırken ortaya çıkar.

Teknik Gereksinimler:

Gömülü WebView'ler, Sistem WebView'lere kıyasla ek kurulum gerektirir:

1. iOS: Associated Domains yetkilendirmeleri, AASA dosya yapılandırması
2. Android: Geçiş anahtarı işlevselliğini etkinleştirmek için WebView WebAuthn yapılandırması ile AndroidX WebKit 1.12.1+ (özellik algılama gereklidir)
3. Her İkisi: Düzgün yapılandırılmış bilinen (well-known) ilişkilendirme dosyaları ve Digital Asset Links

Platform Bileşenleri:

• iOS: WKWebView
• Android: android.webkit.WebView

Ödünleşimler:

• Orta karmaşıklık: WebView yapılandırması (Android WebKit 1.12.1+) ve yetkilendirme kurulumu (iOS) gerektirir
• Daha düşük geçiş anahtarı benimsemesi: Kullanıcılar native uygulamaya kıyasla daha fazla sürtünmeyle karşılaşabilir
• Conditional UI desteklenmez: Giriş alanlarında geçiş anahtarı otomatik doldurma Android Gömülü WebView'de çalışmaz
• Sınırlı platform desteği: Bazı özellikler tutarlı çalışmayabilir (ör. otomatik geçiş anahtarı oluşturma)

Geçiş anahtarlarını WebView'ler aracılığıyla uygularken, Sistem WebView'leri ile Gömülü WebView'ler arasındaki ayrımı anlamak çok önemlidir. Yukarıda özetlenen üç yaklaşım (Native Uygulama, Sistem WebView ve Gömülü WebView) farklı kullanım senaryolarına hizmet eder.

iOS'ta, uygulama içinde web içeriğini görüntülemek için birden fazla seçeneğiniz vardır:

• WKWebView, WebKit çerçevesinin (iOS 8'de tanıtıldı) bir parçası olan özelleştirilebilir bir WebView'dir. Web içeriğinin görünümü ve davranışı üzerinde size çok fazla kontrol sağlar.
• SFSafariViewController, Apple tarafından sağlanan ve uygulamanızın içinde hafif bir Safari tarayıcısı görevi gören bir view controller'dır. Safari'nin motorunu kullanır. iOS 11+ sürümlerinde ayrı bir çerez deposu vardır ve Safari çerezlerini paylaşmaz. Safari oturum paylaşımı gerektiğinde ASWebAuthenticationSession kullanın.
• SFAuthenticationSession / ASWebAuthenticationSession, OAuth/OpenID veya diğer güvenli giriş akışları için özel olarak tasarlanmış özelleşmiş web kimlik doğrulama oturumlarıdır (iOS 11/12'den beri mevcuttur). Bunlar da temelinde Safari'den yararlanır, ancak kimlik doğrulama akışlarına odaklanır ve paylaşılan çerezler ile Çoklu Oturum Açma (SSO) gibi şeyleri otomatik olarak yönetir.

Android'deki ana seçenekler şunlardır:

• Android WebView, standart WebView widget'ıdır (android.webkit.WebView), etkinliklerinize (activities) gömülebilen mini bir tarayıcı gibidir. Son derece özelleştirilebilirdir ancak uygulamanızın işlemi (process) içinde çalışır.
• Chrome Custom Tabs (CCT), uygulamanızın bağlamı içinde Chrome destekli bir sekme açan bir özelliktir. Custom Tabs, uygulamanızın bir parçası olarak görünür, ancak önceden yükleme, paylaşılan çerezler ve kullanıcı güveni için tanıdık URL çubuğu gibi özelliklerle Chrome tarayıcısı (yüklüyse) tarafından desteklenir.

Aşağıdaki bölümlerde, iOS ve Android için bu WebView türlerini biraz daha derinlemesine inceleyeceğiz ve hangisinin geçiş anahtarı kimlik doğrulama akışları için en uygun olabileceğini tartışacağız.

Son haberler için Passkeys Substack'e abone olun.

Abone ol

Apple'ın platformu, yukarıda listelenen üç WebView seçeneğini sunar. Seçiminiz, geçiş anahtarlarının uygulama içinde ne kadar sorunsuz kullanılabileceğini etkileyecektir:

iOS'ta farklı WebView davranışlarını test etmek için WebView - WKWebView and UIWebView rendering uygulamasını öneririz.

WKWebView, iOS için çok yönlü bir WebView bileşenidir. Geliştiriciler, kullanıcı arayüzü ve davranışı üzerinde yüksek derecede kontrol sahibi olarak web içeriğini oluşturmak için bir WKWebView gömebilir. WKWebView, Safari ile aynı işleme motorunu kullanır, bu nedenle oldukça performanslıdır ve modern web özelliklerini destekler. Teorik olarak WKWebView, doğru yapılandırılırsa WebAuthn'i (ve dolayısıyla geçiş anahtarlarını) yönetebilir, ancak güvenlikle ilgili bazı gelişmiş tarayıcı özelliklerinin kısıtlanabileceğini unutmayın. Dikkat edilmesi gereken bir nokta, WKWebView'in varsayılan olarak Mobil Safari ile çerezleri veya keychain verilerini paylaşmamasıdır. Kullanıcıların baştan giriş yapması gerekebilir çünkü WebView oturumları Safari'nin oturumundan izole edilmiştir. Ayrıca, WKWebView içeriği uygulama tarafından tamamen özelleştirilebildiğinden, kullanıcı bir adres çubuğu veya Safari arayüzü görmez – bu markalama için harikadır, ancak kullanıcının sayfanın meşruiyetini doğrulamak için daha az ipucuna sahip olduğu anlamına gelir (oltalama karşıtı bir endişe). Bazı uygulamalar komut dosyaları (scripts) enjekte etmek veya içeriği değiştirmek için WKWebView'i kötüye bile kullanmıştır (örneğin TikTok'un uygulama içi tarayıcıları aracılığıyla izleme JS'si enjekte ettiği belirtilmiştir), bu nedenle WKWebView'i güvenli, kullanıcı güvenine layık bir şekilde kullanmaya dikkat edilmelidir.

SFSafariViewController, uygulama içi bir Safari deneyimi sunar. SFSafariViewController ile bir URL açtığınızda, kullanıcının uygulamanızın arayüzünde kalması dışında neredeyse gerçek Safari tarayıcısında açmak gibidir. Geçiş anahtarları için avantajı önemlidir: temel olarak Safari olduğu için, kullanıcının iCloud Keychain'i ve kaydedilmiş geçiş anahtarları erişilebilirdir. iOS 11+ sürümlerinde çerezlerin paylaşılmadığını unutmayın. Bu, kullanıcının siteniz için zaten bir geçiş anahtarı varsa, Safari'nin onu bulabileceği ve hatta kolay giriş için Conditional UI otomatik tamamlama sunabileceği anlamına gelir. SFSafariViewController daha az özelleştirilebilir (araç çubuğunu pek değiştiremezsiniz), ancak birçok güvenlik ve gizlilik özelliğini otomatik olarak yönetir. URL çubuğu, HTTPS için asma kilit simgesiyle birlikte gösterilir, bu da kullanıcılara doğru etki alanında olduklarına dair güven verir. Genel olarak, SFSafariViewController ham bir WKWebView'den daha güvenli kabul edilir ve uygulanması daha basittir (Apple bunu doğrudan bir eklenti (drop-in) olarak sunar). Ana ödünleşim, görünüm ve his üzerindeki kontrolün bir kısmından feragat etmenizdir. Bir kimlik doğrulama akışı için bu genellikle kabul edilebilirdir. Buradaki öncelik, SFSafariViewController'ın Safari'nin bağlamını kullanarak mükemmel bir şekilde sağladığı güvenlik ve giriş kolaylığıdır.

SFAuthenticationSession / ASWebAuthenticationSession – Bu sınıflar (ikincisi daha yeni, Swift dostu olan addır) OAuth veya OpenID Connect gibi giriş akışları için özel olarak oluşturulmuştur. Bir kullanıcının web sayfası üzerinden kimliğini doğrulamanız gerektiğinde (örneğin harici bir IdP'ye), iOS'ta önerilen seçim bu oturumlardır. Arka planda Safari tarayıcısını kullanmaları ve Safari ile çerezleri/depolamayı paylaşmaları bakımından SFSafariViewController'a çok benzerler. Temel fark, SFAuthenticationSession'ın (kullanıcı farkındalığı için) uygulamanın bir web sayfası kullanarak kimlik doğrulamak istediğini her zaman kullanıcıya sorması ve mevcutsa kullanıcının var olan Safari oturumunu otomatik olarak kullanmasıdır.

Bunun faydası sorunsuz bir SSO deneyimidir – kullanıcı Safari'deki sağlayıcıda zaten oturum açmışsa, bu oturum başka bir girişi önlemek için o çerezi kullanabilir. Geçiş anahtarları için bu önemlidir çünkü Safari/iCloud Keychain'de depolanan herhangi bir geçiş anahtarı kimlik bilgisinin burada da kullanılabileceği anlamına gelir. Apple'ın resmi yönergesi, bir giriş akışına benzeyen herhangi bir şey için ASWebAuthenticationSession kullanılmasıdır. Artıları, gelişmiş gizlilik (uygulamanız asla kimlik bilgilerini veya çerezleri görmez, Safari yönetir) ve yerleşik SSO desteğidir. Eksisi, kimlik doğrulama akışlarıyla sınırlı olmasıdır (uygulamanızda herhangi bir web içeriğini oluşturmak için bunu kullanmazsınız). Özetle, iOS'ta bir WebView yaklaşımı seçerseniz, ASWebAuthenticationSession güvenli olduğu, durumu Safari ile paylaştığı ve kimlik doğrulama için özel olarak oluşturulduğu için genellikle geçiş anahtarlarını uygulamak için en iyi seçimdir.

Kaç kişinin gerçekten passkeys kullandığını görün.

Adoption verilerini gör

Android'de WebView kararı, klasik WebView ile Chrome Custom Tabs arasındadır:

Android'de farklı WebView davranışlarını test etmek için WebView vs Chrome Custom Tabs uygulamasını öneririz.

Android WebView (android.webkit.WebView), etkinlik düzeninize (activity layout) web sayfaları gömmenizi sağlayan bir bileşendir. Size tam kontrol sağlaması bakımından WKWebView'e benzer: gezinmeyi (navigation) engelleyebilir, JavaScript enjekte edebilir, kullanıcı arayüzünü özelleştirebilirsiniz vb. Ayrıca uygulamanızın işlemi içinde çalışır. Geçiş anahtarları için bir WebView kullanmak, uygulamanızın web giriş sayfanızı yüklemesi ve bu sayfanın bir WebAuthn geçiş anahtarı seremonisi başlatabilmesi anlamına gelir. Modern Android WebView, WebAuthn'i destekler (cihazın WebView uygulamasının Android Sistem WebView veya Chrome bileşeni aracılığıyla güncel olması koşuluyla). Önemli bir husus: varsayılan olarak, bir Android WebView çerezleri veya saklanan kimlik bilgilerini kullanıcının Chrome tarayıcısıyla paylaşmaz. Dolayısıyla, WebView'de oluşturulan veya kullanılan herhangi bir geçiş anahtarı Chrome tarafından bilinmeyebilir ve bunun tersi de geçerlidir. Bu izolasyon güvenlik için iyi olabilir (uygulamanız tarayıcı çerezlerini okuyamaz), ancak Chrome'da zaten kimlik doğrulaması yapmışlarsa kullanıcıları tekrar giriş yapmaya zorlayabilir. Diğer bir sorun ise güvendir. Düz bir WebView, URL'yi veya SSL kilit simgesini göstermez, bu nedenle kullanıcıların kendilerini oltalama amaçlı yönlendirmemesi için uygulamanıza tamamen güvenmeleri gerekir. Google, potansiyel oltalama riskleri nedeniyle Google OAuth oturum açma işlemleri için WebView kullanımını bile yasaklamıştır. Performans açısından WebView'ler iyidir, ancak kullanıcının varsayılan tarayıcısını kullanmaktan daha yavaş veya bellek yoğun olabilirler, özellikle de ağır sayfalar yüklenirken.

Chrome Custom Tabs (CCT) hibrit bir yaklaşımdır. Uygulamanızın bir parçası gibi görünen Chrome tarafından oluşturulmuş bir sayfa açmanıza olanak tanır. Araç çubuğu rengini özelleştirebilir, bir uygulama logosu ekleyebilirsiniz vb., ancak içerik Chrome tarafından ayrı bir işlemde oluşturulur. Geçiş anahtarları için CCT'lerin çeşitli avantajları vardır: kullanıcının çerezlerini ve kimlik bilgilerini Chrome tarayıcısıyla paylaşırlar, yani kullanıcının Chrome (Google Password Manager) aracılığıyla kaydedilmiş bir geçiş anahtarı varsa, Custom Tab buna erişebilir. Kullanıcı ayrıca gerçek URL'yi ve güvenlik göstergelerini görecek ve bu da güven oluşturacaktır. Performans genellikle daha iyidir – Chrome, daha hızlı yükleme için arka planda "ısıtılabilir". Ve en önemlisi, güvenlik güçlüdür: temelde Chrome uygulaması olduğu için, Google Güvenli Tarama gibi özellikler oturumu korur ve uygulamanız sayfaya keyfi komut dosyaları enjekte edemez (belirli saldırıları önler).

Dezavantajı, kullanıcının Chrome'un (veya desteklenen bir tarayıcının) yüklü ve güncel olmasını gerektirmesidir. Android kullanıcılarının çoğu buna sahiptir, ancak bazı bölgelerdeki bazı cihazlarda bu bir sorun olabilir. Genel olarak, Android'de gömülü bir web yaklaşımı seçerseniz, iyi bir entegrasyon ve güvenlik dengesi sağladıkları için geçiş anahtarı akışlarında Chrome Custom Tabs önerilir. Aslında, bunlar kimlik doğrulama için varsayılan tarayıcıdan yararlanarak iOS'un SFSafariViewController/ASWebAuthSession'ına birçok yönden benzer.

(Bir Not: Apple'ın WKWebView ve SFSafariViewController karşılaştırması ile Android'in WebView ve CCT karşılaştırması birçok paralelliğe sahiptir. Hem Safari VC hem de Chrome Tabs tarayıcı durumunu paylaşır ve daha iyi güvenlik sağlar; WKWebView/Android WebView ise daha fazla kontrol verir ancak web içeriğini izole eder. Geçiş anahtarları için durumun (çerezler, kimlik bilgisi depoları) paylaşılması, geçiş anahtarına sorunsuz bir şekilde erişilebilmesi ve oluşturulabilmesi için genellikle arzu edilen durumdur.)

Hangi uygulama yaklaşımını seçerseniz seçin, geçiş anahtarı işlevselliğini etkinleştirmek için belirli teknik gereksinimlerin karşılanması gerekir. Bu bölüm bilinen (well-known) ilişkilendirme dosyalarını, iOS yetkilendirmelerini ve Android WebView yapılandırmasını kurma konusunda kapsamlı rehberlik sağlar.

Yönetilen Cihazlar Hakkında Not: Mobil Cihaz Yönetimi (MDM) politikalarının kimlik bilgisi depolamasını kontrol ettiği yönetilen cihazlarda geçiş anahtarı davranışı önemli ölçüde değişir. Yönetilen cihazlarda geçiş anahtarlarını test etmek için bkz. Yönetilen iOS ve Android Cihazlarda Geçiş Anahtarları.

Native ve Gömülü WebView akışları, uygulamanız ile web etki alanınız arasında kriptografik güven oluşturmak için ilişkilendirme dosyaları gerektirir. Sistem WebView (ASWebAuthenticationSession) ve Chrome Custom Tabs uygulama-site ilişkilendirmesi gerektirmez.

AASA dosyası, iOS uygulamanız ile web etki alanınız arasındaki bağlantıyı kurarak geçiş anahtarlarının her iki platformda da çalışmasını sağlar.

Dosya Konumu: https://yourdomain.com/.well-known/apple-app-site-association

Yapılandırma Gereksinimleri:

• Etki alanınızda /.well-known/apple-app-site-association adresinde barındırın
• Geçerli bir SSL sertifikasıyla HTTPS üzerinden sunun
• Content-Type: application/json
• .well-known yolunda yönlendirme (redirect) yok
• Uygulamanızın Team ID ve Bundle ID'sini ekleyin

Örnek AASA Dosyası:

{
    "webcredentials": {
        "apps": ["TEAMID123.com.example.app"]
    }
}

AASA Önbelleğe Alma ve Test Etme:

Apple, AASA dosyalarını bir CDN kullanarak agresif bir şekilde (24-48 saate kadar) önbelleğe alır ve bu da geliştirmeyi ve testi zorlaştırabilir. Geliştirme sırasında önbelleğe almayı atlamak için:

1. Test cihazınızda Geliştirici Modunu etkinleştirin
2. Xcode'da ilişkili etki alanınızın (associated domain) sonuna ?mode=developer ekleyin
3. Bu, iOS'u en son AASA dosyasını doğrudan sunucunuzdan getirmeye zorlar

⚠️ Önemli: Üretim (production) sürümlerinde ?mode=developer KULLANMAYIN. Bu parametre yalnızca geliştirme içindir; üretimde kullanılması, iOS'un AASA dosyanızı düzgün bir şekilde algılamasını engelleyerek geçiş anahtarı işlevselliğini bozar.

Doğrulama: Yapılandırmanızı doğrulamak için Apple'ın AASA Doğrulayıcısını kullanın.

Android, uygulamanız ile web siteniz arasındaki ilişkiyi doğrulamak için Digital Asset Links kullanır.

Dosya Konumu: https://yourdomain.com/.well-known/assetlinks.json

Yapılandırma Gereksinimleri:

• Etki alanınızda /.well-known/assetlinks.json adresinde barındırın
• Geçerli sertifika ile HTTPS üzerinden sunun
• Content-Type: application/json
• Uygulamanızın SHA256 parmak izini ekleyin (imzalama sertifikasından)

Örnek assetlinks.json Dosyası:

[
    {
        "relation": [
            "delegate_permission/common.handle_all_urls",
            "delegate_permission/common.get_login_creds"
        ],
        "target": {
            "namespace": "android_app",
            "package_name": "com.example.app",
            "sha256_cert_fingerprints": [
                "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
            ]
        }
    }
]

Doğrulama: Yapılandırmanızı oluşturmak ve doğrulamak için Google'ın Digital Asset Links Oluşturucusunu kullanın.

iOS uygulamaları, geçiş anahtarı işlevselliğine erişmek için uygun yetkilendirmeler gerektirir. Gereksinimler, uygulama yaklaşımınıza göre biraz farklılık gösterir.

Yetkilendirmeler (entitlements) dosyası (Flutter uygulamalarında genellikle Runner.entitlements veya native iOS projelerinde YourApp.entitlements olarak adlandırılır), Apple'ın sistemi tarafından verilen özel izinleri ve yetenekleri tanımlar. Geçiş anahtarları için bu dosya Associated Domains'i yapılandırır.

Dosya Konumu: Genellikle Xcode projenizde ios/Runner/Runner.entitlements adresinde bulunur

Native Uygulama ve Gömülü WebView, uygulamanızı web etki alanınızla bağlamak için Associated Domains yeteneğini gerektirir. Sistem WebView (ASWebAuthenticationSession) Safari bağlamında çalıştığı için bunu gerektirmez.

Xcode'da Kurulum:

1. Projenizi Xcode'da açın
2. Uygulama hedefinizi (app target) seçin
3. "Signing & Capabilities" sekmesine gidin
4. "+ Capability" tıklayın ve "Associated Domains" ekleyin
5. Etki alanınızı webcredentials: önekiyle ekleyin

Örnek Yapılandırma:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>webcredentials:yourdomain.com</string>
        <string>webcredentials:subdomain.yourdomain.com</string>
    </array>
</dict>
</plist>

Birden Fazla Etki Alanı: Uygulamanızın birden fazla etki alanıyla çalışması gerekiyorsa, Related Origin Requests (ROR) ihtiyacınız olabilir.

Android Gömülü WebView'ler, geçiş anahtarlarını iki farklı yaklaşımla destekler: daha yeni WebKit tabanlı yaklaşım (Bölüm 5.3.1) ve eski JavaScript köprüsü yaklaşımı (Bölüm 5.3.2). Sistem WebView (Chrome Custom Tabs) herhangi bir yapılandırma gerektirmez - kimlik bilgileri otomatik olarak çalışır.

Android, her iki uygulama yaklaşımını gösteren resmi WebView geçiş anahtarı örnekleri sunar.

Native geçiş anahtarı yönetimi ile modern WebKit entegrasyonu. Bu yaklaşım, özel köprü kodu gerektirmeden native WebAuthn desteği sağlar.

Resmi Örnek: Webkit WebView MainActivity

Gereksinimler:

• AndroidX WebKit 1.12.1 veya daha yenisi (1.14.0+ önerilir)
• Yapılandırılmış Digital Asset Links
• WebAuthn destekli WebView APK'sı (özellik algılama ile kontrol edin)
• Not: AndroidX Credentials kütüphanesi WebView WebAuthn için GEREKLİ DEĞİLDİR, yalnızca tamamen native uygulamalar içindir

Uygulama:

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
 
// Web Kimlik Doğrulamasının desteklenip desteklenmediğini kontrol edin
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) {
    // Web Kimlik Doğrulamasını Etkinleştirin
    WebSettingsCompat.setWebAuthenticationSupport(
        webView.settings,
        WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP
    )
 
    // JavaScript'i Etkinleştirin
    webView.settings.javaScriptEnabled = true
}

Önemli Noktalar:

• JavaScript köprüsüne gerek yok: WebAuthn, WebView'de native olarak çalışır
• Özellik algılama gerekli: Çalışma zamanında daima WebViewFeature.WEB_AUTHENTICATION kontrolünü yapın
• Conditional UI desteklenmez: mediation:"conditional" (giriş alanlarında geçiş anahtarı otomatik doldurma) Gömülü WebView'de çalışmaz
• Yedek strateji: Özellik mevcut değilse, bunun yerine Chrome Custom Tabs kullanın

Sürüm Notları:

• WebKit 1.12.1 veya daha yenisini kullanın (1.12.0'da bir çalışma zamanı kullanılabilirlik sorunu vardı)
• Özellik desteği kullanıcının WebView APK sürümüne bağlıdır - cihazdaki eski APK'lar bu özelliği göstermez

AndroidX WebKit 1.12.0'dan önce, Gömülü WebView'de native WebAuthn desteği yoktu. Bu eski yaklaşım, native WebView WebAuthn desteği olmayan cihazlar için geçiş anahtarlarını yönetmek üzere Web'den Native'e bir köprü kullanır.

Resmi Örnekler:

• PasskeyWebListener (Köprü İşleyicisi)
• JavaScript kodlama yardımcı programları

Ne Zaman Kullanılır: Eski Android sürümlerini veya eski WebView uygulamalarına sahip cihazları desteklerken.

Ekiplerin şunlardan birini yapması gerekiyordu:

1. Chrome Custom Tabs veya Auth Tab kullanmak (önerilir)
2. Özel bir JavaScript köprüsü oluşturmak

Ayrıntılı uygulama için bkz. Android'in Credential Manager WebView Entegrasyon kılavuzu. Ancak modern uygulamalar için native WebKit 1.12.1+ yaklaşımını kullanmanızı şiddetle tavsiye ederiz.

Öneri: AndroidX WebKit 1.12.1+ ile native WebAuthn desteği kullanın. Çalışma zamanında mevcut değilse, paylaşılan kimlik bilgileriyle mükemmel geçiş anahtarı desteği sağlayan Chrome Custom Tabs'e geri dönün.

Native uygulamalarda geçiş anahtarlarını uygularken, uygulamanız ile web etki alan(lar)ınız arasında güven oluşturmanız gerekir. Bu bölüm, tek etki alanlarını, birden fazla ilişkili etki alanını (ROR) nasıl yöneteceğinizi ve bilinen ilişkilendirme dosyalarınızın düzgün yapılandırıldığını nasıl doğrulayacağınızı kapsar.

Tek bir etki alanı (ör. kayak.com) kullanan uygulamalar için şunlara ihtiyacınız vardır:

• https://kayak.com/.well-known/apple-app-site-association adresinde iOS için bir AASA dosyası
• https://kayak.com/.well-known/assetlinks.json adresinde Android için bir assetlinks.json
• webcredentials:kayak.com ile yapılandırılmış Associated Domains yetkilendirmesi

Related Origins (ROR), tek bir geçiş anahtarı setinin birden fazla ilişkili etki alanında (ör. kayak.com, kayak.de, kayak.co.uk) çalışmasına olanak tanıyan bir WebAuthn özelliğidir. ROR, AASA veya assetlinks dosyalarını DEĞİL, ilişkili orijinleri tanımlamak için her sitedeki /.well-known/webauthn uç noktasını (endpoint) kullanır.

Önemli Noktalar:

• ROR yapılandırması: Her etki alanı, ilişkili orijinlerin listesiyle birlikte /.well-known/webauthn adresini barındırır
• Uygulama ilişkilendirme dosyaları (AASA/assetlinks): Yalnızca uygulamaları ilgili web sitelerine eşlemek için kullanılır
• iOS 18+ Gömülü WebView: Düzgün yapılandırıldığında ROR'u destekler
• Associated Domains yetkilendirmeleri: Uygulamanızın kimlik doğrulaması yapması gereken tüm etki alanlarını ekleyin

Yapılandırma Örneği:

Uygulamanız kayak.com ve kayak.de ile çalışıyorsa, her iki etki alanı da:

• Aynı Team ID ve Bundle ID'ye sahip kendi AASA dosyalarını barındırmalıdır
• Uygulamanızın Associated Domains yetkilendirmelerinde listelenmelidir
• Düzgün yapılandırılmış ve erişilebilir bilinen (well-known) dosyalara sahip olmalıdır

Canlıya geçmeden önce, bilinen dosyalarınızın düzgün yapılandırıldığını ve erişilebilir olduğunu doğrulayın. Apple ve Google, dosya erişilebilirliğini kontrol etmek için CDN tabanlı test URL'leri sağlar:

Bu Test URL'lerini Kullanma:

• Apple/Google'ın bilinen dosyalarınızı alıp alamayacağını doğrulamak için bağlantılara tıklayın
• Apple'ın ?nocache=1 parametresi, CDN önbelleğini atlayarak yeni bir alma işlemini zorlar
• Dosyalar bu URL'ler üzerinden erişilebilir değilse, geçiş anahtarı işlevselliği uygulamanızda çalışmaz
• Yukarıdaki URL kalıplarında kayak.com veya kayak.de yerine kendi etki alan(lar)ınızı yazın

Test Tuzağı: Tüm etki alanlarının düzgün yapılandırılmış bilinen dosyalara sahip olduğundan emin olun. Herhangi bir etki alanındaki eksik veya yanlış yapılandırılmış bir dosya, o etki alanı için geçiş anahtarı işlevselliğini bozabilir.

Daha Fazla Bilgi: Native Uygulamalarda WebAuthn Relying Party ID

Doğru uygulama yaklaşımını seçmek, uygulamanızın kimlik doğrulama mimarisine, OAuth gereksinimlerine ve oturum kontrolü ihtiyacına bağlıdır. İleriye dönük en iyi yolu belirlemek için bu karar ağacını kullanın.

Aşağıdaki akış şeması, uygulamanızın gereksinimlerine göre doğru uygulama yaklaşımını seçme konusunda size rehberlik eder:

Her yol için hızlı başvuru:

• OAuth tabanlı giriş mi? → Sistem WebView (ASWebAuthenticationSession / Chrome Custom Tabs)
• Web kimlik doğrulamasını native kabukta yeniden kullanmak mı? → Yapılandırmalı Gömülü WebView (WKWebView / Android WebView + WebKit 1.12.1+)
• Öncelikle native mi geliştiriliyor? → Native Uygulama (AuthenticationServices / Credential Manager)
• Yeniden kullanılacak mevcut web kimlik doğrulaması mı var? → Hızlı uygulama için Sistem WebView; aksi takdirde optimum UX için Native

Her yaklaşımın temel boyutlarda nasıl performans gösterdiği aşağıda verilmiştir:

Boyut Açıklamaları:

• Geçiş Anahtarları Oluşturma: Kullanıcıların bu yaklaşımla ne kadar kolay geçiş anahtarı oluşturabildiği
• Geçiş Anahtarları Kullanımı: Mevcut geçiş anahtarlarını kullanırken ki kimlik doğrulama deneyimi
• Geçiş Anahtarları Yönetimi: Kullanıcıların geçiş anahtarlarını nasıl görüntülediği, düzenlediği veya sildiği
• Teknik Karmaşıklık: Geliştirme çabası ve sürekli bakım
• OAuth Desteği: Yaklaşımın OAuth2/OIDC kimlik doğrulama akışlarını ne kadar iyi idare ettiği
• Kurulum Süresi: Tipik uygulama zaman çizelgesi

Önerilen: Sistem WebView

Uygulamanız OAuth2, OIDC veya sosyal giriş sağlayıcıları (Google, GitHub, Microsoft vb.) üzerinden kimlik doğruluyorsa, Sistem WebView en uygun seçimdir:

• iOS: ASWebAuthenticationSession OAuth akışları için amaca yönelik olarak oluşturulmuştur
• Android: Chrome Custom Tabs sorunsuz OAuth entegrasyonu sağlar
• Faydaları: Minimum native kod, otomatik kimlik bilgisi paylaşımı
• Uygulama: Web kimlik doğrulama sayfanıza WebAuthn ekleyin, ardından Sistem WebView aracılığıyla yükleyin

Örnek: kayak.com ve kayak.de gibi Seyahat uygulamaları kimlik doğrulama için OAuth kullanır. Sistem WebView, web kimlik doğrulama sayfaları aracılığıyla geçiş anahtarı desteği eklerken mevcut OAuth altyapılarını korumalarına olanak tanır.

Önerilen: Hibrit Yaklaşım

İlk OAuth kimlik doğrulaması için Sistem WebView'i kullanın, ardından kimlik doğrulama sonrası oturumlar için Gömülü WebView'i kullanın:

1. İlk Kimlik Doğrulama: Sistem WebView, OAuth + geçiş anahtarı girişini yönetir
2. Oturum Yönetimi: Çerez/oturum kontrolüne ihtiyaç duyduğunuz yerlerde doğrulanmış web içeriği için Gömülü WebView'e geçin
3. Teknik Kurulum: Hem Sistem hem de Gömülü WebView gereksinimlerini yapılandırın - Android için AndroidX WebKit 1.12.1+ sürümünün dahil edildiğinden emin olun (bkz. Bölüm 5)

Ne zaman kullanılır: OAuth aracılığıyla kimlik doğrulaması yapan ancak daha sonra doğrudan oturum manipülasyonunun gerekli olduğu doğrulanmış web içeriğini görüntülemesi gereken uygulamalar.

Önerilen: Native Uygulama

Sıfırdan mı geliştiriyorsunuz veya native ekranlarınız mı var? Tamamen native gidin:

• iOS: AuthenticationServices çerçevesini kullanın
• Android: Credential Manager API'yi kullanın
• Faydaları: En iyi UX, anında kimlik doğrulama, tam kontrol
• Benzersiz Avantaj: Uygulama başlangıcında otomatik geçiş anahtarı katmanı görüntülemek için preferImmediatelyAvailableCredentials kullanın - bu native uygulamalara özeldir ve en yüksek dönüşüm oranlarını sağlar
• SDK Önerisi: Üretim testinden geçmiş uç durum yönetimi ile geliştirmeyi hızlandırmak için Corbado SDK'larını (iOS, Android) kullanın

Yeni Uygulamalar İçin: İlk günden itibaren native giriş oluşturmanızı şiddetle tavsiye ederiz. Sizi en iyi UX için hazırlar ve gelecekteki WebView'den native'e geçişleri (migrations) önler.

Önerilen: Aşamalı Geçiş

Aşağıdaki diyagram, artımlı (incremental) geçiş yolunu göstermektedir:

Her aşama bir öncekinin üzerine inşa edilerek mevcut kullanıcıları kesintiye uğratmadan kademeli iyileştirmelere olanak tanır.

Ayrıntılı yapılandırma talimatları için Bölüm 5'e bakın.

Geçiş anahtarlarını native uygulamalarda test etmek yapılandırılmış, çok katmanlı bir yaklaşım gerektirir. Test piramidini izleyin: birim testleri (izole mantık), entegrasyon testleri (simülatörlerde/emülatörlerde WebAuthn seremonisi) ve sistem testleri (fiziksel cihazlarda uçtan uca).

Temel Test Kategorileri:

• Temel Yolculuklar: Kayıt, kimlik doğrulama, cihazlar arası akışlar, geçiş anahtarı silme
• Platform Kapsamı: iOS (native), Android (native), OS sürümlerinde web tarayıcıları
• Etki Alanı İlişkilendirmesi: AASA dosyalarının (iOS) ve Digital Asset Links'in (Android) erişilebilir olduğunu doğrulayın
• İptal Akışları: İşletim sistemi istemlerinde ve biyometrik ekranlarda kullanıcı iptalini test edin
• Hata Yönetimi: Arka uç arızaları, ağ zaman aşımları, kimlik bilgisi uyuşmazlıkları
• Uç Durumlar: Ekran kilidi devre dışı, iCloud/Google Password Manager devre dışı
• OAuth Akışları: Uçtan uca tam OAuth + geçiş anahtarı entegrasyonu
• Yönetilen Cihazlar: MDM kontrollü ortamlar (yönetilen cihaz testlerine bakın)
• Üçüncü Taraf Yöneticiler: 1Password, Bitwarden, Dashlane uyumluluğu
• Cihazlar Arası Kimlik Doğrulama: QR kodu akışları ve hibrit taşıma (transport) testi
• Gömülü WebView'e Özel: Gömülü WebView kullanılıyorsa, Android'de WebKit 1.12.1+ yapılandırmasını doğrulayın
• Üretim İzleme: Başarı oranları, hatalar ve gecikme için kontrol paneli

Otomasyon stratejileri, platformlara özgü tuzaklar ve eksiksiz bir uçuş öncesi kontrol listesi dahil olmak üzere kapsamlı test rehberliği için özel kılavuzumuza bakın: Native iOS ve Android Uygulamalarında Geçiş Anahtarı Akışlarını Test Etme.

Kullanıcılardan geleneksel başarılı girişten (parola, OAuth) sonra geçiş anahtarı oluşturmalarını istemeyi düşünün. Bu kademeli dönüşüm yaklaşımı:

• Mevcut kimlik doğrulama akışlarını bozmaz
• Kullanıcı reddederse zarif bir şekilde düşmeye (graceful degradation) izin verir
• Değişiklikleri zorlamadan zaman içinde geçiş anahtarı benimsenmesini artırır
• Her üç uygulama yaklaşımıyla da iyi çalışır

Örnek: Sistem WebView aracılığıyla OAuth girişinden sonra native bir istem gösterin: "Face ID ile daha hızlı girişi etkinleştirelim mi?" Kabul edilirse, Sistem WebView'de yüklenen web sayfası aracılığıyla geçiş anahtarı oluşturun.

Geçiş anahtarlarının nasıl uygulanacağına (Native Uygulama, Sistem WebView veya Gömülü WebView aracılığıyla) karar vermek, güvenliği, kullanıcı deneyimini ve geliştirme karmaşıklığını etkileyen çok önemli bir tasarım seçimidir. Herkese uyan tek bir cevap yoktur.

OAuth tabanlı uygulamalar için: Sistem WebView (ASWebAuthenticationSession, Chrome Custom Tabs) önerilen başlangıç noktasıdır. Mükemmel OAuth desteği, minimum uygulama çabası ve otomatik kimlik bilgisi paylaşımı sağlar.

Native öncelikli uygulamalar için: Mümkün olan en kısa sürede native kullanın. Native bir geçiş anahtarı girişi, uygulama başlangıcında otomatik geçiş anahtarı katmanını etkinleştiren preferImmediatelyAvailableCredentials gibi özel özelliklerle en sorunsuz UX'i sunar - bu WebView uygulamalarının sağlayamayacağı bir şeydir. iOS ve Android'in artık geçiş anahtarları için birinci sınıf destek sağlamasıyla birlikte, gerçek dünya başarıları yüksek benimsenme oranlarını göstermektedir. Araçlar (açık kaynaklı SDK'lar ve platform kütüphaneleri dahil), native entegrasyonu makul zaman dilimlerinde ulaşılabilir kılacak kadar olgunlaştı. Cihaz yönetimi politikalarına, cihazlar arası senkronizasyona ve üçüncü taraf sağlayıcılara dikkat etmeniz gerekirken, bu zorluklar dikkatli mühendislik ve testlerle yönetilebilir. Sonuç, kolaylığı ve hızı ile kullanıcıları memnun ederken güvenliği de önemli ölçüde artıran bir uygulama girişidir.

Gömülü WebView çerçeve gereksinimleri için: Gömülü WebView genellikle iki gerçek dünya senaryosunda kullanılır. Birincisi, OAuth tabanlı uygulamalar genellikle ilk giriş akışı için Sistem WebView'i kullanır, ardından oturum kontrolünün gerekli olduğu ayar ekranlarında geçiş anahtarı yönetim seçeneklerini oluşturmak için Gömülü WebView'e geçerler - bazı uygulamalar her iki akış için de Sistem WebView'i tutarak bunu basitleştirir. İkinci olarak, geçiş anahtarlarını benimsemeden önce kimlik doğrulama akışlarını WebView çerçevelerine zaten yerleştirmiş olan uygulamalar, tutarlılık için bu modeli kullanmaya devam eder. Native WebAuthn destekli Gömülü WebView (AndroidX WebKit 1.12.1+), yapılandırma ve kurulum (izinler, yetkilendirmeler, WebView ayarları) gerektirir ancak artık özel JavaScript köprüsü koduna ihtiyaç duymaz. Conditional UI'ın Gömülü WebView'de desteklenmediğini unutmayın. Mevcut gömülü kimlik doğrulama kalıplarını korurken veya kimlik doğrulama sonrası ekranlar için oturum/çerez kontrolüne ihtiyacınız olduğunda bu yaklaşımı seçin.

Nihayetinde, native uygulamalardaki geçiş anahtarları hem kullanıcı kolaylığı hem de güvenlik açısından ileriye doğru büyük bir sıçramayı temsil eder. İster Native, ister Sistem WebView veya Gömülü WebView aracılığıyla uygulansınlar, kullanıcılarınız için oltalama risklerini ve parola yönetimi yüklerini ortadan kaldırırlar. VicRoads'un native uygulama geçiş anahtarı entegrasyonu gibi gerçek dünya uygulamaları, otomatik geçiş anahtarı katmanları gibi özelliklerle doğru şekilde uygulandığında native öncelikli yaklaşımların en yüksek kullanıcı benimsemesini ve memnuniyetini sağladığını göstermektedir. Kullanıcı dostu kimlik doğrulama için en iyi uygulamaları takip ederek ve uygulamanızın mimarisine uygun uygulama yaklaşımını seçerek (yeni uygulamalar için native öncelikli, OAuth akışları için Sistem WebView veya mevcut gömülü kalıplar için Gömülü WebView) geçiş anahtarlarının vizyonunu gerçekten gerçekleştiren parolasız, biyometrik girişler sunabilirsiniz: herkes için basit, güvenli ve keyifli kimlik doğrulama.

Geçiş anahtarları native uygulamanızda çalışmıyorsa, uygulama yaklaşımına göre bu yaygın sorunları kontrol edin:

• Dosyalar geçerli bir sertifikayla HTTPS üzerinden sunuluyor
• Doğru MIME türü: application/json
• .well-known yolunda yönlendirme (redirect) yok
• iOS: Team ID ve Bundle ID AASA dosyasında tam olarak eşleşiyor
• Android: SHA256 parmak izi, assetlinks.json'daki imzalama sertifikanızla eşleşiyor
• Relying Party ID etki alanınızla eşleşiyor (protokol yok, bağlantı noktası (port) yok)
• RP ID'de sondaki eğik çizgiler (trailing slashes) yok
• WebAuthn orijini: https://your-domain.com (app:// değil)

• iOS: Xcode'da webcredentials:yourdomain.com ile Associated Domains yeteneği etkinleştirildi
• Android: Digital Asset Links AndroidManifest.xml dosyasında beyan edildi
• Kullanıcı ekran kilidini etkinleştirmiş (biyometrik veya PIN)
• Apple'ın AASA Doğrulayıcısı ve Google'ın Digital Asset Links aracıyla test edin
• Runner.entitlements dosyasının doğru ilişkili etki alanlarını (associated domains) içerdiğini doğrulayın

• iOS: ASWebAuthenticationSession (önerilir) veya SFSafariViewController kullanılıyor
• Android: Chrome Custom Tabs kullanılıyor (düz WebView değil)
• iOS: Gerekirse Associated Domains'in yapılandırıldığını doğrulayın
• Çerezlerin/kimlik bilgilerinin sistem tarayıcısıyla paylaşıldığını test edin
• Web kimlik doğrulama sayfasının uygun WebAuthn uygulamasına sahip olduğunu doğrulayın

• iOS: Uygun yetkilendirmelerle yapılandırıldı
• iOS: Associated Domains tüm ilgili etki alanlarını içeriyor
• iOS: AASA dosyasına erişilebilir ve düzgün biçimlendirilmiş
• iOS: Geliştirme sırasında ?mode=developer ile test edin (üretim için kaldırın)
• Android: AndroidX WebKit 1.12.1+ (veya daha yenisi) projeye dahil edildi
• Android: WebViewFeature.WEB_AUTHENTICATION için çalışma zamanı özellik kontrolü
• Android: setWebAuthenticationSupport(), WEB_AUTHENTICATION_SUPPORT_FOR_APP ile çağrıldı
• Android: WebView ayarlarında JavaScript etkin
• Android: Kullanıcının WebView APK sürümü WebAuthn özelliğini destekliyor (işletim sistemi sürümünü değil, özellik algılamasını kullanın)
• Conditional UI kullanılmıyor (Gömülü WebView'de desteklenmiyor)
• WebAuthn özelliği kullanılamıyorsa Chrome Custom Tabs'e geri dönüş

• Kullanıcının aktif olan varsayılan dışı bir kimlik bilgisi sağlayıcısı olup olmadığını kontrol edin (1Password, Bitwarden vb.)
• Sağlayıcının geçiş anahtarlarını desteklediğini doğrulayın (tüm parola yöneticileri desteklemez)
• Platform native kimlik bilgisi yöneticisi (iCloud Keychain, Google Password Manager) ile test edin

"NotAllowedError: The request is not allowed by the user agent or the platform in the current context"

• Genellikle şu anlama gelir: Eksik yetkilendirmeler (iOS) veya WebView özelliği mevcut değil/etkin değil (Android Gömülü WebView)
• Şunu kontrol edin: Associated Domains yapılandırması, AASA dosyası erişilebilirliği, WebKit sürümü, özellik algılama, setWebAuthenticationSupport() çağrısı

Geçiş anahtarı istemi görünmüyor

• Şu anlama gelebilir: AASA/assetlinks.json yüklenmiyor, yanlış WebView türü, önbelleğe alınmış AASA dosyası
• Şunu deneyin: İlişkilendirme dosyalarını doğrulayın, test için iOS'ta ?mode=developer kullanın, WebView türünü doğrulayın

Ayrıntılı hata ayıklama için, native uygulamalarda Relying Party ID'leri hakkındaki makalemize bakın.

Yaygın bir tuzak: kısıtlı erişime sahip hazırlık ortamları (IP beyaz listesi, yalnızca VPN) başarısız olacaktır çünkü Apple ve Google CDN'leri ilişkilendirme dosyalarınızı alabilmelidir.

• AASA/assetlinks dosyaları herkese açıktır (IP beyaz listesi yok, VPN gereksinimi yok)
• Apple CDN'in dosyanıza ulaşabildiğini doğrulayın: https://app-site-association.cdn-apple.com/a/v1/your-staging-domain.com?nocache=1
• Google'ın dosyanıza ulaşabildiğini doğrulayın: https://digitalassetlinks.googleapis.com/v1/statements:list/?source.web.site=https://your-staging-domain.com&relation=delegate_permission/common.handle_all_urls

Üretim rpID'sine sahip hazırlık (staging) alt alan adı:

Hazırlık ortamınız (ör. stg.login.example.com) rpID olarak üretim etki alanını (ör. example.com) kullanıyorsa, AASA araması hazırlık alt alan adınızda değil, rpID etki alanında gerçekleşir. Bu şu anlama gelir:

• Hazırlık uygulama Bundle ID'lerini üretim AASA dosyanıza ekleyin
• Hazırlık aşamasında oluşturulan geçiş anahtarlarının üretim giriş akışlarında görüneceğinin farkında olun (potansiyel karışıklık)

Örnek (bir AASA'yı paylaşan birden fazla ortam):

{
    "webcredentials": {
        "apps": [
            "TEAMID123.com.example.app",
            "TEAMID123.com.example.app.dev",
            "TEAMID123.com.example.app.stg",
            "TEAMID123.com.example.app.pre"
        ]
    }
}

Öneri: Ortamlar arasında kimlik bilgisi çakışmasını önlemek için hazırlık etki alanınızla eşleşen ayrı bir hazırlık rpID kullanın. Bu, hazırlık etki alanında herkese açık erişilebilir AASA dosyaları gerektirir.

?mode=developer açıklaması:

Associated Domains'deki ?mode=developer parametresi, Apple'ın CDN önbelleğini atlar ancak erişilebilirlik gereksinimini atlamaz. AASA dosyanıza cihazdan hala erişilebilmelidir (Apple'ın CDN'i üzerinden değil, doğrudan). Bu, AASA değişiklikleri üzerinde yinelenirken geliştirme sırasında yardımcı olur, ancak hazırlık sunucunuz IP beyaz listesindeyse yardımcı olmaz.

Corbado Native SDK'ları:

• iOS SDK (Swift)
• Android SDK (Kotlin)
• Flutter Paketi

Platform Belgeleri:

• Apple: Geçiş Anahtarlarını Destekleme
• Google: Credential Manager

Doğrulama Araçları:

• Apple AASA Doğrulayıcısı
• Google Digital Asset Links Oluşturucusu

Corbado Hakkında

Corbado, büyük ölçekte tüketici kimlik doğrulaması yöneten CIAM ekipleri için Passkey Intelligence Platform'tur. IDP loglarının ve genel analytics araçlarının göremediğini görmenizi sağlarız: hangi cihazların, OS sürümlerinin, tarayıcıların ve credential manager'ların passkey desteklediğini; kayıtların neden girişe dönüşmediğini; WebAuthn akışının nerede başarısız olduğunu; bir OS ya da tarayıcı güncellemesinin girişi sessizce ne zaman bozduğunu — hem de Okta, Auth0, Ping, Cognito veya kendi IDP'nizi değiştirmeden. İki ürün: Corbado Observe, passkey'ler ve diğer tüm giriş yöntemleri için observability sağlar. Corbado Connect, analytics entegre managed passkey'ler sunar (IDP'nizin yanında). VicRoads, Corbado ile 5M+ kullanıcı için passkey çalıştırıyor (%80+ passkey aktivasyonu). Bir Passkey uzmanıyla görüşün →

Seçim, kimlik doğrulama mimarinize bağlıdır. Uygulamanız OAuth2 veya OIDC kullanıyorsa, Sistem WebView (iOS'ta ASWebAuthenticationSession veya Android'de Chrome Custom Tabs) en az uygulama çabasını gerektirir ve ilişkilendirme dosyası kurulumu gerektirmez. Yeni native öncelikli uygulamalar için Native Uygulama üstün UX sağlarken, Gömülü WebView kimlik doğrulamayı halihazırda bir WebView çerçevesine gömen ve giriş yaptıktan sonra oturum veya çerez kontrolüne ihtiyaç duyan uygulamalara uygundur.

SFSafariViewController, Safari'nin motorundan yararlanır, SSL göstergeleriyle URL çubuğunu gösterir ve oltalama koruması sağlayarak kimlik doğrulama akışları için daha güvenilir hale getirir. WKWebView daha fazla UI özelleştirmesi sunar ancak Safari'den ayrı, izole edilmiş bir çerez deposuna sahiptir, geçiş anahtarlarını etkinleştirmek için Associated Domains yetkilendirmeleri ve bir AASA dosyası gerektirir ve URL çubuğunu görüntülemediğinden kullanıcı güven sinyallerini azaltır.

Chrome Custom Tabs çerezleri ve saklanan kimlik bilgilerini kullanıcının Chrome tarayıcısıyla paylaşır, yani Google Password Manager'da saklanan geçiş anahtarlarına kimlik doğrulama sırasında erişilebilir. Standart Android WebView izole bir çerez deposuna sahiptir, URL'yi veya SSL göstergelerini göstermez ve Google, oltalama riskleri nedeniyle Google hesabı girişleri için bunu açıkça yasaklamıştır.

Bir kullanıcının aktif sağlayıcısı olarak 1Password gibi üçüncü taraf bir kimlik bilgisi yöneticisi ayarlanmışsa, bu genellikle geçiş anahtarı oluşturma ve depolamayı engelleyerek platformun native kimlik bilgisi yöneticisine (iCloud Keychain veya Google Password Manager) göre öncelik alır. Bu, geçiş anahtarlarının platform keychain'i yerine üçüncü taraf uygulamada saklanabileceği ve cihazlar arası senkronizasyon ile geçiş anahtarı yönetim davranışını etkileyebileceği anlamına gelir.

MDM politikaları kimlik bilgisi senkronizasyonunu devre dışı bıraktığında, geçiş anahtarları cihaza bağlı hale gelir ve tipik tüketici senaryolarının aksine yeni bir cihaza dolaşamaz (roam). Kurumsal ortamları hedefleyen uygulamalar, bir kullanıcının yeni bir yönetilen cihaz aldığı durumları yönetmek için parola veya sihirli bağlantı (magic link) girişi gibi yedek (fallback) kimlik doğrulama mekanizmaları planlamalıdır.