احراز هویت کاربران با ورود به سیستم با Google

ورود به سیستم با Google به شما کمک می کند تا به سرعت احراز هویت کاربر را با برنامه Android خود یکپارچه کنید. کاربران می توانند از حساب Google خود برای ورود به برنامه شما، ارائه رضایت و به اشتراک گذاری ایمن اطلاعات نمایه خود با برنامه شما استفاده کنند. کتابخانه Jetpack مدیر اعتبار اندروید این ادغام را روان می‌کند و با استفاده از یک API، تجربه‌ای ثابت را در دستگاه‌های Android ارائه می‌دهد.

این سند شما را از طریق پیاده‌سازی Sign in with Google در برنامه‌های Android، نحوه راه‌اندازی رابط کاربری دکمه Sign in with Google و پیکربندی تجربه‌های ثبت‌نام و ورود با یک ضربه بهینه‌شده برای برنامه راهنمایی می‌کند. برای انتقال آسان دستگاه، «ورود به سیستم با Google» از ورود خودکار به سیستم پشتیبانی می‌کند و ماهیت چند پلتفرمی آن در Android، iOS و سطوح وب به شما کمک می‌کند دسترسی ورود به سیستم را برای برنامه‌تان در هر دستگاهی فراهم کنید.

برای راه اندازی ورود به سیستم با Google، این دو مرحله اصلی را دنبال کنید:

پیکربندی ورود با Google به عنوان گزینه ای برای رابط کاربری صفحه پایینی Credential Manager . این را می توان طوری پیکربندی کرد که به طور خودکار از کاربر درخواست ورود به سیستم شود. اگر کلیدهای عبور یا گذرواژه را اجرا کرده اید، می توانید همه انواع اعتبار مربوطه را به طور همزمان درخواست کنید، به طوری که کاربر مجبور نیست گزینه ای را که قبلا برای ورود به سیستم استفاده کرده است به خاطر بسپارد. .

برگه پایینی مدیر اعتبارنامه
شکل 1. رابط کاربری انتخاب اعتبار صفحه پایینی Credential Manager

دکمه ورود با Google را به رابط کاربری برنامه خود اضافه کنید . دکمه Sign in with Google روشی کارآمد را به کاربران ارائه می دهد تا از حساب های Google موجود خود برای ثبت نام یا ورود به برنامه های Android استفاده کنند. اگر کاربران رابط کاربر صفحه پایین را رد کنند، یا اگر صراحتاً بخواهند از حساب Google خود برای ثبت نام و ورود به سیستم استفاده کنند، روی دکمه ورود به سیستم با Google کلیک می کنند. برای توسعه دهندگان، این به معنای ورود آسان تر کاربر و کاهش اصطکاک در هنگام ثبت نام است.

انیمیشنی که جریان ورود به سیستم با Google را نشان می دهد
شکل 2. رابط کاربری Credential Manager با دکمه Google وارد شوید

این سند نحوه ادغام دکمه ورود با Google و گفتگوی صفحه پایین را با Credential Manager API با استفاده از کتابخانه راهنمای Google ID توضیح می دهد.

پروژه کنسول Google APIs خود را تنظیم کنید

  1. پروژه خود را در کنسول API باز کنید یا اگر قبلاً ندارید پروژه ای ایجاد کنید.
  2. در صفحه نمایش رضایت OAuth، مطمئن شوید که همه اطلاعات کامل و دقیق هستند.
    1. مطمئن شوید که نام برنامه، نشان‌واره برنامه و صفحه اصلی برنامه به برنامه شما اختصاص داده شده است. این مقادیر در صفحه رضایت ورود به سیستم با Google هنگام ثبت نام و صفحه برنامه‌ها و خدمات شخص ثالث به کاربران ارائه می‌شوند.
    2. مطمئن شوید که نشانی‌های اینترنتی خط‌مشی رازداری و شرایط خدمات برنامه‌تان را مشخص کرده‌اید.
  3. اگر قبلاً ندارید، در صفحه اعتبارنامه، یک شناسه کلاینت Android برای برنامه خود ایجاد کنید. شما باید نام بسته برنامه و امضای SHA-1 را مشخص کنید.
    1. به صفحه اعتبارنامه بروید.
    2. روی ایجاد اعتبار > شناسه مشتری OAuth کلیک کنید.
    3. نوع برنامه اندروید را انتخاب کنید.
  4. اگر قبلاً این کار را نکرده‌اید، در صفحه اعتبارنامه، یک شناسه مشتری «برنامه وب» جدید ایجاد کنید. فعلاً می‌توانید از فیلدهای «اصالت‌های مجاز جاوا اسکریپت» و «URIs تغییر مسیر مجاز» چشم‌پوشی کنید. این شناسه مشتری برای شناسایی سرور پشتیبان شما هنگام برقراری ارتباط با سرویس‌های احراز هویت Google استفاده می‌شود.
    1. به صفحه اعتبارنامه بروید.
    2. روی ایجاد اعتبار > شناسه مشتری OAuth کلیک کنید.
    3. نوع برنامه وب را انتخاب کنید.

