پیوند حساب Google به دارندگان حساب Google این امکان را می دهد که سریع، یکپارچه و ایمن به خدمات شما متصل شوند و داده ها را با Google به اشتراک بگذارند.
ورود به سیستم حساب پیوندی، ورود با یک ضربه با Google را برای کاربرانی که از قبل حساب Google خود را به سرویس شما مرتبط کرده‌اند، فعال می‌کند. این تجربه را برای کاربران بهبود می بخشد زیرا آنها می توانند با یک کلیک بدون وارد کردن نام کاربری و رمز عبور خود وارد سیستم شوند. همچنین شانس ایجاد حساب های تکراری در سرویس شما توسط کاربران را کاهش می دهد.
الزامات
برای پیاده سازی ورود به حساب لینک شده، باید شرایط زیر را رعایت کنید:
- شما یک پیاده سازی OAuth Linking حساب Google دارید که از جریان کد مجوز OAuth 2.0 پشتیبانی می کند. اجرای OAuth شما باید شامل نقاط پایانی زیر باشد:
- نقطه پایانی مجوز برای رسیدگی به درخواست های مجوز.
- نقطه پایانی نشانه برای رسیدگی به درخواست دسترسی و به‌روزرسانی نشانه‌ها.
- userinfo endpoint برای بازیابی اطلاعات اولیه حساب در مورد کاربر پیوند شده که در طی فرآیند ورود به حساب پیوندی به کاربر نمایش داده می شود.
- شما یک برنامه اندروید دارید.
چگونه کار می کند
پیش نیاز: کاربر قبلاً حساب Google خود را با حساب خود در سرویس شما پیوند داده است.
- در طول جریان ورود به سیستم با یک ضربه، نمایش حساب‌های مرتبط را انتخاب می‌کنید.
- یک درخواست ورود با یک ضربه به کاربر نشان داده می‌شود که گزینه‌ای برای ورود به سرویس شما با حساب مرتبط خود دارد.
- اگر کاربر انتخاب کند که با حساب پیوند شده ادامه دهد، Google درخواستی برای ذخیره کد مجوز به نقطه پایانی رمز شما ارسال می کند. این درخواست شامل رمز دسترسی کاربر صادر شده توسط سرویس شما و یک کد مجوز Google است.
- شما کد مجوز Google را با یک رمز Google ID که حاوی اطلاعات حساب Google کاربر است، مبادله می کنید.
- برنامه شما همچنین پس از پایان جریان، یک کد شناسه دریافت می‌کند و شما آن را با شناسه کاربری در کد ID که توسط سرور شما دریافت شده است، مطابقت می‌دهید تا کاربر را وارد برنامه خود کنید.
ورود به حساب پیوندی را در برنامه اندروید خود پیاده کنید
برای پشتیبانی از ورود به حساب پیوندی در برنامه Android خود، دستورالعمل‌های راهنمای اجرای Android را دنبال کنید.
رسیدگی به درخواست‌های کد مجوز از Google
Google یک درخواست POST به نقطه پایانی توکن شما می‌کند تا کد مجوزی را که با کد شناسه کاربر مبادله می‌کنید، ذخیره کند. این درخواست شامل رمز دسترسی کاربر و کد مجوز OAuth2 صادر شده توسط Google است.
قبل از ذخیره کد مجوز، باید تأیید کنید که رمز دسترسی توسط شما به Google اعطا شده است که توسط client_id شناسایی شده است.
درخواست HTTP
نمونه درخواست
POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
code=GOOGLE_AUTHORIZATION_CODE
&grant_type=urn:ietf:params:oauth:grant-type:reciprocal
&client_id=CLIENT_ID
&client_secret=CLIENT_SECRET
&access_token=ACCESS_TOKEN
نقطه پایانی مبادله رمز شما باید بتواند پارامترهای درخواست زیر را مدیریت کند:
| پارامترهای نقطه پایانی رمز | |
|---|---|
code | کد مجوز Google OAuth2 مورد نیاز است |
client_id | شناسه مشتری مورد نیازی که برای Google صادر کردید |
client_secret | راز مورد نیاز مشتری که برای Google صادر کردید |
access_token | رمز دسترسی مورد نیاز که برای Google صادر کردید. شما از این برای دریافت زمینه کاربر استفاده خواهید کرد |
grant_type | مقدار مورد نیاز باید روی urn:ietf:params:oauth:grant-type:reciprocal تنظیم شود |
نقطه پایانی تبادل توکن شما باید با انجام موارد زیر به درخواست POST پاسخ دهد:
- بررسی کنید
access_tokenبه Google اعطا شده است که توسطclient_idشناسایی شده است. - اگر درخواست معتبر است و کد احراز هویت با موفقیت با یک نشانه Google ID مبادله شده است، یا با یک پاسخ HTTP 200 (OK) پاسخ دهید، یا اگر درخواست نامعتبر است، با کد خطای HTTP پاسخ دهید.
پاسخ HTTP
موفقیت
کد وضعیت HTTP را 200 OK برگردانید
نمونه پاسخ موفقیت
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache
{}
خطاها
در صورت درخواست نامعتبر HTTP، با یکی از کدهای خطای HTTP زیر پاسخ دهید:
| کد وضعیت HTTP | بدن | شرح |
|---|---|---|
| 400 | {"error": "invalid_request"} | درخواست فاقد پارامتر است، بنابراین سرور نمی تواند درخواست را ادامه دهد. اگر درخواست شامل یک پارامتر پشتیبانی نشده باشد یا یک پارامتر را تکرار کند، ممکن است این مورد برگردانده شود |
| 401 | {"error": "invalid_request"} | احراز هویت مشتری ناموفق بود، مثلاً اگر درخواست حاوی شناسه مشتری یا رمز نامعتبر باشد |
| 401 | {"error": "invalid_token"}چالش احراز هویت "WWW-Authentication: Bearer" را در سرصفحه پاسخ قرار دهید | رمز دسترسی شریک نامعتبر است. |
| 403 | {"error": "insufficient_permission"}چالش احراز هویت "WWW-Authentication: Bearer" را در سرصفحه پاسخ قرار دهید | رمز دسترسی شریک شامل محدوده(های) لازم برای اجرای OAuth متقابل نیست |
| 500 | {"error": "internal_error"} | خطای سرور |
پاسخ خطا باید شامل فیلدهای زیر باشد:
| فیلدهای پاسخ به خطا | |
|---|---|
error | رشته خطای مورد نیاز |
error_description | توصیف خطا توسط انسان |
error_uri | URI که جزئیات بیشتری در مورد خطا ارائه می دهد |
نمونه پاسخ خطای 400
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error": "invalid_request",
"error_description": "Request was missing the 'access_token' parameter."
}
مبادله کد مجوز برای شناسه رمز
شما باید کد مجوزی که دریافت کرده‌اید را با یک توکن Google ID که حاوی اطلاعاتی درباره حساب Google کاربر است، مبادله کنید.
برای مبادله کد مجوز برای یک نشانه Google ID، با https://oauth2.googleapis.com/token endpoint تماس بگیرید و پارامترهای زیر را تنظیم کنید:
| فیلدهای درخواست | |
|---|---|
client_id | مورد نیاز شناسه مشتری که از صفحه اعتبار کنسول API به دست آمده است. این معمولاً اعتباری با نام اقدامات جدید در برنامه Google است |
client_secret | مورد نیاز راز مشتری که از صفحه اعتبار کنسول API بدست می آید |
code | مورد نیاز کد مجوز ارسال شده در درخواست اولیه |
grant_type | مورد نیاز همانطور که در مشخصات OAuth 2.0 تعریف شده است ، مقدار این فیلد باید روی authorization_code تنظیم شود. |
نمونه درخواست
POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded
code=GOOGLE_AUTHORIZATION_CODE
&grant_type=authorization_code
&client_id=GOOGLE_CLIENT_ID
&client_secret=GOOGLE_CLIENT_SECRET
Google به این درخواست با برگرداندن یک شی JSON که حاوی یک نشانه دسترسی کوتاه مدت و یک نشانه تازه‌سازی است، پاسخ می‌دهد.
پاسخ شامل فیلدهای زیر است:
| فیلدهای پاسخ | |
|---|---|
access_token | کد دسترسی صادر شده توسط Google که برنامه شما برای تأیید درخواست Google API ارسال می کند |
id_token | رمز شناسه حاوی اطلاعات حساب Google کاربر است. بخش Validate Response شامل جزئیاتی در مورد نحوه رمزگشایی و اعتبارسنجی پاسخ نشانه ID است |
expires_in | طول عمر باقیمانده رمز دسترسی در ثانیه |
refresh_token | توکنی که می توانید از آن برای به دست آوردن یک نشانه دسترسی جدید استفاده کنید. نشانه‌های Refresh تا زمانی که کاربر دسترسی را لغو نکند معتبر هستند |
scope | مقدار این فیلد همیشه برای مورد استفاده از ورود به سیستم حساب پیوندی روی openid تنظیم می شود |
token_type | نوع رمز برگشتی. در این زمان، مقدار این فیلد همیشه روی Bearer تنظیم می شود |
نمونه پاسخ
HTTP/1.1 200 OK
Content-type: application/json; charset=utf-8
{
"access_token": "Google-access-token",
"id_token": "Google-ID-token",
"expires_in": 3599,
"token_type": "Bearer",
"scope": "openid",
"refresh_token": "Google-refresh-token"
}
POST /oauth2/v4/token HTTP/1.1
Host: www.googleapis.com
Content-Type: application/x-www-form-urlencoded
code=Google authorization code
&grant_type=authorization_code
&client_id=Google client id
&client_secret=Google client secret
پاسخ ID Token را تأیید کنید
验证并解码JWT断言
您可以使用针对您的语言的JWT解码库来验证和解码JWT断言。使用Google的JWK或PEM格式的公钥来验证令牌的签名。
解码后，JWT断言类似于以下示例：
{
"sub": "1234567890", // The unique ID of the user's Google Account
"iss": "https://accounts.google.com", // The assertion's issuer
"aud": "123-abc.apps.googleusercontent.com", // Your server's client ID
"iat": 233366400, // Unix timestamp of the assertion's creation time
"exp": 233370000, // Unix timestamp of the assertion's expiration time
"name": "Jan Jansen",
"given_name": "Jan",
"family_name": "Jansen",
"email": "jan@gmail.com", // If present, the user's email address
"email_verified": true, // true, if Google has verified the email address
"hd": "example.com", // If present, the host domain of the user's GSuite email address
// If present, a URL to user's profile picture
"picture": "https://lh3.googleusercontent.com/a-/AOh14GjlTnZKHAeb94A-FmEbwZv7uJD986VOF1mJGb2YYQ",
"locale": "en_US" // User's locale, from browser or phone settings
}
除了验证令牌的签名外，还要验证断言的颁发者（ iss字段）为https://accounts.google.com ，受众（ aud字段）是您分配的客户端ID，并且令牌尚未过期（ exp场地）。
使用email ， email_verified和hd字段，您可以确定Google是否托管电子邮件地址并对其具有权威性。如果Google具有权威性，则当前已知该用户为合法帐户所有者，您可以跳过密码或其他挑战方法。否则，可以使用这些方法在链接之前验证帐户。
Google具有权威性的情况：
-
email后缀为@gmail.com，这是一个Gmail帐户。 -
email_verified为true并且设置了hd，这是一个G Suite帐户。
用户可以在不使用Gmail或G Suite的情况下注册Google帐户。如果email不包含@gmail.com后缀，并且没有hd则Google并不具有权威性，建议您使用密码或其他验证方法来验证用户。当Google在创建Google帐户时最初验证了用户时， email_verfied也可能为true，但是此后第三方电子邮件帐户的所有权可能已更改。