Kimlik Bilgisi Yöneticisi'ni Google ile oturum açma özelliğiyle entegre etme

Google ile oturum açma, kullanıcı kimlik doğrulamasını Android uygulamanızla hızlı bir şekilde entegre etmenize yardımcı olur. Kullanıcılar uygulamanızda oturum açmak, izin vermek ve profil bilgilerini uygulamanızla güvenli bir şekilde paylaşmak için Google Hesaplarını kullanabilirler. Android'in Kimlik Bilgisi Yöneticisi Jetpack kitaplığı, bu entegrasyonu sorunsuz hale getirerek Android cihazlarda tek bir API kullanarak tutarlı bir deneyim sunar.

Bu doküman, Android uygulamalarında Google ile oturum açma özelliğini uygulama, Google ile oturum açma düğme kullanıcı arayüzünü ayarlama ve uygulamaya göre optimize edilmiş tek dokunuşla kaydolma ve oturum açma deneyimlerini yapılandırma konusunda size yol gösterir. Cihazların sorunsuz bir şekilde taşınması için Google ile Oturum Açma özelliği otomatik oturum açmayı destekler. Android, iOS ve web yüzeylerindeki platformlar arası yapısı ise uygulamanıza herhangi bir cihazda oturum açma erişimi sağlamanıza yardımcı olur.

Google ile oturum açma özelliğini kurmak için şu iki temel adımı uygulayın:

Kimlik Bilgisi Yöneticisi alt sayfa kullanıcı arayüzü için Google ile oturum açma seçeneğini yapılandırın. Bu ayar, kullanıcıdan otomatik olarak oturum açmasını isteyecek şekilde yapılandırılabilir. Geçiş anahtarları veya şifreler uyguladıysanız ilgili tüm kimlik bilgisi türlerini aynı anda isteyebilirsiniz. Böylece kullanıcı, daha önce oturum açmak için kullandığı seçeneği hatırlamak zorunda kalmaz.

Kimlik Bilgisi Yöneticisi alt sayfası
Şekil 1. Kimlik Bilgisi Yöneticisi alt sayfası kimlik bilgisi seçimi kullanıcı arayüzü

Uygulamanızın kullanıcı arayüzüne Google ile oturum aç düğmesini ekleyin. Google ile oturum aç düğmesi, kullanıcıların Android uygulamalarına kaydolmak veya oturum açmak için mevcut Google Hesaplarını kullanmaları için kolay bir yol sunar. Kullanıcılar alt sayfa kullanıcı arayüzünü kapatırsa veya kaydolmak ve oturum açmak için açıkça Google Hesaplarını kullanmak isterse Google ile oturum aç düğmesini tıklar. Geliştiriciler bu sayede ilk katılım sürecini kolaylaştırır ve kayıt sırasında daha az sorunla karşılaşmış olurlar.

Google ile oturum açma akışını gösteren animasyon
Şekil 2. Kimlik Bilgisi Yöneticisi Google ile oturum aç düğme kullanıcı arayüzü

Bu dokümanda, Google Kimliği yardımcı kitaplığını kullanarak Google ile Oturum Aç düğmesinin ve alt sayfa iletişim kutusunun Credential Manager API'siyle nasıl entegre edileceği açıklanmaktadır.

Google API'leri konsol projenizi ayarlayın

  1. Projenizi API Konsolu'nda açın veya projeniz yoksa bir proje oluşturun.
  2. OAuth izin ekranı sayfasında tüm bilgilerin eksiksiz ve doğru olduğundan emin olun.
    1. Uygulamanıza doğru Uygulama Adı, Uygulama Logosu ve Uygulama Ana Sayfası'nın atandığından emin olun. Bu değerler, kayıt sırasında Google ile oturum açma izin ekranında ve Üçüncü taraf uygulamaları ve hizmetleri ekranında kullanıcılara sunulur.
    2. Uygulamanızın gizlilik politikasının ve hizmet şartlarının URL'lerini belirttiğinizden emin olun.
  3. Kimlik bilgileriniz (Kimlik Bilgileri) sayfasında, uygulamanız için bir Android istemci kimliğiniz yoksa oluşturun. Uygulamanızın paket adını ve SHA-1 imzasını belirtmeniz gerekir.
    1. Kimlik bilgileri sayfasına gidin.
    2. Kimlik bilgisi oluştur > OAuth istemci kimliği'ni tıklayın.
    3. Android uygulama türünü seçin.
  4. Kimlik Bilgileri sayfasında henüz oluşturmadıysanız yeni bir "Web uygulaması" istemci kimliği oluşturun. "Yetkilendirilmiş JavaScript Kaynakları" ve "Yetkilendirilmiş yönlendirme URI'leri" alanlarını şimdilik yoksayabilirsiniz. Bu istemci kimliği, Google'ın kimlik doğrulama hizmetleriyle iletişim kurduğunda arka uç sunucunuzu tanımlamak için kullanılır.
    1. Kimlik bilgileri sayfasına gidin.
    2. Kimlik bilgisi oluştur > OAuth istemci kimliği'ni tıklayın.
    3. Web uygulaması türünü seçin.