وابستگی ها را اعلام کنید

در فایل build.gradle ماژول خود، وابستگی ها را با استفاده از آخرین نسخه Credential Manager اعلام کنید:

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 را به صورت نمونه ارائه کنید

برای شروع اجرای خود، یک درخواست ورود به سیستم Google را نمونه‌سازی کنید . از GetGoogleIdOption برای بازیابی شناسه Google کاربر استفاده کنید.

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

ابتدا، با فراخوانی API با پارامتر setFilterByAuthorizedAccounts که روی true تنظیم شده است، بررسی کنید که آیا کاربر حساب‌هایی دارد که قبلاً برای ورود به برنامه شما استفاده شده است. کاربران می توانند بین حساب های موجود برای ورود به سیستم انتخاب کنند.

اگر هیچ حساب Google مجاز در دسترس نباشد، باید از کاربر خواسته شود تا با هر یک از حساب های موجود خود ثبت نام کند. برای انجام این کار، با فراخوانی مجدد API و تنظیم setFilterByAuthorizedAccounts روی false از کاربر درخواست کنید. درباره ثبت نام بیشتر بدانید .

فعال کردن ورود خودکار برای کاربران بازگشتی (توصیه می شود)

توسعه دهندگان باید ورود خودکار را برای کاربرانی که با حساب تک خود ثبت نام می کنند فعال کنند. این یک تجربه بی‌نظیر را در بین دستگاه‌ها فراهم می‌کند، به‌ویژه در حین انتقال دستگاه، که در آن کاربران می‌توانند به سرعت بدون وارد کردن مجدد اعتبار، به حساب خود دسترسی پیدا کنند. برای کاربران شما، این اصطکاک غیرضروری را زمانی که قبلاً وارد سیستم شده بودند، برطرف می‌کند.

برای فعال کردن ورود خودکار، از setAutoSelectEnabled(true) استفاده کنید. ورود خودکار تنها زمانی امکان پذیر است که شرایط زیر رعایت شود:

  • یک اعتبار منطبق با درخواست وجود دارد که می‌تواند یک حساب Google یا یک رمز عبور باشد، و این اعتبار با حساب پیش‌فرض در دستگاه مجهز به Android مطابقت دارد.
  • کاربر به صراحت از سیستم خارج نشده است.
  • کاربر ورود خودکار را در تنظیمات حساب Google خود غیرفعال نکرده است. 
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()

به یاد داشته باشید هنگام اجرای ورود به سیستم خودکار، خروج از سیستم را به درستی مدیریت کنید ، تا کاربران همیشه بتوانند پس از خروج صریح از برنامه شما، حساب مناسب را انتخاب کنند.

برای بهبود امنیت یک عدد تنظیم کنید

برای بهبود امنیت ورود به سیستم و جلوگیری از حملات مجدد، setNonce اضافه کنید تا در هر درخواست یک nonce اضافه شود. درباره ایجاد یک nonce بیشتر بیاموزید .

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 را ایجاد کنید

