Kimlik Bilgisi Yöneticisi ile kimlik bilgilerini geri yükleme özelliğini uygulama

Bu sayfada, geri yükleme anahtarı oluşturma, geri yükleme anahtarıyla oturum açma ve geri yükleme anahtarını silme işlemleri açıklanmaktadır.

Sürüm uyumluluğu

Kimlik Bilgisi Yöneticisi'nin Kimlik Bilgilerini Geri Yükleme özelliği, Android 9 (API düzeyi 28) ve sonraki sürümleri, Google Play Hizmetleri (GMS) temel sürümü 242200000 (24.22 sürümü) ve sonraki sürümleri ile androidx.credentials kitaplığının 1.5.0 ve sonraki sürümlerini çalıştıran cihazlarda kullanılabilir. Google Play Hizmetleri bulunmayan veya eski bir GMS sürümü yüklü cihazlarda, uygulamanızın standart oturum açma yöntemine sorunsuz bir şekilde geri dönmesi için CreateCredentialProviderConfigurationException ve GetCredentialProviderConfigurationException hatalarını yakalayın.

Ön koşullar

Geçiş anahtarları sunucusuna benzer bir WebAuthn bağlı taraf sunucusu yapılandırın. Geçiş anahtarlarıyla kimlik doğrulamayı işlemek için ayarlanmış bir sunucunuz varsa geri yükleme anahtarları için aynı WebAuthn kayıt ve onay uç noktalarını yeniden kullanabilirsiniz.

Bağımlılıklar

Uygulama modülünüzün build.gradle dosyasına aşağıdaki bağımlılıkları ekleyin:

Kotlin

dependencies {
    implementation("androidx.credentials:credentials:1.7.0-alpha02")
    implementation("androidx.credentials:credentials-play-services-auth:1.7.0-alpha02")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.7.0-alpha02"
    implementation "androidx.credentials:credentials-play-services-auth:1.7.0-alpha02"
}

Kimlik Bilgilerini Geri Yükleme özelliği, androidx.credentials kitaplığının 1.5.0 ve sonraki sürümlerinde kullanılabilir. Ancak mümkün olduğunda bağımlılıkların en son kararlı sürümlerini kullanmanız önerilir.

android:allowBackup, Kimlik Bilgilerini Geri Yükleme özelliğini nasıl etkiler?

android:allowBackup manifest özelliği, uygulama verilerinin yedeklenmesini kontrol eder. Bu özellik, Restore Credentials ile üç farklı şekilde etkileşime girer:

  • Anahtar aktarımını geri yükleme (allowBackup bağımsız): Google Play Hizmetleri, android:allowBackup değerinin true veya false olup olmadığına bakılmaksızın uçtan uca şifrelenmiş bulut yedekleme veya yerel cihazlar arası (D2D) aktarım kullanarak RestoreCredential anahtar çiftini aktarır. Cihazdan cihaza aktarımlarda geri yükleme anahtarı her zaman aktarılır. Aktarılmadığı tek durum, kullanıcının Android ayarlarında bulut yedeklemeyi devre dışı bıraktığı bulut yedekleme işlemidir.
  • BackupAgent uygulamasında arka planda geri yükleme (android:allowBackup="true" gerektirir): Kullanıcı yeni cihazda uygulamayı açmadan önce arka planda sessiz oturum açma (BackupAgent.onRestoreFinished()) işlemi yalnızca manifest dosyanızda android:allowBackup="true" ve android:backupAgent yapılandırıldığında çalışır. android:allowBackup="false" ise kullanıcı ana Activity uygulamanızı ilk kez başlattığında oturumu geri yükleyin. Geri yükleme işlemini daha sağlam hale getirmek için her iki yaklaşımı da uygulayabilirsiniz.
  • Android Studio Cloud Backup testi (android:allowBackup="true" gerektirir): Android Studio'nun Yedekleme ve Geri Yükleme aracında Bulut yedekleme türünü test etmek için android:allowBackup="true" gerekir. Cihazlar Arası test ise allowBackup'den bağımsız olarak çalışır.

Genel Bakış

