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

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

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

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

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

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

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

خود را تنظیم کنید Google Cloud Console پروژه

1. پروژه خود را درCloud Console ، یا اگر قبلا پروژه ای ندارید ایجاد کنید.
2. درBranding page ، مطمئن شوید که همه اطلاعات کامل و دقیق هستند.
   1. مطمئن شوید که نام برنامه، نشان‌واره برنامه و صفحه اصلی برنامه به برنامه شما اختصاص داده شده است. این مقادیر در صفحه رضایت ورود به سیستم با Google هنگام ثبت نام و صفحه برنامه‌ها و خدمات شخص ثالث به کاربران ارائه می‌شوند.
   2. مطمئن شوید که نشانی‌های اینترنتی خط‌مشی رازداری و شرایط خدمات برنامه‌تان را مشخص کرده‌اید.
3. درClients page ، یک شناسه کلاینت Android برای برنامه خود ایجاد کنید، اگر قبلاً آن را ندارید. شما باید نام بسته برنامه و امضای SHA-1 را مشخص کنید.
   1. برو بهClients page .
   2. روی ایجاد مشتری کلیک کنید.
   3. نوع برنامه اندروید را انتخاب کنید.
   4. یک نام برای مشتری OAuth وارد کنید. این نام در پروژه شما نمایش داده می شودClients page برای شناسایی مشتری
   5. نام بسته برنامه اندروید خود را وارد کنید. این مقدار در [ ویژگی package عنصر <manifest> ][manifest-element-package] in your تعریف شده است.
   6. اثر انگشت گواهی امضای SHA-1 توزیع برنامه را وارد کنید.
   7. اگر برنامه شما از امضای برنامه توسط Google Play استفاده می‌کند، اثر انگشت SHA-1 را از صفحه امضای برنامه کنسول Play کپی کنید.
   8. اگر ذخیره کلید و کلیدهای امضای خود را مدیریت می‌کنید، از ابزار ابزار کلید موجود در جاوا برای چاپ اطلاعات گواهی در قالبی قابل خواندن برای انسان استفاده کنید. مقدار SHA-1 را در بخش Certificate fingerprints در خروجی ابزار کلید کپی کنید. برای اطلاعات بیشتر به تأیید اعتبار مشتری خود در اسناد Google APIs for Android مراجعه کنید.
   9. (اختیاری) مالکیت برنامه Android خود را تأیید کنید .
4. درClients page ، شناسه مشتری «برنامه وب» جدید ایجاد کنید، اگر قبلاً این کار را نکرده اید. فعلاً می‌توانید از فیلدهای «اصالت‌های مجاز جاوا اسکریپت» و «URIs تغییر مسیر مجاز» چشم‌پوشی کنید. این شناسه مشتری برای شناسایی سرور پشتیبان شما هنگام برقراری ارتباط با سرویس‌های احراز هویت Google استفاده می‌شود.
   1. برو بهClients page .
   2. روی ایجاد مشتری کلیک کنید.
   3. نوع برنامه وب را انتخاب کنید.

تأیید مالکیت برنامه

برای کاهش خطر جعل هویت برنامه، می توانید مالکیت برنامه خود را تأیید کنید.

برای تکمیل فرآیند تأیید، اگر حساب برنامه‌نویس Google Play خود دارید و برنامه شما در کنسول Google Play ثبت شده است، می‌توانید از آن استفاده کنید. برای تأیید موفقیت آمیز باید شرایط زیر رعایت شود:

• باید برنامه‌ای ثبت‌شده در کنسول Google Play با همان نام بسته و اثر انگشت گواهی امضای SHA-1 به‌عنوان سرویس‌گیرنده Android OAuth که در حال تکمیل تأیید آن هستید، داشته باشید.
• شما باید مجوز Admin برای برنامه در کنسول Google Play داشته باشید. درباره مدیریت دسترسی در کنسول Google Play بیشتر بیاموزید .

در بخش Verify App Ownership در کلاینت Android، روی دکمه Verify Ownership کلیک کنید تا فرآیند تأیید تکمیل شود.

در صورت موفقیت آمیز بودن تأیید، یک اعلان برای تأیید موفقیت آمیز بودن فرآیند تأیید نمایش داده می شود. در غیر این صورت، یک اعلان خطا نشان داده خواهد شد.

برای رفع یک تأیید ناموفق، موارد زیر را امتحان کنید:

• مطمئن شوید برنامه ای که تأیید می کنید یک برنامه ثبت شده در کنسول Google Play است.
• مطمئن شوید که مجوز Admin برای برنامه در کنسول Google Play دارید.

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

وابستگی های زیر را به اسکریپت ساخت ماژول برنامه خود اضافه کنید - مطمئن شوید که <latest version> با آخرین نسخه کتابخانه googleid جایگزین کنید:

dependencies {
    implementation("androidx.credentials:credentials:1.6.0-beta01")
    implementation("androidx.credentials:credentials-play-services-auth:1.6.0-beta01")
    implementation("com.google.android.libraries.identity.googleid:googleid:<latest version>")
}

dependencies {
    implementation "androidx.credentials:credentials:1.6.0-beta01"
    implementation "androidx.credentials:credentials-play-services-auth:1.6.0-beta01"
    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)
    // nonce string to use when generating a Google ID token
    .setNonce(nonce)
    .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)
    // nonce string to use when generating a Google ID token
    .setNonce(nonce)
    .build()

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

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

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

val googleIdOption: GetGoogleIdOption = GetGoogleIdOption.Builder()
    .setFilterByAuthorizedAccounts(true)
    .setServerClientId(WEB_CLIENT_ID)
    .setAutoSelectEnabled(true)
    // nonce string to use when generating a Google ID token
    .setNonce(nonce)
    .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 = GetCredentialRequest.Builder()
    .addCredentialOption(googleIdOption)
    .build()

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

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

    when (credential) {

        // Passkey credential
        is PublicKeyCredential -> {
            // Share responseJson such as a GetCredentialResponse to 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.
                    // see [validation instructions](https://developers.google.com/identity/gsi/web/guides/verify-google-id-token)
                } 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(
    serverClientId = WEB_CLIENT_ID
).setNonce(nonce)
    .build()

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

fun handleSignInWithGoogleOption(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 تماس بگیرید تا به ارائه دهنده اجازه دهید هر جلسه اعتبار ذخیره شده را پاک کند.