مراحل تنظیم یک جریان ورود به سیستم با Google به شرح زیر است:

  1. یک GetCredentialRequest نمونه برداری کنید، سپس googleIdOption ایجاد شده قبلی را با استفاده از addCredentialOption() اضافه کنید تا اعتبارنامه ها را بازیابی کنید.
  2. این درخواست را به تماس getCredential() (Kotlin) یا getCredentialAsync() (جاوا) ارسال کنید تا اعتبارنامه های موجود کاربر را بازیابی کنید.
  3. پس از موفقیت آمیز بودن API، CustomCredential را استخراج کنید که نتیجه را برای داده های GoogleIdTokenCredential نگه می دارد.
  4. نوع CustomCredential باید برابر با مقدار GoogleIdTokenCredential.TYPE_GOOGLE_ID_TOKEN_CREDENTIAL باشد. با استفاده از متد GoogleIdTokenCredential.createFrom ، شی را به GoogleIdTokenCredential تبدیل کنید.

  5. اگر تبدیل با موفقیت انجام شد، شناسه GoogleIdTokenCredential را استخراج کنید، آن را تأیید کنید و اعتبار را در سرور خود تأیید کنید.

  6. اگر تبدیل با GoogleIdTokenParsingException انجام نشد، ممکن است لازم باشد نسخه ورود به سیستم با Google خود را به روز کنید.

  7. انواع اعتبارنامه سفارشی ناشناخته را بگیرید. 

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 the ID to validate and
          // authenticate on your server.
          val googleIdTokenCredential = GoogleIdTokenCredential
            .createFrom(credential.data)
          // You can use the members of googleIdTokenCredential directly for UX
          // purposes, but don't use them to store or control access to user
          // data. For that you first need to validate the token:
          // pass googleIdTokenCredential.getIdToken() to the backend server.
          GoogleIdTokenVerifier verifier = ... // see validation instructions
          GoogleIdToken idToken = verifier.verify(idTokenString);
          // To get a stable account identifier (e.g. for storing user data),
          // use the subject ID:
          idToken.getPayload().getSubject()
        } 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 را فعال کنید

برای فعال کردن جریان دکمه Sign in with Google، به جای GetGoogleIdOption از GetSignInWithGoogleOption استفاده کنید:

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

همانطور که در مثال کد زیر توضیح داده شده است، GoogleIdTokenCredential برگشتی را مدیریت کنید.

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 را انجام دادید، جریان احراز هویت را به روشی مشابه که در بخش Sign in with Google ذکر شد، راه اندازی کنید.

فعال کردن ثبت نام برای کاربران جدید (توصیه می شود)

ورود به سیستم با Google ساده ترین راه برای کاربران برای ایجاد حساب جدید با برنامه یا سرویس شما تنها با چند ضربه است.

اگر اعتبار ذخیره شده ای پیدا نشد (هیچ حساب Google توسط getGoogleIdOption بازگردانده نشده است)، از کاربر خود بخواهید که ثبت نام کند. ابتدا، بررسی کنید که آیا setFilterByAuthorizedAccounts(true) وجود دارد یا خیر. اگر هیچکدام یافت نشد، از کاربر بخواهید با استفاده از setFilterByAuthorizedAccounts(false)

مثال:

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

هنگامی که درخواست ثبت نام در گوگل را انجام دادید، جریان احراز هویت را راه اندازی کنید. اگر کاربران نمی خواهند برای ثبت نام از ورود با Google استفاده کنند، برنامه خود را برای تکمیل خودکار بهینه سازی کنید . هنگامی که کاربر شما یک حساب کاربری ایجاد کرد، ثبت نام آنها در کلیدهای عبور را به عنوان آخرین مرحله برای ایجاد حساب در نظر بگیرید.

خروج از سیستم را کنترل کنید

هنگامی که کاربر از برنامه شما خارج می شود، روش API clearCredentialState() را فراخوانی کنید تا وضعیت اعتبار کاربری فعلی از همه ارائه دهندگان اعتبار پاک شود. این به همه ارائه دهندگان اعتبارنامه اطلاع می دهد که هر جلسه اطلاعات کاربری ذخیره شده برای برنامه داده شده باید پاک شود.

ممکن است یک ارائه‌دهنده اعتبارنامه یک جلسه اعتبارنامه فعال را ذخیره کرده باشد و از آن برای محدود کردن گزینه‌های ورود به سیستم برای تماس‌های دریافت اعتبارنامه آینده استفاده کند. به عنوان مثال، ممکن است اعتبار فعال را بر هر اعتبار موجود دیگری اولویت دهد. هنگامی که کاربر شما صراحتاً از برنامه شما خارج می شود و برای اینکه دفعه بعد گزینه های ورود به سیستم جامع را دریافت کند، باید با این API تماس بگیرید تا به ارائه دهنده اجازه دهید هر جلسه اعتبار ذخیره شده را پاک کند.