Kimlik Bilgilerini Geri Yükleme, kullanıcının önceki ve yeni cihazlarında üç aşamalı bir yaşam döngüsü izler:

  1. Önceki cihazda geri yükleme anahtarı oluşturma: Kullanıcı oturum açtıktan sonra (veya kullanıcı zaten oturum açmışsa ve yerel depolama alanına geri yükleme anahtarı kaydedilmemişse uygulama başlatılırken) bağlı taraf sunucunuzdan oluşturma seçeneklerini alın ve credentialManager.createCredential() yöntemini çağırın.
  2. Yeni cihazda geri yükleme anahtarıyla oturum açma: Aktarılan RestoreCredential anahtarını iki aşamalı bir strateji kullanarak alın: İlk olarak arka planda senkronizasyonun ve push bildirimlerinin hemen devam etmesi için BackupAgent.onRestoreFinished() (android:allowBackup="true" olduğunda) arka planda, ikinci olarak ise ilk uygulama başlatıldığında başlatıcınızda Activity.onCreate() yedek olarak.
  3. Oturum kapatıldığında geri yükleme anahtarını silme: Kullanıcı oturumu kapattığında veya oturumu sunucu tarafından geçersiz kılındığında credentialManager.clearCredentialState() öğesini ClearCredentialStateRequest(ClearCredentialStateRequest.TYPE_CLEAR_RESTORE_CREDENTIAL) ile çağırın ve yerel senkronizasyon işaretinizi temizleyin.

Geri yükleme anahtarı oluşturma

Uygulamanız, etkin kullanıcıların geri yükleme anahtarı oluşturmasını sağlamak için kullanıcının oturum açtığı tüm durumları kapsamalıdır. Aşağıdaki senaryolarda geri yükleme anahtarını oluşturun:

  • Kullanıcı oturum açtıysa ve henüz bir geri yükleme anahtarı oluşturulmadıysa (ör. ana Activity için onCreate() yönteminde).
  • Kullanıcı oturum açarken veya yeni bir hesap kayıt akışını tamamlarken

Her uygulama başlatıldığında createCredential() çağrısı yapmamak için yerel depolama alanında has_synced_restore_credential gibi bir yerel senkronizasyon işareti saklayın. Dosya data_extraction_rules.xml içinde hariç tutulmadığı sürece bu işareti varsayılan olarak yedeklenen SharedPreferences veya DataStore içinde saklamayın. Aksi takdirde, otomatik yedekleme has_synced_restore_credential = true öğesini yeni cihaza kopyalar ve yeni cihazın kendi geri yükleme anahtarını oluşturmasını veya değiştirmesini engeller.

Kimlik Bilgisi Yöneticisi'ni örneklendirme

Bir CredentialManager nesnesini örneklendirmek için uygulamanızın etkinlik bağlamını kullanın.

// Use your app or activity context to instantiate a client instance of
// CredentialManager.
private val credentialManager = CredentialManager.create(context)

Uygulama sunucunuzdan kimlik bilgisi oluşturma seçeneklerini alma

İstemci uygulamanıza geri yükleme kimlik bilgisini oluşturmak için gereken PublicKeyCredentialCreationOptions JSON'u göndermek üzere uygulama sunucunuzda FIDO uyumlu bir kitaplık kullanın. Sunucu tarafı uygulama hakkında daha fazla bilgi için Sunucu tarafı kılavuzu'nu inceleyin.

Oluşturma seçenekleri JSON'u, geçiş anahtarı kaydıyla aynı yapıyı izler:

{
  "challenge": "<base64url-encoded challenge>",
  "rp": {
    "name": "<relying party name>",
    "id": "<relying party host name>"
  },
  "user": {
    "id": "<base64url-encoded user ID>",
    "name": "<user name>",
    "displayName": "<user display name>"
  },
  "pubKeyCredParams": [
    {
      "type": "public-key",
      "alg": -7
    }
  ],
  "attestation": "none",
  "excludeCredentials": [
    {
        "id": "<base64url-encoded credential ID to exclude>", 
        "type": "public-key"
    }
  ],
  "authenticatorSelection": {
    "requireResidentKey": true,
    "residentKey": "required",
    "userVerification": "required"
  }
}

