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ı 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 ve sonraki sürümlerin yüklü olduğu cihazlarda, Google Play Hizmetleri (GMS) çekirdek sürümü 24220000 veya sonraki sürümlerde ve androidx.credentials kitaplığının 1.5.0 veya sonraki sürümlerinde çalışır.

Ön koşullar

Geçiş anahtarları için kullanılan sunucuya benzer bir bağlı taraf sunucusu ayarlayın. Geçiş anahtarlarıyla kimlik doğrulama işlemini gerçekleştirmek için sunucunuz zaten ayarlanmışsa geri yükleme anahtarları için aynı sunucu tarafı uygulamayı kullanın.

Bağımlılıklar

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

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

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ümlerinin kullanılması ö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öneticisini başlatma: CredentialManager nesnesi oluşturun.
   2. Uygulama sunucusundan kimlik bilgisi oluşturma seçeneklerini alma: İstemci uygulamasına, uygulama sunucunuzdan geri yükleme anahtarı oluşturmak için gereken ayrıntıları gönderin.
   3. Geri yükleme anahtarı oluşturma: Kullanıcı uygulamanızda oturum açtıysa kullanıcının hesabı için bir geri yükleme anahtarı oluşturun.
   4. Kimlik bilgisi oluşturma yanıtını işleme: Kimlik bilgilerini işlenmek üzere istemci uygulamanızdan uygulama sunucunuza gönderin ve tüm istisnaları işleyin.
2. Geri yükleme anahtarıyla oturum açma: Geri yükleme anahtarıyla oturum açmak için aşağıdaki adımları tamamlayın:
   1. Uygulama sunucusundan kimlik bilgisi alma seçeneklerini alma: İstemci uygulamasına, geri yükleme anahtarını uygulama sunucunuzdan almak için gereken ayrıntıları gönderin.
   2. Geri yükleme anahtarını alma: Kullanıcı yeni bir cihaz kurduğunda Kimlik Bilgileri 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ı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ı oluşturun:

• Kullanıcı oturum açtıysa ve geri yükleme anahtarı henüz oluşturulmadıysa (ör. onCreate yöntemiyle Activity için).
• Kullanıcı oturum açtığında veya yeni hesap kaydı akışını tamamladığında.

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

Kimlik Bilgisi Yöneticisi'ni başlatma

CredentialManager nesnesi oluşturmak 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 kimliği 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ı rehberliğe 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 sarmalayıp 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: Uygulama sunucusu tarafından Web Authentication API biçiminde PublicKeyCredentialCreationOptionsJSON için gönderilen kimlik bilgisi oluşturma seçenekleri.

  • isCloudBackupEnabled: Geri yükleme anahtarının bulutta yedeklenip yedeklenmeyeceğini belirleyen Boolean alanı. Bu işaret varsayılan olarak true'dır. Bu alan aşağıdaki değerlere sahiptir:

    • true: (Önerilir) Bu değer, kullanıcının Google Yedekleme'si varsa ve uçtan uca şifreleme (ör. ekran kilidi) 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, JSON biçiminde ortak anahtar kimlik bilgisi kayıt yanıtını içerir.

Uygulamanızın ortak anahtarını, güvenen taraf sunucusuna gönderin. Bu ortak anahtar, geçiş anahtarı oluşturduğunuzda oluşturulan ortak anahtara benzer. Sunucuda geçiş anahtarı oluşturmayı işleyen kod, geri yükleme anahtarı oluşturmayı da işleyebilir. Sunucu tarafı uygulama hakkında daha fazla bilgi için geçiş anahtarlarıyla ilgili kılavuza bakın.

Anahtar oluşturma işlemini geri yükleme sırasında aşağıdaki istisnaları ele alın:

• CreateRestoreCredentialDomException: Bu istisna, requestJson geçersizse ve PublicKeyCredentialCreationOptionsJSON için WebAuthn biçimine uymuyorsa oluşur.
• E2eeUnavailableException: Bu istisna, isCloudBackupEnabled true ise ancak kullanıcının cihazında ekran kilidi gibi veri yedekleme veya uçtan uca şifreleme yoksa oluşur.
  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. Bunu, createCredential işlevini isCloudBackupEnabled değeri true olarak ayarlanmış şekilde çağırarak yapabilirsiniz. E2eeUnavailableException atılırsa isCloudBackupEnabled, false olarak ayarlanmışken E2eeUnavailableException'ı yakalayıp createCredential'ı tekrar arayın.
• IllegalArgumentException: Bu istisna, createRestoreRequest boşsa veya geçerli bir JSON değilse ya da WebAuthn özelliklerine uygun geçerli bir user.id içermiyorsa oluşur.

Geri yükleme anahtarıyla oturum açma

Cihaz kurulumu sırasında kullanıcıyı sessizce oturum açmak için Kimlik Bilgilerini Geri Yükle'yi kullanın.

Uygulama sunucusundan kimlik bilgisi alma seçeneklerini edinme

Geri yükleme anahtarını sunucudan almak için gereken seçenekleri istemci uygulamasına gönderin. Bu adım için benzer geçiş anahtarı yönergelerini Geçiş anahtarıyla oturum açma başlıklı makalede bulabilirsiniz. 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 getCredential() yöntemini CredentialManager nesnesinde çağırın.

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

• Uygulama cihazda ilk kez başlatıldığında Bu senaryoda kimlik bilgisinin geri yüklenmesi, uygulama verilerinin geri yüklenmesinden bağımsızdır.
• Uygulama verilerinin yedeklenmesi ve geri yüklenmesi etkinse uygulama verileri geri yüklendikten hemen sonra geri yükleme anahtarını alın. Uygulamanızın yedeğini yapılandırmak için BackupAgent öğesini kullanın ve getCredential işlevini onRestoreFinished geri çağırma işlevi içinde 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 uygulamanızı açmalarını beklemeden uygulamayla etkileşime geçebilir. Örneğin, bu sayede uygulamanız, kullanıcı yeni cihazda uygulamayı ilk kez açmadan önce kullanıcıya bildirim gönderebilir. Bu özellik, özellikle mesajlaşma veya iletişim uygulamaları için önemlidir.

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

Kimlik bilgisi yöneticisi API'leri, GetCredentialResponse türünde bir yanıt döndürür. Bu yanıtta yer alan kimlik bilgisi, ortak anahtarı içeren RestoreCredential türündedir.

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

Uygulamadan ortak anahtarı, kullanıcının oturum açması için kullanılabilecek olan güvenen 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çmayı işleyen kod, geri yükleme anahtarlarıyla oturum açmayı da işleyebilir. Geçiş anahtarları için sunucu tarafı uygulama hakkında daha fazla bilgi edinmek istiyorsanız Geçiş anahtarıyla oturum açma başlıklı makaleyi inceleyin.

Geri yükleme anahtarını silme

Kimlik Bilgisi Yöneticisi durum bilgisiz olduğundan ve kullanıcı etkinliğinin farkında olmadığından, geri yükleme anahtarlarını kullanımdan sonra otomatik olarak silmez. Geri yükleme anahtarını silmek için clearCredentialState() yöntemini çağırın. Güvenlik için, kullanıcı her oturumu kapattığında anahtarı silin. Bu işlem, kullanıcının uygulamayı aynı cihazda bir sonraki açışında oturumunun kapatılmasını ve tekrar oturum açmasının istenmesini sağlar.

Bir uygulamanın kaldırılması, kullanıcının oturumu kapattığındaki amacına benzer şekilde, ilgili geri yükleme anahtarının cihazdan silinmesi olarak yorumlanır.

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

• Sistem düzeyinde işlemler: Kullanıcılar uygulamayı kaldırır veya verilerini temizler.
• Uygulama düzeyinde çağrılar: Uygulamanızın kodunda kullanıcı oturum kapatma işlemi gerçekleştirilirken clearCredentialState() çağrısı yaparak anahtarı programatik olarak silin.

Kullanıcı uygulamanızın oturumunu 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)