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

Bu sayfada, geri yükleme anahtarının nasıl oluşturulacağı, geri yükleme anahtarıyla nasıl oturum açılacağı ve geri yükleme anahtarının nasıl silineceği 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 24220000 veya sonraki sürümleri ve androidx.credentials kitaplığının 1.5.0 veya sonraki sürümlerini çalıştıran cihazlarda kullanılabilir.

Ön koşullar

Geçiş anahtarları sunucusuna benzer bir bağlı taraf sunucusu oluşturun. Geçiş anahtarlarıyla kimlik doğrulamayı işlemek için ayarlanmış bir sunucunuz varsa yedek anahtarlar için aynı sunucu tarafı uygulamasını kullanın.

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.

Genel Bakış

  1. Geri yükleme anahtarı oluşturma: Geri yükleme anahtarı oluşturmak için aşağıdaki adımları tamamlayın:
    1. Kimlik Bilgisi Yöneticisi'ni örneklendirme: CredentialManager nesnesi oluşturun.
    2. Uygulama sunucusundan kimlik bilgisi oluşturma seçeneklerini alma: İstemci uygulamasına, uygulama sunucunuzdan geri yükleme anahtarını oluşturmak için gereken bilgileri gönderin.
    3. Geri yükleme anahtarı oluşturma: Kullanıcı uygulamanızda oturum açtıysa kullanıcının hesabı için geri yükleme anahtarı oluşturun.
    4. Kimlik bilgisi oluşturma yanıtını işleme: Kimlik bilgilerini istemci uygulamanızdan uygulama sunucunuza göndererek işleyin ve istisnaları ele alın.
  2. Geri yükleme anahtarıyla oturum açma: Geri yükleme anahtarıyla oturum açmak için aşağıdaki adımları uygulayın:
    1. Uygulama sunucusundan kimlik bilgisi alma seçeneklerini alma: İstemci uygulamasına, uygulama sunucunuzdan geri yükleme anahtarını almak için gereken bilgileri gönderin.
    2. Geri yükleme anahtarını alma: Kullanıcı yeni bir cihaz kurduğunda Kimlik Bilgisi Yöneticisi'nden geri yükleme anahtarını isteyin. Bu sayede kullanıcı, ek giriş yapmadan oturum açabilir.
    3. Kimlik bilgisi alma yanıtını işleme: Kullanıcının oturum açması için istemci uygulamasından uygulama sunucusuna geri yükleme anahtarını gönderin.
  3. Geri yükleme anahtarını silme.

Geri yükleme anahtarı oluşturma

Uygulamanız, etkin kullanıcılar için geri yükleme anahtarı oluşturulduğundan emin olmak amacıyla kullanıcının oturum açtığı tüm durumları kapsamalıdır. Aşağıdaki senaryolarda geri yükleme anahtarı 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 olduğu gibi).
  • Kullanıcı oturum açarken veya yeni bir hesap kayıt akışını tamamlarken

Performansı optimize etmek ve her girişte geri yükleme kimlik bilgisi oluşturma veya kontrol etme yükünden kaçınmak için yerel depolama alanında bir boolean işareti veya kimlik bilgisi oluşturma zaman damgası (ör. has_synced_restore_credential) ayarlayarak anahtarın daha önce oluşturulup oluşturulmadığını takip edin.

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

Uygulama sunucunuzda FIDO uyumlu bir kitaplık kullanarak istemci uygulamanıza geri yükleme kimlik bilgisini oluşturmak için gereken bilgileri (ör. kullanıcı, uygulama ve ek yapılandırma özellikleri hakkında bilgiler) gönderin. Sunucu tarafı uygulama hakkında daha fazla bilgi için Sunucu tarafı kılavuzu'na bakın.

Geri yükleme anahtarını oluşturma

Sunucu tarafından gönderilen ortak anahtar oluşturma seçeneklerini ayrıştırdıktan sonra bu seçenekleri bir CreateRestoreCredentialRequest nesnesine sarmalayarak ve CredentialManager nesnesiyle createCredential() yöntemini çağırarak bir geri yükleme anahtarı oluşturun.

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

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

      • true: (Önerilir) Bu değer, kullanıcının Google Yedekleme ve uçtan uca şifreleme (ör. ekran kilidi) ö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.

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.