Oluşturma seçenekleri JSON'unuzun aşağıdaki koşulları karşıladığından emin olun:

  • challenge ve user.id: Her iki değeri de doldurulmamış Base64URL dizeleri olarak kodlayın (+ yerine -, / yerine _ kullanın ve sondaki = karakterini kaldırın). Standart Base64 karakterleri veya ham tam sayı kimlikleri CreateRestoreCredentialDomException ya da IllegalArgumentException hatasına neden olur.
  • rp.id: Güvenen tarafınızın alan adına (ör. example.com) ayarlanır.
  • pubKeyCredParams: {"type": "public-key", "alg": -7} (ES256) ve {"type": "public-key", "alg": -257} (RS256) değerlerini ekleyin.

Geri yükleme anahtarını oluşturma

Sunucunuzdan ortak anahtar oluşturma seçenekleri JSON'unu aldıktan sonra JSON'u bir CreateRestoreCredentialRequest nesnesine sarmalayın ve CredentialManager nesnesinde createCredential() yöntemini çağırın.

// createRestoreRequest contains the details sent by the server 
val response = credentialManager.createCredential(context, createRestoreRequest)

Kodla ilgili önemli noktalar

  • CreateRestoreCredentialRequest nesnesi aşağıdaki alanları içerir:

    • requestJson: PublicKeyCredentialCreationOptionsJSON için Web Authentication API biçiminde uygulama sunucusu tarafından gönderilen kimlik bilgisi oluşturma seçenekleri.

    • isCloudBackupEnabled: Geri yükleme anahtarının buluta yedeklenip yedeklenmeyeceğini belirlemek için Boolean alanı. Varsayılan olarak bu işaret true şeklindedir. Bu alan aşağıdaki değerleri içerir:

      • true: (Önerilir) Bu değer, kullanıcının Google Yedekleme ve ekran kilidi gibi uçtan uca şifreleme özellikleri etkinse geri yükleme anahtarlarının buluta yedeklenmesini sağlar.
      • false: Bu değer, anahtarı bulutta değil yerel olarak kaydeder. Kullanıcı buluttan geri yüklemeyi seçerse anahtar yeni cihazda kullanılamaz ancak yerel kablo veya kablosuz cihazdan cihaza (D2D) kurulum sırasında aktarılır.

Kimlik bilgisi oluşturma yanıtını işleme

Credential Manager API, CreateRestoreCredentialResponse türünde bir yanıt döndürür. Bu yanıt, ortak anahtar kimlik bilgisi kayıt yanıtını JSON biçiminde içerir.

Ortak anahtarı kullanıcının hesabıyla birlikte doğrulamak ve depolamak için uygulamanızdan bağlı taraf sunucunuza response.registrationResponseJson gönderin, ardından yerel senkronizasyon işaretçinizi yerel depolama alanına kaydedin. Sunucu tarafı doğrulama hakkında daha fazla bilgi için geçiş anahtarlarıyla ilgili kılavuzu inceleyin.

Geri yükleme anahtarı oluşturma işlemi sırasında aşağıdaki istisnaları ele alın:

  • CreateRestoreCredentialDomException: requestJson geçersizse ve PublicKeyCredentialCreationOptionsJSON için WebAuthn biçimine uymuyorsa bu istisna gerçekleşir.
  • E2eeUnavailableException: Bu istisna, isCloudBackupEnabled true ise ancak kullanıcının cihazında veri yedekleme veya uçtan uca şifreleme (ör. ekran kilidi) yoksa ortaya çıkar.
    Bulut E2EE kullanılamadığında bile yerel cihazlar arası (D2D) aktarımlar için geri yükleme kimlik bilgilerinin oluşturulmasını sağlamak amacıyla E2eeUnavailableException hatasını yakalayın ve hemen CreateRestoreCredentialRequest(requestJson, isCloudBackupEnabled = false) ile createCredential() işlemini yeniden deneyin.
  • IllegalArgumentException: requestJson boşsa, geçerli bir JSON değilse veya WebAuthn spesifikasyonlarına uygun, geçerli bir Base64URL kodlu user.id içermiyorsa bu istisna oluşur.

Geri yükleme anahtarıyla oturum açma

Cihaz kurulumu sırasında kullanıcının oturumunu arka planda açmak için Kimlik Bilgilerini Geri Yükleme özelliğini kullanın.

