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ğrulamayı işlemek için sunucunuz varsa geri yükleme 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.6.0-rc01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-rc01")
}

Groovy

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-rc01"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-rc01"
}

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ını oluşturun: 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 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 alın: İ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

Kullanıcı uygulamanızda kimliğini doğruladıktan sonra (oturum açtıktan hemen sonra veya oturum açmışsa sonraki uygulama başlatma sırasında) geri yükleme anahtarını oluşturun.

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çenekleri ayrıştırıldıktan sonra, bu seçenekleri bir CreateRestoreCredentialRequest nesnesine sarmalayıp createCredential() yöntemini CredentialManager nesnesiyle çağırarak bir geri yükleme anahtarı oluşturun.

val credentialManager = CredentialManager.create(context)

// On a successful authentication create a Restore Key
// Pass in the context and CreateRestoreCredentialRequest object
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 şu değerlere sahiptir:

      • true: (Önerilir) Bu değer, kullanıcının Google Yedekleme ve uçtan uca şifreleme (ör. ekran kilidi) etkinse yedekleme/geri yükleme anahtarlarının bulutta 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ızın ortak anahtarını, güvenen taraf sunucusuna gönderin. Bu ortak anahtar, şifre 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.

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

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 alma

Geri yükleme anahtarını sunucudan almak için gereken seçenekleri istemci uygulamasına gönderin. Bu adımla ilgili benzer geçiş anahtarı yönergeleri 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.

Geri yükleme anahtarını aşağıdaki senaryolarda alabilirsiniz:

  • (Önerilir) Uygulama verileri geri yüklendikten hemen sonra. Uygulamanızın yedeğini yapılandırmak ve uygulama verileri geri yüklendikten hemen sonra uygulamanın kimlik bilgilerinin geri yüklenmesini sağlamak için onRestore geri çağırma işlevi içinde getCredential işlevini tamamlamak üzere BackupAgent kullanın. Bu, kullanıcılar yeni cihazlarını ilk kez açtığında olası gecikmeleri önler ve kullanıcıların uygulamanızı açmalarını beklemeden etkileşimde bulunmalarını sağlar.
  • Uygulama cihazda ilk kez başlatıldığında

Kullanıcı yeni bir cihazda uygulamayı ilk kez açmadan önce bildirim göndermek için BackupAgent'nın onRestore geri çağırma işlevi içinde geri yükleme anahtarını getirin. Bu durum, özellikle mesajlaşma veya iletişim uygulamaları için geçerlidir.

// Fetch the Authentication JSON from server
val authenticationJson = fetchAuthenticationJson()

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

// The restore key can be fetched in two scenarios to
// 1. On the first launch of app on the device, fetch the Restore Key
// 2. In the onRestore callback (if the app implements the Backup Agent)
val response = credentialManager.getCredential(context, getRequest)

Kimlik bilgisi yöneticisi API'leri, GetCredentialResponse türünde bir yanıt döndürür. Bu yanıtta ortak anahtar bulunur.

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

Uygulamadan gelen ortak anahtarı, kullanıcının oturum açması için kullanılabilen 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 durumsuz olduğundan ve kullanıcı etkinliğinden haberdar 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)

// On user log-out, clear the restore key
val response = credentialManager.clearCredentialState(clearRequest)