Uygulamanızdaki ortak anahtarı, bağlı taraf sunucusuna gönderin. Bu ortak anahtar, geçiş anahtarı oluşturduğunuzda oluşturulan ortak anahtara benzer. Sunucuda geçiş anahtarı oluşturma işlemini gerçekleştiren kod, geri yükleme anahtarı oluşturma işlemini de gerçekleştirebilir. Sunucu tarafı uygulama hakkında daha fazla bilgi için geçiş anahtarlarıyla ilgili kılavuza bakın.

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

  • CreateRestoreCredentialDomException: requestJson geçersizse ve PublicKeyCredentialCreationOptionsJSON için WebAuthn biçimine uymuyorsa bu istisna oluşur.
  • E2eeUnavailableException: Bu istisna, isCloudBackupEnabled true olduğunda ancak kullanıcının cihazında veri yedekleme veya uçtan uca şifreleme (ör. ekran kilidi) olmadığında ortaya çıkar.
    Kimlik Bilgilerini Geri Yükleme özelliğinin her durumda oluşturulmasını sağlamak için E2eeUnavailableException değerini açıkça işlemeniz gerekir. Bunun için createCredential değerini isCloudBackupEnabled değeri true olarak ayarlanmış şekilde çağırın. E2eeUnavailableException hatası oluşursa hatayı yakalayın ve isCloudBackupEnabled parametresini false olarak ayarlayarak createCredential yöntemini tekrar çağırın.
  • IllegalArgumentException: Bu istisna, createRestoreRequest boşsa veya geçerli bir JSON değilse ya da WebAuthn spesifikasyonlarına uygun geçerli bir user.id içermiyorsa ortaya çıkar.

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

İstemci uygulamasına, sunucudan geri yükleme anahtarını almak için gereken seçenekleri gönderin. Bu adımla ilgili benzer geçiş anahtarı kılavuzu için Geçiş anahtarıyla oturum açma başlıklı makaleyi inceleyin. Sunucu tarafı uygulama hakkında daha fazla bilgi için sunucu tarafı kimlik doğrulama kılavuzuna bakın.

Geri yükleme anahtarını alma

Yeni cihazda geri yükleme anahtarını almak için CredentialManager nesnesinde getCredential() yöntemini çağırın.

Aşağıdaki senaryoların her ikisinde de geri yükleme anahtarını getirmeniz önerilir:

  • Uygulamanın cihazda ilk kez başlatılması sırasında. Bu senaryoda kimlik bilgilerinin geri yüklenmesi, uygulama verilerinin geri yüklenmesinden bağımsızdır.
  • Uygulama verilerini yedekleme ve geri yükleme özelliği etkinse uygulama verileri geri yüklendikten hemen sonra geri yükleme anahtarını alın. Uygulamanızın yedeklemesini yapılandırmak için BackupAgent kullanın ve onRestoreFinished geri çağırma işlevinde getCredential işlevini tamamladığınızdan emin olun. Yalnızca anahtar/değer yedeklemeleri için çağrıldığından onRestore yöntemini kullanmayın. onRestoreFinished ise her türlü yedekleme geri yükleme işlemi için güvenilir bir şekilde çağrılır. Bu sayede, kullanıcılar yeni cihazlarını ilk kez açtığında olası gecikmeler önlenir ve kullanıcıların uygulamanızı açmasını beklemeden uygulamayla etkileşim kurması sağlanır. Örneğin, uygulamanız yeni cihazda ilk kez açılmadan önce kullanıcıya bildirim gönderebilir. Bu, özellikle mesajlaşma veya iletişim uygulamaları için önemlidir.

Yeni bir BackupAgent oluşturursanız ve daha önce allowBackup="true" ile yedeklemeyi etkinleştirdiyseniz uygulamanızın manifest dosyasında android:fullBackupOnly="true" boole değerini ayarlayın. Bu sayede uygulamanızın yedekleme ve geri yükleme davranışı korunur.

// 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'leri, GetCredentialResponse türünde bir yanıt döndürür. Bu yanıtta yer alan kimlik bilgisi, ortak anahtarı barındıran RestoreCredential türündedir.

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

Uygulamadaki ortak anahtarı, kullanıcının oturum açması için kullanılabilecek olan bağlı taraf sunucusuna gönderin. Sunucu tarafında bu işlem, geçiş anahtarı kullanarak oturum açmaya benzer. Sunucuda geçiş anahtarlarıyla oturum açma işlemini gerçekleştiren kod, geri yükleme anahtarlarıyla oturum açma işlemlerini de gerçekleştirebilir. Geçiş anahtarlarının sunucu tarafı uygulaması hakkında daha fazla bilgi için Geçiş anahtarıyla oturum açma başlıklı makaleyi inceleyin.

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. Bu sayede, kullanıcı uygulamayı aynı cihazda bir sonraki açışında oturumu kapatılır ve tekrar oturum açması istenir.

Bir uygulamanın kaldırılması, kullanıcının oturumu kapatırkenki niyetine benzer şekilde, ilgili geri yükleme anahtarını o cihazdan silme niyeti olarak yorumlanır.

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.

Kullanıcı uygulamanızda oturumu kapattığında CredentialManager nesnesinde clearCredentialState() yöntemini çağırın.

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