Uygulama sunucusundan kimlik bilgisi alma seçeneklerini alma

Yeni cihazda getCredential() yöntemini çağırmadan önce uygulama sunucunuzdan bir WebAuthn PublicKeyCredentialRequestOptions JSON sorgusu isteyin. Yeni cihazdaki uygulama, hangi kullanıcının oturum açtığını henüz bilmediğinden bu uç noktanın kimliği doğrulanmamış (kullanıcısız keşif) olması gerekir. İlgili sunucu kılavuzu için Geçiş anahtarıyla oturum açma ve sunucu tarafı kimlik doğrulama kılavuzuna bakın.

Alma seçenekleri JSON'u aşağıdaki yapıya sahiptir:

{
  "challenge": "<your app challenge>",
  "allowCredentials": [],
  "rpId": "<your app server domain>"
}

Sunucunuzda alma seçenekleri JSON'unu aşağıdaki gibi yapılandırın:

  • allowCredentials: Kullanıcının hesabı geri yükleme işleminden önce bilinmediği için bu alanı atlayın veya boş bir dizi ([]) iletin. getCredential() döndükten sonra sunucunuz, kullanıcıyı response.userHandle alanından (oluşturma sırasında kaydedilen user.id ile eşleşir) tanımlar ve id (credentialId) ile ortak anahtarı arar.
  • userVerification: "discouraged" (veya "preferred") olarak ayarlayın. Kimlik Bilgilerini Geri Yükleme, biyometrik veya ekran kilidi kullanıcı arayüzü olmadan sessizce çalıştığı için Android, "required" değerini "discouraged" olarak geçersiz kılar ve sunucunuza döndürülen kimlik doğrulayıcı verilerinde Kullanıcı Doğrulandı (uv) işareti false olarak ayarlanır. WebAuthn sunucu doğrulayıcınızı, anahtar geri yükleme onayları için uv = false değerini kabul edecek şekilde yapılandırın.

Geri yükleme anahtarını alma

Yeni cihazda geri yükleme anahtarını almak için sunucunun requestJson anahtarını GetCredentialRequest içindeki bir GetRestoreCredentialOption ile sarmalayın ve CredentialManager nesnesinde getCredential() yöntemini çağırın.

Kullanıcıların, arka planda uygulama verilerini geri yükleme işlemi çalışsa da çalışmasa da oturum açabilmesi için iki katmanlı bir geri yükleme stratejisi uygulayın:

  • 1. Katman (BackupAgent.onRestoreFinished() içinde arka planda geri yükleme): Uygulama verilerini yedekleme etkinse (android:allowBackup="true") BackupAgent alt sınıfını oluşturun ve onRestoreFinished() yöntemini geçersiz kılın (yalnızca eski anahtar/değer yedeklemeleri için çağrılan onRestore() yöntemini kullanmayın). onRestoreFinished() senkronize, getCredential() ise Kotlin suspend işlevi olduğundan runBlocking(Dispatchers.IO) kullanarak çağrıyı bağlayın. Geri yükleme anahtarı olmadığında NoCredentialException hatasını sessizce yakalayın.
  • 2. Katman (Başlatıcıda ön plan yedek Activity.onCreate()): Yerel oturumun olmadığı ilk uygulama başlatma işleminde, giriş ekranınızı göstermeden önce lifecycleScope içinden getCredential() yöntemini çağırın. Bu, android:allowBackup="false" içeren uygulamaları işler ve onRestoreFinished() çalıştırıldığında cihaz çevrimdışıysa kurtarır.

android:allowBackup="true" ile Otomatik Yedekleme'yi kullanan bir uygulamaya yeni bir BackupAgent eklerseniz AndroidManifest.xml içindeki <application> öğesinde android:fullBackupOnly="true" değerini de ayarlayın. Böylece Android, eski anahtar/değer yedeklemesine geçmek yerine Otomatik Yedekleme'yi kullanmaya devam eder.

// Fetch the options required to get the restore key
val authenticationJson = fetchAuthenticationJson()

// Create the GetRestoreCredentialRequest object
val options = GetRestoreCredentialOption(authenticationJson)
val getRequest = GetCredentialRequest(listOf(options))