Bağımlılıkları bildirme

Modülünüzün build.gradle dosyasında, Kimlik Bilgisi Yöneticisi'nin en son sürümünü kullanarak bağımlılıkları tanımlayın:

dependencies {
  // ... other dependencies

  implementation "androidx.credentials:credentials:<latest version>"
  implementation "androidx.credentials:credentials-play-services-auth:<latest version>"
  implementation "com.google.android.libraries.identity.googleid:googleid:<latest version>"
}

Google ile oturum açma isteği örneklendirme

Uygulamaya başlamak için bir Google oturum açma isteği başlatın. Kullanıcının Google Kimliği Jetonunu almak için GetGoogleIdOption kullanın.

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(WEB_CLIENT_ID)
  .setAutoSelectEnabled(true)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Öncelikle, setFilterByAuthorizedAccounts parametresi true olarak ayarlanmış API'yi çağırarak kullanıcının daha önce uygulamanızda oturum açmak için kullanılmış hesapları olup olmadığını kontrol edin. Kullanıcılar, oturum açmak için mevcut hesaplar arasından seçim yapabilir.

Yetkili Google Hesabı yoksa kullanıcıdan kullanılabilir hesaplarından herhangi biriyle kaydolması istenir. Bunun için API'yi tekrar çağırıp setFilterByAuthorizedAccounts değerini false olarak ayarlayarak kullanıcıdan işlem yapmasını isteyin. Kaydolma hakkında daha fazla bilgi edinin.

Geri gelen kullanıcılar için otomatik oturum açmayı etkinleştir (önerilir)

Geliştiriciler, tek hesaplarıyla kaydolan kullanıcılar için otomatik oturum açmayı etkinleştirmelidir. Bu, özellikle cihaz taşıma sırasında kullanıcıların kimlik bilgilerini tekrar girmeden hesaplarına hızlı bir şekilde erişebilecekleri cihazlar arasında sorunsuz bir deneyim sağlar. Bu özellik, kullanıcılarınız için daha önce oturum açmışken gereksiz zorlukları ortadan kaldırır.

Otomatik oturum açmayı etkinleştirmek için setAutoSelectEnabled(true) uygulamasını kullanın. Otomatik oturum açma yalnızca aşağıdaki ölçütler karşılandığında kullanılabilir:

  • İstekle eşleşen tek bir kimlik bilgisi vardır. Bu bir Google Hesabı veya şifre olabilir ve bu kimlik bilgisi, Android destekli cihazdaki varsayılan hesapla eşleşir.
  • Kullanıcı açık bir şekilde çıkış yapmadı.
  • Kullanıcı, Google Hesabı ayarlarında otomatik oturum açmayı devre dışı bırakmamış olmalıdır.
val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(WEB_CLIENT_ID)
  .setAutoSelectEnabled(true)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Otomatik oturum açmayı uygularken oturum kapatma işlemini doğru şekilde yapmayı unutmayın. Böylece kullanıcılar, uygulamanızda açık bir şekilde oturumu kapattıktan sonra her zaman doğru hesabı seçebilir.

Güvenliği artırmak için tek seferlik bir rastgele sayı belirleyin

Oturum açma güvenliğini iyileştirmek ve tekrar oynatma saldırılarını önlemek için her isteğe tek seferlik bir rastgele sayı eklemek için setNonce ekleyin. Tek seferlik rastgele sayı oluşturma hakkında daha fazla bilgi edinin.

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(true)
  .setServerClientId(WEB_CLIENT_ID)
  .setAutoSelectEnabled(true)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Google ile oturum açma akışını oluşturma

Google ile oturum açma akışını ayarlama adımları şunlardır:

  1. Bir GetCredentialRequest somutlaştırın, ardından kimlik bilgilerini almak için addCredentialOption() kullanarak önceden oluşturulan googleIdOption öğesini ekleyin.
  2. Kullanıcının mevcut kimlik bilgilerini almak için bu isteği getCredential() (Kotlin) veya getCredentialAsync() (Java) çağrısına iletin.
  3. API başarılı olduktan sonra GoogleIdTokenCredential verileri için sonucu barındıran CustomCredential dosyasını çıkarın.
  4. CustomCredential türü, GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL değerine eşit olmalıdır. GoogleIdTokenCredential.createFrom yöntemini kullanarak nesneyi GoogleIdTokenCredential biçimine dönüştürün.

  5. Dönüşüm başarılı olursa GoogleIdTokenCredential kimliğini çıkartın, doğrulayın ve sunucunuzda kimlik bilgisini doğrulayın.

  6. Dönüşüm bir GoogleIdTokenParsingException ile başarısız olursa Google ile oturum açma kitaplığı sürümünüzü güncellemeniz gerekebilir.

  7. Tanınmayan özel kimlik bilgisi türlerini yakalayın.

val request: GetCredentialRequest = Builder()
  .addCredentialOption(googleIdOption)
  .build()

coroutineScope.launch {
  try {
    val result = credentialManager.getCredential(
      request = request,
      context = activityContext,
    )
    handleSignIn(result)
  } catch (e: GetCredentialException) {
    handleFailure(e)
  }
}

