نمای کلی
در ۱۶ فوریه ۲۰۲۲، برنامههایی را برای ایمنتر کردن تعاملات Google OAuth بااستفاده از جریانهای OAuth ایمنتر اعلام کردیم. این راهنما به شما کمک میکند تغییرات و مراحل لازم برای انتقال موفقیتآمیز از جریان «خارج باند» (OOB) OAuth به جایگزینهای پشتیبانیشده را درک کنید.
این تلاش اقدامی محافظتی دربرابر حملات رمزگیری و جعل هویت برنامه درطول تعامل با نقاط پایانی مجوز OAuth 2.0 در Google است.
OOB چیست؟
OAuth خارج از باند (OOB)، که بهعنوان گزینه کپی و جایگذاری دستی نیز شناخته میشود، یک جریان قدیمی است که برای پشتیبانی از کارخواههای نصبشدهای توسعه یافته است که پساز تأیید درخواست رضایت OAuth توسط کاربر، URI هدایت برای پذیرش اعتبارنامهها ندارند. جریان OOB خطر رمزگیری از راه دور را بههمراه دارد و کارخواهها باید به روش جایگزینی مهاجرت کنند تا دربرابر این آسیبپذیری محافظت شوند.
جریان OOB برای همه انواع برنامهها منسوخ میشود—یعنی برنامههای وب، Android، iOS، Universal Windows Platform (UWP)، برنامههای Chrome، تلویزیونها و دستگاههای ورودی محدود، برنامههای رایانه.
تاریخهای کلیدی برای رعایت خطمشیها
- ۲۸ فوریه ۲۰۲۲ - استفاده جدید از OAuth برای جریان OOB مسدود شد
- ۵ سپتامبر ۲۰۲۲ - ممکن است پیام هشدار سَمت کاربر برای درخواستهای OAuth غیرمنطبق نمایش داده شود
- ۳ اکتبر ۲۰۲۲ - جریان OOB برای کارخواههای OAuth ایجادشده قبلاز ۲۸ فوریه ۲۰۲۲ منسوخ میشود
- ۳۱ ژانویه ۲۰۲۳ - همه مشتریان موجود مسدود میشوند (ازجمله مشتریان معافشده)
برای درخواستهای غیرمنطبق، پیام خطای سَمت کاربر نمایش داده خواهد شد. این پیام به کاربران اطلاع میدهد که برنامه مسدود شده است و درعینحال ایمیل پشتیبانی را که در صفحه رضایت OAuth در کنسول Google Cloud ثبت کردهاید نمایش میدهد.
دو مرحله اصلی برای تکمیل فرایند انتقال وجود دارد:
- ببینید آیا تحتتأثیر قرار گرفتهاید یا نه.
- اگر تحتتأثیر قرار گرفتهاید، به یک سیستم مطمئنتر منتقل کنید.
تعیین اینکه آیا تحتتأثیر قرار گرفتهاید یا نه
این منسوخ شدن فقط برای برنامههای تولید (یعنی برنامههایی که وضعیت انتشار آنها روی در تولید تنظیم شده است) اعمال میشود. جریان همچنان برای برنامههایی که وضعیت انتشار آزمایشی دارند کار خواهد کرد.
وضعیت انتشار خود را در OAuth صفحه نمانامسازی از Google Cloud Console بررسی کنید و اگر از جریان OOB در پروژهای با وضعیت انتشار «در تولید» استفاده میکنید، به مرحله بعدی بروید.
نحوه تشخیص اینکه برنامهتان از جریان OOB استفاده میکند یا نه
کد برنامهتان یا تماس شبکه خروجی (درصورتیکه برنامهتان از کتابخانه OAuth استفاده میکند) را بررسی کنید تا مشخص شود آیا درخواست مجوز Google OAuth که برنامهتان ایجاد میکند از مقدار URI تغییرمسیر OOB استفاده میکند یا نه.
کد برنامهتان را بازرسی کنید
بخشی از کد برنامهتان را که در آن با نقطههای پایانی مجوز Google OAuth تماس میگیرید بازبینی کنید و ببینید آیا پارامتر redirect_uri هیچکدام از مقادیر زیر را دارد یا نه:
redirect_uri=urn:ietf:wg:oauth:2.0:oobredirect_uri=urn:ietf:wg:oauth:2.0:oob:autoredirect_uri=oob
نمونه درخواست جریان هدایت OOB بهصورت زیر است:
https://accounts.google.com/o/oauth2/v2/auth? response_type=code& scope=<SCOPES>& state=<STATE>& redirect_uri=urn:ietf:wg:oauth:2.0:oob& client_id=<CLIENT_ID>
بازرسی تماس شبکه خروجی
روش بازرسی تماسهای شبکه بسته به نوع برنامه شما متفاوت خواهد بود.
- برنامه وب - بازرسی فعالیت شبکه در Chrome
- Android - inspect network traffic with the Network Inspector
- برنامههای Chrome
- به صفحه افزونههای Chrome بروید
- چارگوش انتخاب حالت توسعهدهنده را در گوشه بالا سمت چپ صفحه افزونه علامت بزنید
- افزونهای را که میخواهید پایش کنید انتخاب کنید
- روی پیوند صفحه پسزمینه در بخش بازرسی نماها صفحه افزونه کلیک کنید
- کادر گفتگوی ابزارهای توسعهدهندگان باز میشود که در آن میتوانید ترافیک شبکه را در برگه شبکه پایش کنید
- iOS - Analyzing HTTP traffic with Instruments
- برنامههای رایانهای - از ابزار ضبط شبکه موجود برای سیستمعاملی که برنامه برای آن توسعه یافته است استفاده کنید
هنگام بازرسی تماسهای شبکه، درخواستهای ارسالشده به
نقطههای پایانی مجوز Google OAuth را جستجو کنید و ببینید آیا پارامتر redirect_uri
یکی از مقادیر زیر را دارد یا نه:
redirect_uri=urn:ietf:wg:oauth:2.0:oobredirect_uri=urn:ietf:wg:oauth:2.0:oob:autoredirect_uri=oob
نمونه درخواست جریان هدایت OOB بهصورت زیر است:
https://accounts.google.com/o/oauth2/v2/auth? response_type=code& scope=<SCOPES>& state=<STATE>& redirect_uri=urn:ietf:wg:oauth:2.0:oob& client_id=<CLIENT_ID>
انتقال به جایگزین ایمن
کارخواههای برنامه همراه (Android و iOS)
اگر تشخیص دادید که برنامهتان از جریان OOB با نوع برنامه OAuth در Android یا iOS استفاده میکند، باید به استفاده از کیتهای توسعه نرمافزار توصیهشده (Android، iOS) مهاجرت کنید.
کیت توسعه نرمافزار به شما کمک میکند به Google APIs دسترسی پیدا کنید و همه تماسها با نقاط پایانی مجوز OAuth 2.0 در Google را مدیریت میکند.
پیوندهای اسناد زیر اطلاعاتی درباره نحوه استفاده از کیتهای توسعه نرمافزار توصیهشده برای دسترسی به Google API بدون استفاده از URI تغییرمسیر OOB ارائه میدهند.
دسترسی به Google APIs در Android
دسترسی سمت کارخواه
مثال زیر نشان میدهد که چگونه بااستفاده از «کتابخانه Android سرویسهای مدیریت هویتسنجی Google» توصیهشده، در سمت کارخواه در Android به Google APIs دسترسی پیدا کنید.
List<Scopes> requestedScopes = Arrays.asList(DriveScopes.DRIVE_APPDATA);
AuthorizationRequest authorizationRequest =
AuthorizationRequest.builder()
.setRequestedScopes(requestedScopes)
.build();
Identity.getAuthorizationClient(activity)
.authorize(authorizationRequest)
.addOnSuccessListener(
authorizationResult -> {
if (authorizationResult.hasResolution()) {
// Access needs to be granted by the user
PendingIntent pendingIntent =
authorizationResult.getPendingIntent();
try {
startIntentSenderForResult(
pendingIntent.getIntentSender(),
REQUEST_AUTHORIZE, null, 0, 0, 0, null);
} catch (IntentSender.SendIntentException e) {
Log.e(
TAG,
"Couldn't start Authorization UI: "
+ e.getLocalizedMessage());
}
} else {
// Access already granted, continue with user action
saveToDriveAppFolder(authorizationResult);
}
})
.addOnFailureListener(e -> Log.e(TAG, "Failed to authorize", e));
authorizationResult را به روش تعریفشدهتان منتقل کنید تا محتوا در پوشه Drive کاربر ذخیره شود. authorizationResult دارای روش
getAccessToken() است که کد دسترسی را برمیگرداند.
دسترسی سمت سرور (آفلاین)
مثال زیر نشان میدهد که چگونه میتوان به Google APIs در سمت سرور در Android دسترسی پیدا کرد.
List<Scopes> requestedScopes = Arrays.asList(DriveScopes.DRIVE_APPDATA); AuthorizationRequest authorizationRequest = AuthorizationRequest.builder() .requestOfflineAccess(webClientId) .setRequestedScopes(requestedScopes) .build(); Identity.getAuthorizationClient(activity) .authorize(authorizationRequest) .addOnSuccessListener( authorizationResult -> { if (authorizationResult.hasResolution()) { // Access needs to be granted by the user PendingIntent pendingIntent = authorizationResult.getPendingIntent(); try { startIntentSenderForResult( pendingIntent.getIntentSender(), REQUEST_AUTHORIZE, null, 0, 0, 0, null); } catch (IntentSender.SendIntentException e) { Log.e( TAG, "Couldn't start Authorization UI: " + e.getLocalizedMessage()); } } else { String authCode = authorizationResult.getServerAuthCode(); } }) .addOnFailureListener(e -> Log.e(TAG, "Failed to authorize", e));
authorizationResult دارای روش getServerAuthCode() است که کد مجوز را برمیگرداند و میتوانید آن را به پسین خود ارسال کنید تا ژتون دسترسی و بازآوری را دریافت کنید.
دسترسی به Google APIs در برنامه iOS
دسترسی سمت کارخواه
مثال زیر نشان میدهد که چگونه میتوان در سمت کارخواه در iOS به Google API دسترسی پیدا کرد.
user.authentication.do { authentication, error in guard error == nil else { return } guard let authentication = authentication else { return } // Get the access token to attach it to a REST or gRPC request. let accessToken = authentication.accessToken // Or, get an object that conforms to GTMFetcherAuthorizationProtocol for // use with GTMAppAuth and the Google APIs client library. let authorizer = authentication.fetcherAuthorizer() }
با گنجاندن کد دسترسی در سرصفحه درخواست REST یا gRPC (Authorization: Bearer ACCESS_TOKEN) یا بااستفاده از fetcher authorizer (GTMFetcherAuthorizationProtocol) با کتابخانه کارخواه Google APIs برای Objective-C برای REST (Google APIs client library for Objective-C for REST)، از کد دسترسی برای فراخوانی میانای برنامهسازی کاربردی استفاده کنید.
راهنمای دسترسی سمت کارخواه را برای نحوه دسترسی به Google APIs در سمت کارخواه مرور کنید.
دسترسی سمت سرور (آفلاین)
مثال زیر نشان میدهد که چگونه میتوان به Google APIs در سمت سرور دسترسی پیدا کرد تا از کارخواه iOS پشتیبانی شود.
GIDSignIn.sharedInstance.signIn(
with: signInConfig, presenting: self
) { user, error in
guard error == nil else { return }
guard let user = user else { return }
// request a one-time authorization code that your server exchanges for
// an access token and refresh token
let authCode = user.serverAuthCode
}راهنمای دسترسی سمت سرور را درباره نحوه دسترسی به Google APIs از سمت سرور مرور کنید.
Chrome App Client
اگر تشخیص دادید که برنامهتان از جریان OOB در کارخواه برنامه Chrome استفاده میکند، باید به استفاده از Chrome Identity API کوچ کنید.
مثال زیر نشان میدهد که چگونه میتوان همه مخاطبین کاربر را بدون استفاده از URI تغییرمسیر OOB دریافت کرد.
window.onload = function() { document.querySelector('button').addEventListener('click', function() { // retrieve access token chrome.identity.getAuthToken({interactive: true}, function(token) { // .......... // the following example shows how to use a retrieved access token with an // appropriate scope to call the Google People API contactGroups.get endpoint fetch( 'https://people.googleapis.com/v1/contactGroups/all' + '?maxMembers=20&key=API_KEY', init) .then((response) => response.json()) .then(function(data) { console.log(data) }); }); }); };
برای اطلاعات بیشتر درباره نحوه دسترسی به اصالتسنجی کاربران و فراخوانی نقاط پایانی Google با Chrome Identity API، راهنمای Chrome Identity API را مرور کنید.
برنامه وب
اگر تشخیص دادید که برنامهتان از جریان OOB برای برنامه وب استفاده میکند، باید به استفاده از یکی از کتابخانههای کارخواه Google API ما مهاجرت کنید. فهرست کتابخانههای کارخواه Google API را برای زبانهای برنامهنویسی مختلف ببینید.
کتابخانهها دسترسی به میاناهای برنامهسازی کاربردی Google را ساده میکنند و همه فراخوانیها به نقاط پایانی Google را مدیریت میکنند.
دسترسی سمت سرور (آفلاین)
حالت دسترسی سمت سرور (آفلاین) مستلزم این است که کارهای زیر را انجام دهید :
- سروری راهاندازی کنید و نقطه پایانی با دسترسی عمومی (URI هدایت) برای دریافت کد مجوز تعریف کنید.
- URI هدایت را در صفحه کارخواهها در Google Cloud Console پیکربندی کنید
تکهکد زیر نمونهای از NodeJS را نشان میدهد که از Google Drive API برای فهرست کردن فایلهای Google Drive کاربر در سمت سرور بدون استفاده از URI تغییرمسیر OOB استفاده میکند.
async function main() { const server = http.createServer(async function (req, res) { if (req.url.startsWith('/oauth2callback')) { let q = url.parse(req.url, true).query; if (q.error) { console.log('Error:' + q.error); } else { // Get access and refresh tokens (if access_type is offline) let { tokens } = await oauth2Client.getToken(q.code); oauth2Client.setCredentials(tokens); // Example of using Google Drive API to list filenames in user's Drive. const drive = google.drive('v3'); drive.files.list({ auth: oauth2Client, pageSize: 10, fields: 'nextPageToken, files(id, name)', }, (err1, res1) => { // TODO(developer): Handle response / error. }); } } }
راهنمای برنامه وب سمت سرور را درباره نحوه دسترسی به Google API از سمت سرور مرور کنید.
دسترسی سمت کارخواه
تکهکد زیر، در جاوا اسکریپت، نمونهای از استفاده از Google API برای دسترسی به رویدادهای تقویم کاربر در سمت کارخواه را نشان میدهد.
// initTokenClient() initializes a new token client with your // web app's client ID and the scope you need access to const client = google.accounts.oauth2.initTokenClient({ client_id: 'YOUR_GOOGLE_CLIENT_ID', scope: 'https://www.googleapis.com/auth/calendar.readonly', // callback function to handle the token response callback: (tokenResponse) => { if (tokenResponse && tokenResponse.access_token) { gapi.client.setApiKey('YOUR_API_KEY'); gapi.client.load('calendar', 'v3', listUpcomingEvents); } }, }); function listUpcomingEvents() { gapi.client.calendar.events.list(...); }
راهنمای برنامه وب سمت کارخواه را درباره نحوه دسترسی به Google API از سمت کارخواه مرور کنید.
کارخواه رایانه
اگر تشخیص دادید که برنامهتان از جریان OOB در کارخواه رایانه استفاده میکند،
باید به استفاده از جریان نشانی IP مسیریابی بازگشتی (localhost یا 127.0.0.1)
کوچ کنید.