val response = credentialManager.getCredential(context, getRequest)

// Type-check and extract the restore credential
val credential = response.credential as RestoreCredential

Credential Manager API, credential özelliği authenticationResponseJson içeren bir RestoreCredential (PublicKeyCredential değil) olan bir GetCredentialResponse döndürür.

Oturum açma yanıtını işleme

Kriptografik onayı doğrulamak ve kullanıcı için yeni bir oturum jetonu oluşturmak üzere uygulamadan güvenen taraf sunucunuza restoreCredential.authenticationResponseJson gönderin. Sunucu tarafı doğrulama ayrıntıları için Geçiş anahtarıyla oturum açma başlıklı makaleyi inceleyin.

Geri yükleme anahtarları için arka uç depolama alanınızı ve yaşam döngüsü politikalarınızı tasarlarken aşağıdaki yönergeleri uygulayın:

  • Geri yükleme anahtarlarını kullanıcı geçiş anahtarlarından ayırın: Veritabanınızdaki geri yükleme anahtarlarını etiketleyerek kullanıcılara yönelik geçiş anahtarı yönetim ekranlarından gizleyin ve kullanıcı doğrulama (uv = true) kontrollerinden muaf tutun.
  • Kullanıcı başına birden fazla etkin cihazı destekleme: Bir kullanıcının birden fazla cihazı (ör. telefon ve tablet) olabilir. Tek bir satırın üzerine yazmak yerine kullanıcı hesabı başına birden fazla etkin geri yükleme anahtarına (ör. cihaz veya yükleme kimliğine göre anahtarlanmış) izin verin.
  • Uygun bir TTL ayarlayın ve artık anahtarları temizleyin: Bir uygulamayı kaldırmak veya uygulama verilerini temizlemek, sunucunuza bildirimde bulunmadan yerel geri yükleme anahtarını siler. Geri yükleme anahtarlarını, cihaz yükseltme pencereleri boyunca (kullanıcı aktarımdan sonra eski cihazda oturumu kapatsa bile) saklayın ve etkin olmama TTL'sine veya kullanıcı başına anahtar sınırlarına göre eski anahtarları silin.

Geri yükleme anahtarını silme

Kimlik Bilgisi Yöneticisi durum bilgisi içermez ve kullanıcı etkinliğinden haberdar değildir. Bu nedenle, kullanım sonrasında geri yükleme anahtarlarını otomatik olarak silmez. Bir geri yükleme anahtarını silmek için clearCredentialState() yöntemini çağırın. Güvenlik için, kullanıcı oturumu her kapattığında anahtarı silin. Böylece, uygulama bir sonraki başlatıldığında kullanıcının oturumu sessizce yeniden açılmaz.

Geri yükleme anahtarları yalnızca aşağıdaki durumlarda kaldırılır:

  • Sistem düzeyindeki işlemler: Kullanıcılar uygulamayı kaldırır veya verilerini temizler.
  • Uygulama düzeyinde çağrılar: Uygulamanızın kodunda kullanıcı oturumunu kapatma işlemini gerçekleştirirken clearCredentialState() yöntemini çağırarak anahtarı programatik olarak silin.

Varsayılan ClearCredentialStateRequest() yalnızca standart oturum durumunu temizlediği ve geri yükleme anahtarını olduğu gibi bıraktığı için oturum kapatıldığında çift temizleme işlemi gerçekleştirin:

  1. Etkin kimlik bilgisi sağlayıcı oturum durumunu temizlemek için credentialManager.clearCredentialState(ClearCredentialStateRequest()) komutunu çağırın.
  2. Depolanan RestoreCredential değerini silmek için credentialManager.clearCredentialState() yöntemini ClearCredentialStateRequest(ClearCredentialStateRequest.TYPE_CLEAR_RESTORE_CREDENTIAL) ile çağırın.
  3. Yerel depolama alanından yerel has_synced_restore_credential işaretçinizi silin.
// Create a ClearCredentialStateRequest object
val clearRequest = ClearCredentialStateRequest(TYPE_CLEAR_RESTORE_CREDENTIAL)

// When the user logs out, delete the restore key
val response = credentialManager.clearCredentialState(clearRequest)

Sonraki adımlar