fun handleSignIn(result: GetCredentialResponse) {
  // Handle the successfully returned credential.
  val credential = result.credential

  when (credential) {

    // Passkey credential
    is PublicKeyCredential -> {
      // Share responseJson such as a GetCredentialResponse on your server to
      // validate and authenticate
      responseJson = credential.authenticationResponseJson
    }

    // Password credential
    is PasswordCredential -> {
      // Send ID and password to your server to validate and authenticate.
      val username = credential.id
      val password = credential.password
    }

    // GoogleIdToken credential
    is CustomCredential -> {
      if (credential.type == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL) {
        try {
          // Use googleIdTokenCredential and extract id to validate and
          // authenticate on your server.
          val googleIdTokenCredential = GoogleIdTokenCredential
            .createFrom(credential.data)
        } catch (e: GoogleIdTokenParsingException) {
          Log.e(TAG, "Received an invalid google id token response", e)
        }
      } else {
        // Catch any unrecognized custom credential type here.
        Log.e(TAG, "Unexpected type of credential")
      }
    }

    else -> {
      // Catch any unrecognized credential type here.
      Log.e(TAG, "Unexpected type of credential")
    }
  }
}

Google ile Oturum Açma düğme akışını tetikleme

Google ile oturum aç düğme akışını tetiklemek için GetGoogleIdOption yerine GetSignInWithGoogleOption değerini kullanın:

val signInWithGoogleOption: GetSignInWithGoogleOption = GetSignInWithGoogleOption.Builder()
  .setServerClientId(WEB_CLIENT_ID)
  .setNonce(<nonce string to use when generating a Google ID token>)
  .build()

Döndürülen GoogleIdTokenCredential öğesini aşağıdaki kod örneğinde açıklandığı gibi işleyin.

fun handleSignIn(result: GetCredentialResponse) {
  // Handle the successfully returned credential.
  val credential = result.credential

  when (credential) {
    is CustomCredential -> {
      if (credential.type == GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL) {
        try {
          // Use googleIdTokenCredential and extract id to validate and
          // authenticate on your server.
          val googleIdTokenCredential = GoogleIdTokenCredential
            .createFrom(credential.data)
        } catch (e: GoogleIdTokenParsingException) {
          Log.e(TAG, "Received an invalid google id token response", e)
        }
      }
      else -> {
        // Catch any unrecognized credential type here.
        Log.e(TAG, "Unexpected type of credential")
      }
    }

    else -> {
      // Catch any unrecognized credential type here.
      Log.e(TAG, "Unexpected type of credential")
    }
  }
}

Google oturum açma isteğini örnek hale getirdikten sonra, kimlik doğrulama akışını Google ile oturum açma bölümünde belirtildiği şekilde başlatın.

Yeni kullanıcılar için kaydolmayı etkinleştir (önerilir)

Google ile oturum açma, kullanıcıların uygulamanız veya hizmetiniz ile yalnızca birkaç dokunuşla yeni hesap oluşturmasının en kolay yoludur.

Kayıtlı kimlik bilgisi bulunamazsa (getGoogleIdOption tarafından döndürülmeyen Google Hesabı) kullanıcınızdan kaydolmasını isteyin. İlk olarak, daha önce kullanılmış hesap olup olmadığını kontrol etmek için setFilterByAuthorizedAccounts(true) olup olmadığını kontrol edin. Herhangi bir giriş bulunmazsa kullanıcıdan setFilterByAuthorizedAccounts(false) kodunu kullanarak Google Hesabı ile kaydolmasını isteyin

Örnek:

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
  .setFilterByAuthorizedAccounts(false)
  .setServerClientId(SERVER_CLIENT_ID)
  .build()

Google'a kaydolma isteğini örneklendirdikten sonra kimlik doğrulama akışını başlatın. Kullanıcılar Google'a kaydolmak istemiyorsa hesap oluşturma için otomatik doldurma hizmetlerini veya geçiş anahtarlarını kullanabilirsiniz.

Oturumu kapatma işlemini yönet

Bir kullanıcı uygulamanızda oturumu kapattığında, tüm kimlik bilgisi sağlayıcıların geçerli kullanıcı kimlik bilgisi durumunu temizlemek için API clearCredentialState() yöntemini çağırın. Bu işlem, ilgili uygulama için depolanan tüm kimlik bilgisi oturumlarının temizlenmesi gerektiğini tüm kimlik bilgisi sağlayıcılara bildirir.

Bir kimlik bilgisi sağlayıcısı, etkin bir kimlik bilgisi oturumu depolamış ve gelecekteki kimlik bilgisi alma çağrılarında oturum açma seçeneklerini sınırlamak için bu oturumu kullanıyor olabilir. Örneğin, etkin kimlik bilgisine mevcut diğer kimlik bilgilerine göre öncelik verebilir. Kullanıcınız uygulamanızda açık bir şekilde oturumu kapattığında ve bir sonraki oturumda bütünsel oturum açma seçenekleri elde etmek için, sağlayıcının depolanan kimlik bilgisi oturumlarını temizlemesine izin vermek için bu API'yi çağırmanız gerekir.