استفاده از OAuth 2.0 برای برنامه های کاربردی وب سرور
با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
این سند توضیح میدهد که چگونه برنامههای وب سرور از Google API Client Libraries یا Google OAuth 2.0 برای اجرای مجوز OAuth 2.0 برای دسترسی به Google API استفاده میکنند.
OAuth 2.0 به کاربران اجازه می دهد تا داده های خاصی را با یک برنامه به اشتراک بگذارند در حالی که نام کاربری، رمز عبور و سایر اطلاعات خود را خصوصی نگه می دارند. به عنوان مثال، یک برنامه می تواند از OAuth 2.0 برای دریافت مجوز از کاربران برای ذخیره فایل ها در Google Drives خود استفاده کند.
این جریان OAuth 2.0 به طور خاص برای مجوز کاربر است. این برای برنامه هایی طراحی شده است که می توانند اطلاعات محرمانه را ذخیره کرده و وضعیت را حفظ کنند. یک برنامه وب سرور مجاز به درستی می تواند به یک API دسترسی داشته باشد در حالی که کاربر با برنامه تعامل دارد یا بعد از اینکه کاربر برنامه را ترک کرد.
برنامههای کاربردی وب سرور اغلب از حسابهای سرویس برای تأیید درخواستهای API استفاده میکنند، بهویژه زمانی که برای دسترسی به دادههای مبتنی بر پروژه بهجای دادههای خاص کاربر، APIهای Cloud را فراخوانی میکنند. برنامه های کاربردی وب سرور می توانند از حساب های خدماتی در ارتباط با مجوز کاربر استفاده کنند.
کتابخانه های مشتری
نمونههای مخصوص زبان در این صفحه از کتابخانههای سرویس گیرنده Google API برای اجرای مجوز OAuth 2.0 استفاده میکنند. برای اجرای نمونه کد، ابتدا باید کتابخانه کلاینت را برای زبان خود نصب کنید.
وقتی از Google API Client Library برای مدیریت جریان OAuth 2.0 برنامه خود استفاده می کنید، کتابخانه سرویس گیرنده اقدامات زیادی را انجام می دهد که در غیر این صورت برنامه به تنهایی باید آنها را مدیریت کند. برای مثال، تعیین میکند که برنامه چه زمانی میتواند از نشانههای دسترسی ذخیرهشده یا بازخوانی آن استفاده کند و همچنین زمانی که برنامه باید مجدداً رضایت خود را دریافت کند. کتابخانه مشتری همچنین URLهای تغییر مسیر صحیحی را تولید می کند و به پیاده سازی کنترل کننده های تغییر مسیر که کدهای مجوز را برای توکن های دسترسی مبادله می کنند، کمک می کند.
کتابخانه های Google API Client برای برنامه های سمت سرور برای زبان های زیر در دسترس هستند:
If prompted, select a project, or create a new one.
را API Library همه API های موجود را فهرست می کند که بر اساس خانواده محصول و محبوبیت گروه بندی شده اند. اگر API که میخواهید فعال کنید در لیست قابل مشاهده نیست، از جستجو برای پیدا کردن آن استفاده کنید یا روی مشاهده همه در خانواده محصولی که به آن تعلق دارد کلیک کنید.
API را که می خواهید فعال کنید انتخاب کنید، سپس روی دکمه Enable کلیک کنید.
If prompted, enable billing.
If prompted, read and accept the API's Terms of Service.
اعتبارنامه مجوز ایجاد کنید
هر برنامهای که از OAuth 2.0 برای دسترسی به APIهای Google استفاده میکند، باید دارای اعتبارنامه مجوز باشد که برنامه را در سرور OAuth 2.0 Google شناسایی کند. مراحل زیر نحوه ایجاد اعتبار برای پروژه خود را توضیح می دهد. سپس برنامه های شما می توانند از اعتبارنامه ها برای دسترسی به API هایی که برای آن پروژه فعال کرده اید استفاده کنند.
فرم را پر کنید و روی ایجاد کلیک کنید. برنامه هایی که از زبان ها و فریم ورک هایی مانند PHP، جاوا، پایتون، روبی و دات نت استفاده می کنند باید URI های مجاز تغییر مسیر را مشخص کنند. URI های تغییر مسیر، نقاط پایانی هستند که سرور OAuth 2.0 می تواند پاسخ ها را به آنها ارسال کند. این نقاط پایانی باید از قوانین اعتبارسنجی Google پیروی کنند.
برای آزمایش، می توانید URI هایی را مشخص کنید که به ماشین محلی اشاره می کنند، مانند http://localhost:8080 . با در نظر گرفتن این موضوع، لطفاً توجه داشته باشید که همه نمونههای این سند http://localhost:8080 به عنوان URI تغییر مسیر استفاده میکنند.
پس از ایجاد اعتبار، فایل client_secret.json را از API Console. فایل را در مکانی ایمن ذخیره کنید که فقط برنامه شما بتواند به آن دسترسی داشته باشد.
محدوده های دسترسی را شناسایی کنید
Scopes به برنامه شما امکان میدهد فقط درخواست دسترسی به منابع مورد نیاز خود را داشته باشد در حالی که کاربران را قادر میسازد تا میزان دسترسی را که به برنامه شما میدهند کنترل کنند. بنابراین، ممکن است بین تعداد دامنه های درخواستی و احتمال کسب رضایت کاربر رابطه معکوس وجود داشته باشد.
قبل از شروع اجرای مجوز OAuth 2.0، توصیه میکنیم محدودههایی را که برنامه شما برای دسترسی به آنها نیاز به مجوز دارد، شناسایی کنید.
ما همچنین توصیه میکنیم که برنامه شما از طریق یک فرآیند مجوز افزایشی ، که در آن برنامه شما درخواست دسترسی به دادههای کاربر در زمینه را دارد، درخواست دسترسی به دامنههای مجوز دهد. این بهترین روش به کاربران کمک می کند تا راحت تر بفهمند که چرا برنامه شما به دسترسی درخواستی نیاز دارد.
سند OAuth 2.0 API Scopes حاوی فهرست کاملی از حوزههایی است که ممکن است برای دسترسی به Google API از آنها استفاده کنید.
الزامات خاص زبان
برای اجرای هر یک از نمونه کدهای موجود در این سند، به یک حساب Google، دسترسی به اینترنت و یک مرورگر وب نیاز دارید. اگر از یکی از کتابخانه های سرویس گیرنده API استفاده می کنید، شرایط خاص زبان را نیز در زیر ببینید.
PHP
برای اجرای نمونه کدهای PHP در این سند، به موارد زیر نیاز دارید:
PHP 8.0 یا بالاتر با رابط خط فرمان (CLI) و پسوند JSON نصب شده است.
برای اینکه بتوانید مستقیماً با نقاط پایانی OAuth 2.0 تماس بگیرید، نیازی به نصب هیچ کتابخانه ای ندارید.
دریافت توکن های دسترسی OAuth 2.0
مراحل زیر نشان می دهد که چگونه برنامه شما با سرور OAuth 2.0 Google برای کسب رضایت کاربر برای انجام یک درخواست API از طرف کاربر تعامل دارد. برنامه شما قبل از اینکه بتواند یک درخواست Google API را که نیاز به مجوز کاربر دارد، اجرا کند، باید این رضایت را داشته باشد.
لیست زیر به سرعت این مراحل را خلاصه می کند:
برنامه شما مجوزهای مورد نیاز خود را شناسایی می کند.
برنامه شما کاربر را به همراه لیست مجوزهای درخواستی به Google هدایت می کند.
کاربر تصمیم می گیرد که آیا مجوزها را به برنامه شما اعطا کند یا خیر.
برنامه شما متوجه می شود که کاربر چه تصمیمی گرفته است.
اگر کاربر مجوزهای درخواستی را اعطا کرده باشد، برنامه شما نشانه های مورد نیاز برای درخواست های API را از طرف کاربر بازیابی می کند.
مرحله 1: پارامترهای مجوز را تنظیم کنید
اولین قدم شما ایجاد درخواست مجوز است. این درخواست پارامترهایی را تنظیم می کند که برنامه شما را شناسایی می کند و مجوزهایی را که از کاربر خواسته می شود به برنامه شما اعطا کند، تعریف می کند.
اگر از کتابخانه سرویس گیرنده Google برای احراز هویت و مجوز OAuth 2.0 استفاده می کنید، شیئی را ایجاد و پیکربندی می کنید که این پارامترها را تعریف می کند.
اگر مستقیماً با نقطه پایانی Google OAuth 2.0 تماس بگیرید، یک URL ایجاد میکنید و پارامترها را روی آن URL تنظیم میکنید.
برگه های زیر پارامترهای مجوز پشتیبانی شده را برای برنامه های وب سرور تعریف می کنند. مثالهای خاص زبان همچنین نحوه استفاده از کتابخانه مشتری یا کتابخانه مجوز را برای پیکربندی شیای که آن پارامترها را تنظیم میکند، نشان میدهد.
PHP
قطعه کد زیر یک شی Google\Client() ایجاد می کند که پارامترهای درخواست مجوز را تعریف می کند.
آن شی از اطلاعات فایل client_secret.json شما برای شناسایی برنامه شما استفاده می کند. (برای اطلاعات بیشتر درباره آن فایل، به ایجاد اعتبارنامه مجوز مراجعه کنید.) شی همچنین محدوده هایی را که برنامه شما برای دسترسی به آنها درخواست مجوز می کند و نشانی اینترنتی نقطه پایانی تأیید برنامه شما را شناسایی می کند، که پاسخ سرور OAuth 2.0 Google را مدیریت می کند. در نهایت، کد پارامترهای access_type اختیاری و include_granted_scopes تنظیم می کند.
برای مثال، این کد دسترسی آفلاین و فقط خواندنی به متادیتای Google Drive کاربر و رویدادهای تقویم را درخواست میکند:
use Google\Client;$client = new Client();// Required, call the setAuthConfig function to load authorization credentials from// client_secret.json file.$client->setAuthConfig('client_secret.json');// Required, to set the scope value, call the addScope function$client->addScope([Google\Service\Drive::DRIVE_METADATA_READONLY, Google\Service\Calendar::CALENDAR_READONLY]);// Required, call the setRedirectUri function to specify a valid redirect URI for the// provided client_id$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');// Recommended, offline access will give you both an access and refresh token so that// your app can refresh the access token without user interaction.$client->setAccessType('offline');// Recommended, call the setState function. Using a state value can increase your assurance that// an incoming connection is the result of an authentication request.$client->setState($sample_passthrough_value);// Optional, if your application knows which user is trying to authenticate, it can use this// parameter to provide a hint to the Google Authentication Server.$client->setLoginHint('hint@example.com');// Optional, call the setPrompt function to set "consent" will prompt the user for consent$client->setPrompt('consent');// Optional, call the setIncludeGrantedScopes function with true to enable incremental// authorization$client->setIncludeGrantedScopes(true);
پایتون
قطعه کد زیر از ماژول google-auth-oauthlib.flow برای ساخت درخواست مجوز استفاده می کند.
کد یک شی Flow می سازد که برنامه شما را با استفاده از اطلاعات فایل client_secret.json که پس از ایجاد اعتبارنامه های مجوز دانلود کرده اید شناسایی می کند. این شیء همچنین محدودههایی را که برنامه شما برای دسترسی به آنها درخواست مجوز میکند و نشانی اینترنتی نقطه پایانی تأیید برنامه شما را مشخص میکند، که پاسخ سرور OAuth 2.0 Google را مدیریت میکند. در نهایت، کد پارامترهای access_type اختیاری و include_granted_scopes تنظیم می کند.
برای مثال، این کد دسترسی آفلاین و فقط خواندنی به متادیتای Google Drive کاربر و رویدادهای تقویم را درخواست میکند:
importgoogle.oauth2.credentialsimportgoogle_auth_oauthlib.flow# Required, call the from_client_secrets_file method to retrieve the client ID from a# client_secret.json file. The client ID (from that file) and access scopes are required. (You can# also use the from_client_config method, which passes the client configuration as it originally# appeared in a client secrets file but doesn't access the file itself.)flow=google_auth_oauthlib.flow.Flow.from_client_secrets_file('client_secret.json',scopes=['https://www.googleapis.com/auth/drive.metadata.readonly','https://www.googleapis.com/auth/calendar.readonly'])# Required, indicate where the API server will redirect the user after the user completes# the authorization flow. The redirect URI is required. The value must exactly# match one of the authorized redirect URIs for the OAuth 2.0 client, which you# configured in the API Console. If this value doesn't match an authorized URI,# you will get a 'redirect_uri_mismatch' error.flow.redirect_uri='https://www.example.com/oauth2callback'# Generate URL for request to Google's OAuth 2.0 server.# Use kwargs to set optional request parameters.authorization_url,state=flow.authorization_url(# Recommended, enable offline access so that you can refresh an access token without# re-prompting the user for permission. Recommended for web server apps.access_type='offline',# Optional, enable incremental authorization. Recommended as a best practice.include_granted_scopes='true',# Optional, if your application knows which user is trying to authenticate, it can use this# parameter to provide a hint to the Google Authentication Server.login_hint='hint@example.com',# Optional, set prompt to 'consent' will prompt the user for consentprompt='consent')
روبی
از فایل client_secrets.json که ایجاد کرده اید برای پیکربندی یک شی کلاینت در برنامه خود استفاده کنید. هنگامی که یک شی کلاینت را پیکربندی میکنید، دامنههایی را که برنامه شما باید به آن دسترسی داشته باشد، به همراه URL به نقطه پایانی تأیید برنامه خود، که پاسخ سرور OAuth 2.0 را مدیریت میکند، مشخص میکنید.
برای مثال، این کد دسترسی آفلاین و فقط خواندنی به متادیتای Google Drive کاربر و رویدادهای تقویم را درخواست میکند:
require'googleauth'require'googleauth/web_user_authorizer'require'googleauth/stores/redis_token_store'require'google/apis/drive_v3'require'google/apis/calendar_v3'# Required, call the from_file method to retrieve the client ID from a# client_secret.json file.client_id=Google::Auth::ClientId.from_file('/path/to/client_secret.json')# Required, scope value # Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.scope=['Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY','Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY']# Required, Authorizers require a storage instance to manage long term persistence of# access and refresh tokens.token_store=Google::Auth::Stores::RedisTokenStore.new(redis:Redis.new)# Required, indicate where the API server will redirect the user after the user completes# the authorization flow. The redirect URI is required. The value must exactly# match one of the authorized redirect URIs for the OAuth 2.0 client, which you# configured in the API Console. If this value doesn't match an authorized URI,# you will get a 'redirect_uri_mismatch' error.callback_uri='/oauth2callback'# To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI# from the client_secret.json file. To get these credentials for your application, visit# https://console.cloud.google.com/apis/credentials.authorizer=Google::Auth::WebUserAuthorizer.new(client_id,scope,token_store,callback_uri)
برنامه شما از شی کلاینت برای انجام عملیات OAuth 2.0 استفاده می کند، مانند ایجاد URL های درخواست مجوز و اعمال نشانه های دسترسی به درخواست های HTTP.
Node.js
قطعه کد زیر یک شی google.auth.OAuth2 ایجاد می کند که پارامترهای درخواست مجوز را تعریف می کند.
آن شی از اطلاعات فایل client_secret.json شما برای شناسایی برنامه شما استفاده می کند. برای درخواست مجوز از کاربر برای بازیابی رمز دسترسی، آنها را به صفحه رضایت هدایت می کنید. برای ایجاد URL صفحه رضایت:
const{google}=require('googleapis');constcrypto=require('crypto');constexpress=require('express');constsession=require('express-session');/** * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI * from the client_secret.json file. To get these credentials for your application, visit * https://console.cloud.google.com/apis/credentials. */constoauth2Client=newgoogle.auth.OAuth2(YOUR_CLIENT_ID,YOUR_CLIENT_SECRET,YOUR_REDIRECT_URL);// Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.constscopes=['https://www.googleapis.com/auth/drive.metadata.readonly','https://www.googleapis.com/auth/calendar.readonly'];// Generate a secure random state value.conststate=crypto.randomBytes(32).toString('hex');// Store state in the sessionreq.session.state=state;// Generate a url that asks permissions for the Drive activity and Google Calendar scopeconstauthorizationUrl=oauth2Client.generateAuthUrl({// 'online' (default) or 'offline' (gets refresh_token)access_type:'offline',/** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */scope:scopes,// Enable incremental authorization. Recommended as a best practice.include_granted_scopes:true,// Include the state parameter to reduce the risk of CSRF attacks.state:state});
نکته مهم - refresh_token فقط در اولین مجوز بازگردانده می شود. جزئیات بیشتر در اینجا .
HTTP/REST
نقطه پایانی OAuth 2.0 Google در https://accounts.google.com/o/oauth2/v2/auth است. این نقطه پایانی فقط از طریق HTTPS قابل دسترسی است. اتصالات HTTP ساده رد می شود.
سرور مجوز Google از پارامترهای رشته پرس و جو زیر برای برنامه های وب سرور پشتیبانی می کند:
پارامترها
client_id
مورد نیاز
شناسه مشتری برای برنامه شما. شما می توانید این مقدار را در Cloud ConsoleClients page.
redirect_uri
مورد نیاز
تعیین می کند که سرور API کاربر را پس از تکمیل جریان مجوز توسط کاربر به کجا هدایت می کند. مقدار باید دقیقاً با یکی از URIهای مجاز تغییر مسیر برای مشتری OAuth 2.0 مطابقت داشته باشد که در مشتری خود پیکربندی کرده اید. Cloud ConsoleClients page. اگر این مقدار با URI تغییر مسیر مجاز برای client_id ارائه شده مطابقت نداشته باشد، یک خطای redirect_uri_mismatch دریافت خواهید کرد.
توجه داشته باشید که طرح http یا https ، حروف کوچک و اسلش انتهایی (' / ') همه باید مطابقت داشته باشند.
response_type
مورد نیاز
تعیین می کند که آیا نقطه پایانی Google OAuth 2.0 یک کد مجوز را برمی گرداند یا خیر.
مقدار پارامتر را برای code برنامه های وب سرور تنظیم کنید.
scope
مورد نیاز
فهرستی از محدودههای محدود شده با فضا که منابعی را که برنامه شما میتواند از طرف کاربر به آنها دسترسی داشته باشد، شناسایی میکند. این مقادیر صفحه رضایتی را که Google به کاربر نشان می دهد، نشان می دهد.
Scopes به برنامه شما امکان میدهد فقط درخواست دسترسی به منابع مورد نیاز خود را داشته باشد در حالی که کاربران را قادر میسازد تا میزان دسترسی را که به برنامه شما میدهند کنترل کنند. بنابراین، بین تعداد دامنه های درخواستی و احتمال کسب رضایت کاربر رابطه معکوس وجود دارد.
توصیه میکنیم برنامه شما در صورت امکان، درخواست دسترسی به حوزههای مجوز در زمینه را داشته باشد. با درخواست دسترسی به داده های کاربر در زمینه، از طریق مجوز افزایشی ، به کاربران کمک می کنید تا راحت تر بفهمند که چرا برنامه شما به دسترسی درخواستی نیاز دارد.
access_type
توصیه می شود
نشان می دهد که آیا برنامه شما می تواند نشانه های دسترسی را در زمانی که کاربر در مرورگر حضور ندارد بازخوانی کند یا خیر. مقادیر پارامترهای معتبر online هستند که مقدار پیشفرض است و offline .
اگر زمانی که کاربر در مرورگر حضور ندارد، برنامه شما نیاز به بازخوانی نشانه های دسترسی دارد، مقدار را روی offline تنظیم کنید. این روش تازه کردن نشانه های دسترسی است که در ادامه این سند توضیح داده شده است. این مقدار به سرور مجوز Google دستور میدهد تا برای اولین بار که برنامه شما یک کد مجوز را برای توکنها مبادله میکند، یک نشانه تازهسازی و یک نشانه دسترسی را بازگرداند.
state
توصیه می شود
هر مقدار رشته ای را که برنامه شما برای حفظ وضعیت بین درخواست مجوز شما و پاسخ سرور مجوز استفاده می کند، مشخص می کند. سرور مقدار دقیقی را که شما به عنوان یک جفت name=value در مؤلفه جستجوی URL ( ? ) redirect_uri ارسال می کنید، پس از رضایت کاربر یا رد درخواست دسترسی برنامه شما، برمی گرداند.
شما می توانید از این پارامتر برای اهداف مختلفی مانند هدایت کاربر به منبع صحیح در برنامه خود، ارسال nonces و کاهش جعل درخواست بین سایتی استفاده کنید. از آنجایی که redirect_uri شما قابل حدس زدن است، استفاده از یک مقدار state می تواند اطمینان شما را از اینکه اتصال ورودی نتیجه درخواست احراز هویت است افزایش دهد. اگر یک رشته تصادفی ایجاد کنید یا هش یک کوکی یا مقدار دیگری را رمزگذاری کنید که وضعیت کلاینت را نشان میدهد، میتوانید پاسخ را اعتبارسنجی کنید تا علاوه بر این اطمینان حاصل کنید که درخواست و پاسخ از یک مرورگر منشأ گرفتهاند و از حملاتی مانند جعل درخواست بینسایتی محافظت میکنند. برای مثالی از نحوه ایجاد و تأیید یک نشانه state ، به اسناد OpenID Connect مراجعه کنید.
include_granted_scopes
اختیاری
برنامهها را قادر میسازد تا از مجوز افزایشی برای درخواست دسترسی به دامنههای اضافی در زمینه استفاده کنند. اگر مقدار این پارامتر را روی true تنظیم کنید و درخواست مجوز اعطا شود، رمز دسترسی جدید همچنین دامنههایی را که کاربر قبلاً به برنامه دسترسی داده است، پوشش میدهد. برای مثال به بخش مجوز افزایشی مراجعه کنید.
enable_granular_consent
اختیاری
پیش فرض ها به true اگر روی false تنظیم شود، مجوزهای دقیقتر حساب Google برای شناسههای سرویس گیرنده OAuth ایجاد شده قبل از سال 2019 غیرفعال میشود. برای شناسههای سرویس گیرنده OAuth جدیدتر تأثیری ندارد، زیرا مجوزهای دقیقتر همیشه برای آنها فعال است.
وقتی Google مجوزهای گرانول را برای یک برنامه فعال می کند، این پارامتر دیگر هیچ تاثیری نخواهد داشت.
login_hint
اختیاری
اگر برنامه شما بداند که کدام کاربر در حال تلاش برای احراز هویت است، میتواند از این پارامتر برای ارائه راهنمایی به سرور احراز هویت Google استفاده کند. سرور از راهنمایی برای ساده سازی جریان ورود استفاده می کند یا با پر کردن فیلد ایمیل در فرم ورود به سیستم یا با انتخاب جلسه چند ورود مناسب.
مقدار پارامتر را به آدرس ایمیل یا شناسه sub که معادل شناسه گوگل کاربر است تنظیم کنید.
prompt
اختیاری
فهرستی با فاصله محدود و حساس به حروف کوچک و بزرگ از درخواستها برای ارائه کاربر. اگر این پارامتر را مشخص نکنید، تنها اولین باری که پروژه شما درخواست دسترسی می کند، از کاربر خواسته می شود. برای اطلاعات بیشتر به درخواست رضایت مجدد مراجعه کنید.
مقادیر ممکن عبارتند از:
none
هیچ صفحه تایید یا رضایتی را نمایش ندهید. نباید با مقادیر دیگر مشخص شود.
consent
درخواست رضایت از کاربر
select_account
از کاربر بخواهید یک حساب کاربری را انتخاب کند.
مرحله 2: به سرور OAuth 2.0 گوگل هدایت شوید
کاربر را به سرور OAuth 2.0 Google هدایت کنید تا فرآیند احراز هویت و مجوز آغاز شود. به طور معمول، این زمانی اتفاق می افتد که برنامه شما ابتدا نیاز به دسترسی به داده های کاربر دارد. در مورد مجوز افزایشی ، این مرحله همچنین زمانی رخ می دهد که برنامه شما ابتدا نیاز به دسترسی به منابع اضافی دارد که هنوز مجوز دسترسی به آنها را ندارد.
PHP
یک URL برای درخواست دسترسی از سرور OAuth 2.0 Google ایجاد کنید:
پس از ایجاد URL درخواست، کاربر را به آن هدایت کنید.
سرور OAuth 2.0 Google کاربر را احراز هویت می کند و از کاربر رضایت می گیرد تا برنامه شما به محدوده های درخواستی دسترسی پیدا کند. پاسخ با استفاده از URL تغییر مسیری که مشخص کرده اید به برنامه شما ارسال می شود.
مرحله 3: گوگل رضایت کاربر را درخواست می کند
در این مرحله، کاربر تصمیم می گیرد که آیا به اپلیکیشن شما دسترسی درخواستی را بدهد یا خیر. در این مرحله، گوگل یک پنجره رضایت را نمایش می دهد که نام برنامه شما و سرویس های Google API را نشان می دهد که درخواست اجازه دسترسی به آن ها را با اعتبار مجوز کاربر و خلاصه ای از محدوده های دسترسی که باید اعطا شود را نشان می دهد. سپس کاربر می تواند با اعطای دسترسی به یک یا چند حوزه درخواست شده توسط برنامه شما موافقت کند یا درخواست را رد کند.
برنامه شما در این مرحله نیازی به انجام هیچ کاری ندارد زیرا منتظر پاسخ سرور OAuth 2.0 Google است که نشان می دهد آیا دسترسی اعطا شده است یا خیر. این پاسخ در مرحله زیر توضیح داده شده است.
خطاها
درخواستها به نقطه پایانی مجوز OAuth 2.0 Google ممکن است پیامهای خطای کاربر را بهجای جریانهای احراز هویت و مجوز مورد انتظار نمایش دهند. کدهای خطای رایج و راهکارهای پیشنهادی در زیر فهرست شدهاند.
admin_policy_enforced
حساب Google به دلیل خطمشیهای سرپرست Google Workspace نمیتواند یک یا چند محدوده درخواستی را تأیید کند. برای اطلاعات بیشتر در مورد اینکه چگونه یک سرپرست میتواند دسترسی به همه حوزهها یا محدودههای حساس و محدود را تا زمانی که صراحتاً به شناسه مشتری OAuth شما اعطا نشود، به مقاله راهنمای Google Workspace Admin مراجعه کنید.
disallowed_useragent
نقطه پایانی مجوز در داخل یک عامل کاربر تعبیهشده نمایش داده میشود که توسط خطمشیهای OAuth 2.0 Google مجاز نیست.
شناسه مشتری OAuth در درخواست بخشی از پروژه ای است که دسترسی به حساب های Google را در یک سازمان Google Cloud خاص محدود می کند. برای اطلاعات بیشتر در مورد این گزینه پیکربندی، بخش نوع کاربر را در مقاله راهنمای تنظیم صفحه رضایت OAuth خود ببینید.
invalid_client
راز مشتری OAuth نادرست است. پیکربندی سرویس گیرنده OAuth را مرور کنید، از جمله شناسه مشتری و راز استفاده شده برای این درخواست.
deleted_client
مشتری OAuth که برای درخواست استفاده می شود حذف شده است. حذف می تواند به صورت دستی یا خودکار در مورد کلاینت های استفاده نشده اتفاق بیفتد. مشتریان حذف شده را می توان ظرف 30 روز پس از حذف بازیابی کرد. بیشتر بدانید .
invalid_grant
هنگام بازخوانی یک نشانه دسترسی یا استفاده از مجوز افزایشی ، ممکن است نشانه منقضی شده باشد یا باطل شده باشد. مجدداً کاربر را احراز هویت کنید و برای دریافت توکن های جدید رضایت کاربر را بخواهید. اگر همچنان این خطا را مشاهده می کنید، مطمئن شوید که برنامه شما به درستی پیکربندی شده است و از نشانه ها و پارامترهای صحیح در درخواست خود استفاده می کنید. در غیر این صورت، حساب کاربری ممکن است حذف یا غیرفعال شده باشد.
redirect_uri_mismatch
redirect_uri ارسال شده در درخواست مجوز با URI تغییر مسیر مجاز برای شناسه مشتری OAuth مطابقت ندارد. URIهای مجاز تغییر مسیر را در Google Cloud ConsoleClients page.
پارامتر redirect_uri ممکن است به جریان OAuth خارج از باند (OOB) اشاره داشته باشد که منسوخ شده است و دیگر پشتیبانی نمی شود. برای به روز رسانی ادغام خود به راهنمای مهاجرت مراجعه کنید.
invalid_request
مشکلی در درخواستی که دادید وجود داشت. این می تواند به دلایل مختلفی باشد:
درخواست به درستی قالب بندی نشده بود
درخواست فاقد پارامترهای لازم بود
این درخواست از روش مجوزی استفاده میکند که Google از آن پشتیبانی نمیکند. بررسی کنید که ادغام OAuth شما از یک روش ادغام توصیه شده استفاده می کند
مرحله 4: پاسخ سرور OAuth 2.0 را مدیریت کنید
سرور OAuth 2.0 با استفاده از URL مشخص شده در درخواست به درخواست دسترسی برنامه شما پاسخ می دهد.
اگر کاربر درخواست دسترسی را تأیید کند، پاسخ حاوی یک کد مجوز است. اگر کاربر درخواست را تایید نکند، پاسخ حاوی یک پیام خطا است. کد مجوز یا پیغام خطایی که به وب سرور بازگردانده می شود، مانند شکل زیر در رشته کوئری ظاهر می شود:
میتوانید این جریان را با کلیک بر روی نشانی اینترنتی نمونه زیر آزمایش کنید، که درخواست دسترسی فقط خواندنی برای مشاهده فراداده فایلها در Google Drive شما و دسترسی فقط خواندنی برای مشاهده رویدادهای Google Calendar شما را دارد:
پس از تکمیل جریان OAuth 2.0، باید به http://localhost/oauth2callback هدایت شوید، که احتمالاً خطای 404 NOT FOUND ایجاد می کند، مگر اینکه دستگاه محلی شما فایلی را در آن آدرس ارائه کند. مرحله بعدی جزئیات بیشتری را در مورد اطلاعات بازگردانده شده در URI هنگامی که کاربر به برنامه شما هدایت می شود ارائه می دهد.
مرحله 5: کد مجوز را برای بهروزرسانی و دسترسی به توکنها مبادله کنید
پس از اینکه وب سرور کد مجوز را دریافت کرد، می تواند کد مجوز را با یک نشانه دسترسی مبادله کند.
PHP
برای تبادل یک کد مجوز برای یک نشانه دسترسی، از روش fetchAccessTokenWithAuthCode استفاده کنید:
در صفحه پاسخ به تماس خود، از کتابخانه google-auth برای تأیید پاسخ سرور مجوز استفاده کنید. سپس، از روش flow.fetch_token برای مبادله کد مجوز در آن پاسخ برای یک نشانه دسترسی استفاده کنید:
state=flask.session['state']flow=google_auth_oauthlib.flow.Flow.from_client_secrets_file('client_secret.json',scopes=['https://www.googleapis.com/auth/drive.metadata.readonly'],state=state)flow.redirect_uri=flask.url_for('oauth2callback',_external=True)authorization_response=flask.request.urlflow.fetch_token(authorization_response=authorization_response)# Store the credentials in browser session storage, but for security: client_id, client_secret,# and token_uri are instead stored only on the backend server.credentials=flow.credentialsflask.session['credentials']={'token':credentials.token,'refresh_token':credentials.refresh_token,'granted_scopes':credentials.granted_scopes}
روبی
در صفحه پاسخ به تماس خود، از کتابخانه googleauth برای تأیید پاسخ سرور مجوز استفاده کنید. از روش authorizer.handle_auth_callback_deferred برای ذخیره کد مجوز استفاده کنید و به آدرس اینترنتی که در ابتدا درخواست مجوز کرده بود، برگردید. این امر با ذخیره موقت نتایج در جلسه کاربر، تبادل کد را به تعویق می اندازد.
برای تبادل یک کد مجوز برای یک نشانه دسترسی، از روش getToken استفاده کنید:
consturl=require('url');// Receive the callback from Google's OAuth 2.0 server.app.get('/oauth2callback',async(req,res)=>{letq=url.parse(req.url,true).query;if(q.error){// An error response e.g. error=access_deniedconsole.log('Error:'+q.error);}elseif(q.state!==req.session.state){//check state valueconsole.log('State mismatch. Possible CSRF attack');res.end('State mismatch. Possible CSRF attack');}else{// Get access and refresh tokens (if access_type is offline)let{tokens}=awaitoauth2Client.getToken(q.code);oauth2Client.setCredentials(tokens);});
HTTP/REST
برای تبادل کد مجوز برای یک نشانه دسترسی، با https://oauth2.googleapis.com/token endpoint تماس بگیرید و پارامترهای زیر را تنظیم کنید:
فیلدها
client_id
شناسه مشتری به دست آمده از Cloud ConsoleClients page.
client_secret
راز مشتری به دست آمده از Cloud ConsoleClients page.
Google به این درخواست با برگرداندن یک شی JSON که حاوی یک نشانه دسترسی کوتاه مدت و یک نشانه تازهسازی است، پاسخ میدهد. توجه داشته باشید که رمز تازهسازی تنها در صورتی برگردانده میشود که برنامه شما در درخواست اولیه سرور مجوز Google، پارامتر access_type را روی offline تنظیم کند.
پاسخ شامل فیلدهای زیر است:
فیلدها
access_token
رمزی که برنامه شما برای تأیید درخواست Google API ارسال می کند.
expires_in
طول عمر باقیمانده رمز دسترسی در ثانیه.
refresh_token
توکنی که می توانید از آن برای به دست آوردن یک نشانه دسترسی جدید استفاده کنید. نشانههای تازهسازی تا زمانی که کاربر دسترسی را لغو نکند یا نشانهی تازهسازی منقضی شود معتبر هستند. باز هم، این فیلد تنها در صورتی در این پاسخ وجود دارد که در درخواست اولیه به سرور مجوز Google، پارامتر access_type را روی offline تنظیم کنید.
refresh_token_expires_in
طول عمر باقیمانده نشانه رفرش در ثانیه. این مقدار فقط زمانی تنظیم میشود که کاربر دسترسی مبتنی بر زمان را اعطا کند.
scope
دامنه دسترسی اعطا شده توسط access_token به صورت لیستی از رشته های حساس به حروف کوچک و کوچک با فاصله بیان می شود.
token_type
نوع رمز برگشتی. در این زمان، مقدار این فیلد همیشه روی Bearer تنظیم می شود.
هنگام تعویض کد مجوز برای یک نشانه دسترسی، ممکن است به جای پاسخ مورد انتظار با خطای زیر مواجه شوید. کدهای خطای رایج و راهکارهای پیشنهادی در زیر فهرست شدهاند.
invalid_grant
کد مجوز ارائه شده نامعتبر است یا در قالب اشتباه است. با راهاندازی مجدد فرآیند OAuth، یک کد جدید درخواست کنید تا دوباره رضایت کاربر را بخواهد.
مرحله 6: بررسی کنید که کاربران چه محدوده هایی را اعطا کرده اند
هنگام درخواست چندین مجوز (محدوده)، کاربران ممکن است به برنامه شما اجازه دسترسی به همه آنها را ندهند. برنامه شما باید بررسی کند که کدام حوزهها واقعاً اعطا شدهاند و موقعیتهایی را که در آن برخی از مجوزها رد میشوند، بهخوبی مدیریت کند، معمولاً با غیرفعال کردن ویژگیهایی که به آن محدودههای رد شده متکی هستند.
با این حال، استثناهایی وجود دارد. برنامههای Google Workspace Enterprise با تفویض اختیار در سطح دامنه ، یا برنامههایی که بهعنوان «معتمد» علامتگذاری شدهاند، صفحه رضایت مجوزهای جزئی را دور میزنند. برای این برنامهها، کاربران صفحه رضایت جزئیات را نمیبینند. در عوض، برنامه شما یا همه محدوده های درخواستی را دریافت می کند یا هیچ کدام را دریافت نمی کند.
برای بررسی اینکه کاربر کدام حوزه را اعطا کرده است، از متد getGrantedScope() استفاده کنید:
// Space-separated string of granted scopes if it exists, otherwise null.$granted_scopes = $client->getOAuth2Service()->getGrantedScope();// Determine which scopes user granted and build a dictionary$granted_scopes_dict = [ 'Drive' => str_contains($granted_scopes, Google\Service\Drive::DRIVE_METADATA_READONLY), 'Calendar' => str_contains($granted_scopes, Google\Service\Calendar::CALENDAR_READONLY)];
پایتون
شیء credentials برگشتی دارای ویژگی granted_scopes است که لیستی از دامنه هایی است که کاربر به برنامه شما اعطا کرده است.
هنگام درخواست چندین دامنه به طور همزمان، بررسی کنید که کدام محدوده از طریق ویژگی scope شی credentials اعطا شده است.
# User authorized the request. Now, check which scopes were granted.ifcredentials.scope.include?(Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY)# User authorized read-only Drive activity permission.# Calling the APIs, etcelse# User didn't authorize read-only Drive activity permission.# Update UX and application accordinglyend# Check if user authorized Calendar read permission.ifcredentials.scope.include?(Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY)# User authorized Calendar read permission.# Calling the APIs, etc.else# User didn't authorize Calendar read permission.# Update UX and application accordinglyend
Node.js
هنگام درخواست چندین دامنه به طور همزمان، بررسی کنید که کدام محدوده از طریق ویژگی scope شی tokens اعطا شده است.
// User authorized the request. Now, check which scopes were granted.if(tokens.scope.includes('https://www.googleapis.com/auth/drive.metadata.readonly')){// User authorized read-only Drive activity permission.// Calling the APIs, etc.}else{// User didn't authorize read-only Drive activity permission.// Update UX and application accordingly}// Check if user authorized Calendar read permission.if(tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly')){// User authorized Calendar read permission.// Calling the APIs, etc.}else{// User didn't authorize Calendar read permission.// Update UX and application accordingly}
HTTP/REST
برای بررسی اینکه آیا کاربر به برنامه شما اجازه دسترسی به یک محدوده خاص را داده است یا خیر، فیلد scope را در پاسخ نشانه دسترسی بررسی کنید. دامنه دسترسی اعطا شده توسط access_token به صورت لیستی از رشته های حساس به حروف کوچک و کوچک با فاصله بیان می شود.
به عنوان مثال، نمونه پاسخ نشانه دسترسی زیر نشان می دهد که کاربر به برنامه شما اجازه دسترسی به فعالیت Drive فقط خواندنی و رویدادهای تقویم را داده است:
با انجام مراحل زیر از کد دسترسی برای فراخوانی APIهای Google استفاده کنید:
اگر نیاز به اعمال یک نشانه دسترسی به یک شی جدید Google\Client دارید - برای مثال، اگر نشانه دسترسی را در یک جلسه کاربر ذخیره کرده اید - از روش setAccessToken استفاده کنید:
$client->setAccessToken($access_token);
یک شیء سرویس برای API که می خواهید فراخوانی کنید بسازید. شما با ارائه یک شیء مجاز Google\Client به سازنده برای API که می خواهید فراخوانی کنید، یک شیء سرویس می سازید. به عنوان مثال، برای فراخوانی Drive API:
$drive = new Google\Service\Drive($client);
با استفاده از رابط ارائه شده توسط شی سرویس، درخواست هایی را به سرویس API ارسال کنید. به عنوان مثال، برای فهرست کردن فایلها در Google Drive کاربر تأیید شده:
$files = $drive->files->listFiles(array());
پایتون
پس از به دست آوردن یک نشانه دسترسی، برنامه شما میتواند از آن نشانه برای مجوز درخواستهای API از طرف یک حساب کاربری یا حساب سرویس خاص استفاده کند. برای ایجاد یک شیء سرویس برای API که می خواهید فراخوانی کنید، از اعتبارنامه های مجوز خاص کاربر استفاده کنید و سپس از آن شی برای ایجاد درخواست های مجاز API استفاده کنید.
یک شیء سرویس برای API که می خواهید فراخوانی کنید بسازید. شما با فراخوانی روش build کتابخانه googleapiclient.discovery با نام و نسخه API و اعتبار کاربر، یک شیء سرویس میسازید: به عنوان مثال، برای فراخوانی نسخه 3 Drive API:
با استفاده از رابط ارائه شده توسط شی سرویس، درخواست هایی را به سرویس API ارسال کنید. به عنوان مثال، برای فهرست کردن فایلها در Google Drive کاربر تأیید شده:
files=drive.files().list().execute()
روبی
پس از به دست آوردن یک نشانه دسترسی، برنامه شما میتواند از آن رمز برای درخواست API از طرف یک حساب کاربری یا حساب سرویس استفاده کند. برای ایجاد یک شیء سرویس برای API که می خواهید فراخوانی کنید، از اعتبارنامه های مجوز خاص کاربر استفاده کنید و سپس از آن شی برای ایجاد درخواست های مجاز API استفاده کنید.
یک شیء سرویس برای API که می خواهید فراخوانی کنید بسازید. برای مثال، برای فراخوانی نسخه 3 Drive API:
drive=Google::Apis::DriveV3::DriveService.new
اعتبارنامه را روی سرویس تنظیم کنید:
drive.authorization=credentials
با استفاده از رابط ارائه شده توسط شی سرویس، درخواست هایی را به سرویس API ارسال کنید. به عنوان مثال، برای فهرست کردن فایلها در Google Drive کاربر تأیید شده:
files=drive.list_files
متناوباً، مجوز میتواند بر اساس هر روش با ارائه پارامتر options به یک روش ارائه شود:
پس از به دست آوردن یک نشانه دسترسی و تنظیم آن بر روی شی OAuth2 ، از شی برای فراخوانی API های Google استفاده کنید. برنامه شما میتواند از آن نشانه برای تأیید درخواستهای API از طرف یک حساب کاربری یا حساب سرویس خاص استفاده کند. برای API که می خواهید با آن تماس بگیرید ، یک شیء خدمات بسازید. به عنوان مثال ، کد زیر از API Google Drive برای لیست نام های پرونده در درایو کاربر استفاده می کند.
const{google}=require('googleapis');// Example of using Google Drive API to list filenames in user's Drive.constdrive=google.drive('v3');drive.files.list({auth:oauth2Client,pageSize:10,fields:'nextPageToken, files(id, name)',},(err1,res1)=>{if(err1)returnconsole.log('The API returned an error: '+err1);constfiles=res1.data.files;if(files.length){console.log('Files:');files.map((file)=>{console.log(`${file.name} (${file.id})`);});}else{console.log('No files found.');}});
http/استراحت
پس از به دست آوردن برنامه دسترسی ، می توانید در صورت اعطای دامنه (های) دسترسی مورد نیاز API ، از Token برای برقراری تماس با Google API به نمایندگی از یک حساب کاربری خاص استفاده کنید. برای انجام این کار ، نشانه دسترسی را در درخواست API با استفاده از یک پارامتر پرس و جو access_token یا یک Authorization HTTP Bearer Header درج کنید. در صورت امکان ، هدر HTTP ارجح است ، زیرا رشته های پرس و جو در سیاهههای مربوط به سرور قابل مشاهده هستند. در بیشتر موارد می توانید از یک کتابخانه مشتری برای تنظیم تماس های خود به Google API استفاده کنید (به عنوان مثال هنگام تماس با API Files Drive Files ).
می توانید تمام API های Google را امتحان کرده و دامنه آنها را در زمین بازی OAUTH 2.0 مشاهده کنید.
http نمونه هایی دریافت کنید
تماس با drive.files Endpoint (API Files Drive Files) با استفاده از Authorization: Bearer ممکن است مانند موارد زیر باشد. توجه داشته باشید که باید نشانه دسترسی خود را مشخص کنید:
GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token
در اینجا یک تماس به همان API برای کاربر معتبر با استفاده از پارامتر رشته access_token Query:
GET https://www.googleapis.com/drive/v2/files?access_token=access_token
نمونه های curl
می توانید این دستورات را با برنامه خط فرمان curl آزمایش کنید. در اینجا مثالی آورده شده است که از گزینه هدر HTTP استفاده می کند (ترجیحی):
مثال زیر لیستی از پرونده های با فرمت JSON را در Google Drive کاربر پس از تأیید کاربر چاپ می کند و رضایت می دهد تا برنامه برای دسترسی به ابرداده درایو کاربر.
PHP
برای اجرای این مثال:
در API ConsoleURL دستگاه محلی را به لیست URL های تغییر مسیر اضافه کنید. به عنوان مثال ، http://localhost:8080 اضافه کنید.
یک فهرست جدید ایجاد کنید و به آن تغییر دهید. به عنوان مثال:
mkdir ~/php-oauth2-example
cd ~/php-oauth2-example
Files index.php و oauth2callback.php را با محتوای زیر ایجاد کنید.
مثال را با سرور تست داخلی PHP اجرا کنید:
php -S localhost:8080 ~/php-oauth2-example
index.php
<?phprequire_once __DIR__.'/vendor/autoload.php';session_start();$client = new Google\Client();$client->setAuthConfig('client_secret.json');// User granted permission as an access token is in the session.if (isset($_SESSION['access_token']) && $_SESSION['access_token']){ $client->setAccessToken($_SESSION['access_token']); // Check if user granted Drive permission if ($_SESSION['granted_scopes_dict']['Drive']) { echo "Drive feature is enabled."; echo "</br>"; $drive = new Drive($client); $files = array(); $response = $drive->files->listFiles(array()); foreach ($response->files as $file) { echo "File: " . $file->name . " (" . $file->id . ")"; echo "</br>"; } } else { echo "Drive feature is NOT enabled."; echo "</br>"; } // Check if user granted Calendar permission if ($_SESSION['granted_scopes_dict']['Calendar']) { echo "Calendar feature is enabled."; echo "</br>"; } else { echo "Calendar feature is NOT enabled."; echo "</br>"; }}else{ // Redirect users to outh2call.php which redirects users to Google OAuth 2.0 $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php'; header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));}?>
oauth2callback.php
<?phprequire_once __DIR__.'/vendor/autoload.php';session_start();$client = new Google\Client();// Required, call the setAuthConfig function to load authorization credentials from// client_secret.json file.$client->setAuthConfigFile('client_secret.json');$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST']. $_SERVER['PHP_SELF']);// Required, to set the scope value, call the addScope function.$client->addScope([Google\Service\Drive::DRIVE_METADATA_READONLY, Google\Service\Calendar::CALENDAR_READONLY]);// Enable incremental authorization. Recommended as a best practice.$client->setIncludeGrantedScopes(true);// Recommended, offline access will give you both an access and refresh token so that// your app can refresh the access token without user interaction.$client->setAccessType("offline");// Generate a URL for authorization as it doesn't contain code and errorif (!isset($_GET['code']) && !isset($_GET['error'])){ // Generate and set state value $state = bin2hex(random_bytes(16)); $client->setState($state); $_SESSION['state'] = $state; // Generate a url that asks permissions. $auth_url = $client->createAuthUrl(); header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));}// User authorized the request and authorization code is returned to exchange access and// refresh tokens.if (isset($_GET['code'])){ // Check the state value if (!isset($_GET['state']) || $_GET['state'] !== $_SESSION['state']) { die('State mismatch. Possible CSRF attack.'); } // Get access and refresh tokens (if access_type is offline) $token = $client->fetchAccessTokenWithAuthCode($_GET['code']); /** Save access and refresh token to the session variables. * ACTION ITEM: In a production app, you likely want to save the * refresh token in a secure persistent storage instead. */ $_SESSION['access_token'] = $token; $_SESSION['refresh_token'] = $client->getRefreshToken(); // Space-separated string of granted scopes if it exists, otherwise null. $granted_scopes = $client->getOAuth2Service()->getGrantedScope(); // Determine which scopes user granted and build a dictionary $granted_scopes_dict = [ 'Drive' => str_contains($granted_scopes, Google\Service\Drive::DRIVE_METADATA_READONLY), 'Calendar' => str_contains($granted_scopes, Google\Service\Calendar::CALENDAR_READONLY) ]; $_SESSION['granted_scopes_dict'] = $granted_scopes_dict; $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/'; header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));}// An error response e.g. error=access_deniedif (isset($_GET['error'])){ echo "Error: ". $_GET['error'];}?>
پایتون
این مثال از چارچوب Flask استفاده می کند. این برنامه یک برنامه وب را در http://localhost:8080 اجرا می کند که به شما امکان می دهد جریان OAuth 2.0 را آزمایش کنید. اگر به آن URL بروید ، باید پنج پیوند را ببینید:
Call Drive API: این لینک به صفحه ای اشاره دارد که اگر کاربران مجوز را صادر کنند ، می خواهد یک درخواست API نمونه را اجرا کند. در صورت لزوم ، جریان مجوز را شروع می کند. در صورت موفقیت ، صفحه پاسخ API را نشان می دهد.
صفحه مسخره برای تماس با تقویم API: این لینک به یک صفحه اصلی اشاره دارد که در صورت اعطای مجوز ، سعی در اجرای درخواست API تقویم نمونه دارد. در صورت لزوم ، جریان مجوز را شروع می کند. در صورت موفقیت ، صفحه پاسخ API را نشان می دهد.
آزمایش جریان مستقیم مستقیم: این پیوند به صفحه ای اشاره دارد که سعی می کند کاربر را از طریق جریان مجوز ارسال کند. برنامه درخواست ارسال درخواست های مجاز API از طرف کاربر را می دهد.
اعتبارنامه های فعلی را لغو کنید: این پیوند به صفحه ای اشاره دارد که مجوزهایی را که کاربر قبلاً به برنامه داده است ، ابطال می کند .
اعتبارنامه جلسه Flask را پاک کنید: این پیوند اعتبار مجوزهای مجوز را که در جلسه Flask ذخیره می شود ، پاک می کند. این امر به شما امکان می دهد اگر کاربرانی که قبلاً مجوز برنامه شما را داده بود ، سعی در اجرای درخواست API در یک جلسه جدید داشته باشد ، چه اتفاقی می افتد. همچنین به شما امکان می دهد اگر کاربر مجوزهای اعطا شده به برنامه شما را لغو کرده باشد ، پاسخ API شما را دریافت می کند ، و برنامه شما هنوز هم سعی کرده است با یک نشانه دسترسی ابطال شده درخواست کند.
# -*- coding: utf-8 -*-importosimportflaskimportjsonimportrequestsimportgoogle.oauth2.credentialsimportgoogle_auth_oauthlib.flowimportgoogleapiclient.discovery# This variable specifies the name of a file that contains the OAuth 2.0# information for this application, including its client_id and client_secret.CLIENT_SECRETS_FILE="client_secret.json"# The OAuth 2.0 access scope allows for access to the# authenticated user's account and requires requests to use an SSL connection.SCOPES=['https://www.googleapis.com/auth/drive.metadata.readonly','https://www.googleapis.com/auth/calendar.readonly']API_SERVICE_NAME='drive'API_VERSION='v2'app=flask.Flask(__name__)# Note: A secret key is included in the sample so that it works.# If you use this code in your application, replace this with a truly secret# key. See https://flask.palletsprojects.com/quickstart/#sessions.app.secret_key='REPLACE ME - this value is here as a placeholder.'@app.route('/')defindex():returnprint_index_table()@app.route('/drive')defdrive_api_request():if'credentials'notinflask.session:returnflask.redirect('authorize')features=flask.session['features']iffeatures['drive']:# Load client secrets from the server-side file.withopen(CLIENT_SECRETS_FILE,'r')asf:client_config=json.load(f)['web']# Load user-specific credentials from browser session storage.session_credentials=flask.session['credentials']# Reconstruct the credentials object.credentials=google.oauth2.credentials.Credentials(refresh_token=session_credentials.get('refresh_token'),scopes=session_credentials.get('granted_scopes'),token=session_credentials.get('token'),client_id=client_config.get('client_id'),client_secret=client_config.get('client_secret'),token_uri=client_config.get('token_uri'))drive=googleapiclient.discovery.build(API_SERVICE_NAME,API_VERSION,credentials=credentials)files=drive.files().list().execute()# Save credentials back to session in case access token was refreshed.flask.session['credentials']=credentials_to_dict(credentials)returnflask.jsonify(**files)else:# User didn't authorize read-only Drive activity permission.return'<p>Drive feature is not enabled.</p>'@app.route('/calendar')defcalendar_api_request():if'credentials'notinflask.session:returnflask.redirect('authorize')features=flask.session['features']iffeatures['calendar']:# User authorized Calendar read permission.# Calling the APIs, etc.return('<p>User granted the Google Calendar read permission. '+'This sample code does not include code to call Calendar</p>')else:# User didn't authorize Calendar read permission.# Update UX and application accordinglyreturn'<p>Calendar feature is not enabled.</p>'@app.route('/authorize')defauthorize():# Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps.flow=google_auth_oauthlib.flow.Flow.from_client_secrets_file(CLIENT_SECRETS_FILE,scopes=SCOPES)# The URI created here must exactly match one of the authorized redirect URIs# for the OAuth 2.0 client, which you configured in the API Console. If this# value doesn't match an authorized URI, you will get a 'redirect_uri_mismatch'# error.flow.redirect_uri=flask.url_for('oauth2callback',_external=True)authorization_url,state=flow.authorization_url(# Enable offline access so that you can refresh an access token without# re-prompting the user for permission. Recommended for web server apps.access_type='offline',# Enable incremental authorization. Recommended as a best practice.include_granted_scopes='true')# Store the state so the callback can verify the auth server response.flask.session['state']=statereturnflask.redirect(authorization_url)@app.route('/oauth2callback')defoauth2callback():# Specify the state when creating the flow in the callback so that it can# verified in the authorization server response.state=flask.session['state']flow=google_auth_oauthlib.flow.Flow.from_client_secrets_file(CLIENT_SECRETS_FILE,scopes=SCOPES,state=state)flow.redirect_uri=flask.url_for('oauth2callback',_external=True)# Use the authorization server's response to fetch the OAuth 2.0 tokens.authorization_response=flask.request.urlflow.fetch_token(authorization_response=authorization_response)# Store credentials in the session.# ACTION ITEM: In a production app, you likely want to save these# credentials in a persistent database instead.credentials=flow.credentialscredentials=credentials_to_dict(credentials)flask.session['credentials']=credentials# Check which scopes user grantedfeatures=check_granted_scopes(credentials)flask.session['features']=featuresreturnflask.redirect('/')@app.route('/revoke')defrevoke():if'credentials'notinflask.session:return('You need to <a href="/authorize">authorize</a> before '+'testing the code to revoke credentials.')# Load client secrets from the server-side file.withopen(CLIENT_SECRETS_FILE,'r')asf:client_config=json.load(f)['web']# Load user-specific credentials from the session.session_credentials=flask.session['credentials']# Reconstruct the credentials object.credentials=google.oauth2.credentials.Credentials(refresh_token=session_credentials.get('refresh_token'),scopes=session_credentials.get('granted_scopes'),token=session_credentials.get('token'),client_id=client_config.get('client_id'),client_secret=client_config.get('client_secret'),token_uri=client_config.get('token_uri'))revoke=requests.post('https://oauth2.googleapis.com/revoke',params={'token':credentials.token},headers={'content-type':'application/x-www-form-urlencoded'})status_code=getattr(revoke,'status_code')ifstatus_code==200:# Clear the user's session credentials after successful revocationif'credentials'inflask.session:delflask.session['credentials']delflask.session['features']return('Credentials successfully revoked.'+print_index_table())else:return('An error occurred.'+print_index_table())@app.route('/clear')defclear_credentials():if'credentials'inflask.session:delflask.session['credentials']return('Credentials have been cleared.<br><br>'+print_index_table())defcredentials_to_dict(credentials):return{'token':credentials.token,'refresh_token':credentials.refresh_token,'granted_scopes':credentials.granted_scopes}defcheck_granted_scopes(credentials):features={}if'https://www.googleapis.com/auth/drive.metadata.readonly'incredentials['granted_scopes']:features['drive']=Trueelse:features['drive']=Falseif'https://www.googleapis.com/auth/calendar.readonly'incredentials['granted_scopes']:features['calendar']=Trueelse:features['calendar']=Falsereturnfeaturesdefprint_index_table():return('<table>'+'<tr><td><a href="/authorize">Test the auth flow directly</a></td>'+'<td>Go directly to the authorization flow. If there are stored '+' credentials, you still might not be prompted to reauthorize '+' the application.</td></tr>'+'<tr><td><a href="/drive">Call Drive API directly</a></td>'+'<td> Use stored credentials to call the API, you still might not be prompted to reauthorize '+' the application.</td></tr>'+'<tr><td><a href="/calendar">Call Calendar API directly</a></td>'+'<td> Use stored credentials to call the API, you still might not be prompted to reauthorize '+' the application.</td></tr>'+'<tr><td><a href="/revoke">Revoke current credentials</a></td>'+'<td>Revoke the access token associated with the current user '+' session. After revoking credentials, if you go to the test '+' page, you should see an <code>invalid_grant</code> error.'+'</td></tr>'+'<tr><td><a href="/clear">Clear Flask session credentials</a></td>'+'<td>Clear the access token currently stored in the user session. '+' After clearing the token, if you <a href="/authorize">authorize</a> '+' again, you should go back to the auth flow.'+'</td></tr></table>')if__name__=='__main__':# When running locally, disable OAuthlib's HTTPs verification.# ACTION ITEM for developers:# When running in production *do not* leave this option enabled.os.environ['OAUTHLIB_INSECURE_TRANSPORT']='1'# This disables the requested scopes and granted scopes check.# If users only grant partial request, the warning would not be thrown.os.environ['OAUTHLIB_RELAX_TOKEN_SCOPE']='1'# Specify a hostname and port that are set as a valid redirect URI# for your API project in the Google API Console.app.run('localhost',8080,debug=True)
require'googleauth'require'googleauth/web_user_authorizer'require'googleauth/stores/redis_token_store'require'google/apis/drive_v3'require'google/apis/calendar_v3'require'sinatra'configuredoenable:sessions# Required, call the from_file method to retrieve the client ID from a# client_secret.json file.set:client_id,Google::Auth::ClientId.from_file('/path/to/client_secret.json')# Required, scope value# Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.scope=['Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY','Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY']# Required, Authorizers require a storage instance to manage long term persistence of# access and refresh tokens.set:token_store,Google::Auth::Stores::RedisTokenStore.new(redis:Redis.new)# Required, indicate where the API server will redirect the user after the user completes# the authorization flow. The redirect URI is required. The value must exactly# match one of the authorized redirect URIs for the OAuth 2.0 client, which you# configured in the API Console. If this value doesn't match an authorized URI,# you will get a 'redirect_uri_mismatch' error.set:callback_uri,'/oauth2callback'# To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI# from the client_secret.json file. To get these credentials for your application, visit# https://console.cloud.google.com/apis/credentials.set:authorizer,Google::Auth::WebUserAuthorizer.new(settings.client_id,settings.scope,settings.token_store,callback_uri:settings.callback_uri)endget'/'do# NOTE: Assumes the user is already authenticated to the appuser_id=request.session['user_id']# Fetch stored credentials for the user from the given request session.# nil if none presentcredentials=settings.authorizer.get_credentials(user_id,request)ifcredentials.nil?# Generate a url that asks the user to authorize requested scope(s).# Then, redirect user to the url.redirectsettings.authorizer.get_authorization_url(request:request)end# User authorized the request. Now, check which scopes were granted.ifcredentials.scope.include?(Google::Apis::DriveV3::AUTH_DRIVE_METADATA_READONLY)# User authorized read-only Drive activity permission.# Example of using Google Drive API to list filenames in user's Drive.drive=Google::Apis::DriveV3::DriveService.newfiles=drive.list_files(options:{authorization:credentials})"<pre>#{JSON.pretty_generate(files.to_h)}</pre>"else# User didn't authorize read-only Drive activity permission.# Update UX and application accordinglyend# Check if user authorized Calendar read permission.ifcredentials.scope.include?(Google::Apis::CalendarV3::AUTH_CALENDAR_READONLY)# User authorized Calendar read permission.# Calling the APIs, etc.else# User didn't authorize Calendar read permission.# Update UX and application accordinglyendend# Receive the callback from Google's OAuth 2.0 server.get'/oauth2callback'do# Handle the result of the oauth callback. Defers the exchange of the code by# temporarily stashing the results in the user's session.target_url=Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request)redirecttarget_urlend
Node.js
برای اجرای این مثال:
در API ConsoleURL دستگاه محلی را به لیست URL های تغییر مسیر اضافه کنید. به عنوان مثال ، http://localhost اضافه کنید.
اطمینان حاصل کنید که LTS تعمیر و نگهداری ، LTS فعال یا انتشار فعلی Node.js نصب شده دارید.
یک فهرست جدید ایجاد کنید و به آن تغییر دهید. به عنوان مثال:
mkdir ~/nodejs-oauth2-example
cd ~/nodejs-oauth2-example
consthttp=require('http');consthttps=require('https');consturl=require('url');const{google}=require('googleapis');constcrypto=require('crypto');constexpress=require('express');constsession=require('express-session');/** * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI. * To get these credentials for your application, visit * https://console.cloud.google.com/apis/credentials. */constoauth2Client=newgoogle.auth.OAuth2(YOUR_CLIENT_ID,YOUR_CLIENT_SECRET,YOUR_REDIRECT_URL);// Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.constscopes=['https://www.googleapis.com/auth/drive.metadata.readonly','https://www.googleapis.com/auth/calendar.readonly'];/* Global variable that stores user credential in this code example. * ACTION ITEM for developers: * Store user's refresh token in your data store if * incorporating this code into your real app. * For more information on handling refresh tokens, * see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens */letuserCredential=null;asyncfunctionmain(){constapp=express();app.use(session({secret:'your_secure_secret_key',// Replace with a strong secretresave:false,saveUninitialized:false,}));// Example on redirecting user to Google's OAuth 2.0 server.app.get('/',async(req,res)=>{// Generate a secure random state value.conststate=crypto.randomBytes(32).toString('hex');// Store state in the sessionreq.session.state=state;// Generate a url that asks permissions for the Drive activity and Google Calendar scopeconstauthorizationUrl=oauth2Client.generateAuthUrl({// 'online' (default) or 'offline' (gets refresh_token)access_type:'offline',/** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */scope:scopes,// Enable incremental authorization. Recommended as a best practice.include_granted_scopes:true,// Include the state parameter to reduce the risk of CSRF attacks.state:state});res.redirect(authorizationUrl);});// Receive the callback from Google's OAuth 2.0 server.app.get('/oauth2callback',async(req,res)=>{// Handle the OAuth 2.0 server responseletq=url.parse(req.url,true).query;if(q.error){// An error response e.g. error=access_deniedconsole.log('Error:'+q.error);}elseif(q.state!==req.session.state){//check state valueconsole.log('State mismatch. Possible CSRF attack');res.end('State mismatch. Possible CSRF attack');}else{// Get access and refresh tokens (if access_type is offline)let{tokens}=awaitoauth2Client.getToken(q.code);oauth2Client.setCredentials(tokens);/** Save credential to the global variable in case access token was refreshed. * ACTION ITEM: In a production app, you likely want to save the refresh token * in a secure persistent database instead. */userCredential=tokens;// User authorized the request. Now, check which scopes were granted.if(tokens.scope.includes('https://www.googleapis.com/auth/drive.metadata.readonly')){// User authorized read-only Drive activity permission.// Example of using Google Drive API to list filenames in user's Drive.constdrive=google.drive('v3');drive.files.list({auth:oauth2Client,pageSize:10,fields:'nextPageToken, files(id, name)',},(err1,res1)=>{if(err1)returnconsole.log('The API returned an error: '+err1);constfiles=res1.data.files;if(files.length){console.log('Files:');files.map((file)=>{console.log(`${file.name} (${file.id})`);});}else{console.log('No files found.');}});}else{// User didn't authorize read-only Drive activity permission.// Update UX and application accordingly}// Check if user authorized Calendar read permission.if(tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly')){// User authorized Calendar read permission.// Calling the APIs, etc.}else{// User didn't authorize Calendar read permission.// Update UX and application accordingly}}});// Example on revoking a tokenapp.get('/revoke',async(req,res)=>{// Build the string for the POST requestletpostData="token="+userCredential.access_token;// Options for POST request to Google's OAuth 2.0 server to revoke a tokenletpostOptions={host:'oauth2.googleapis.com',port:'443',path:'/revoke',method:'POST',headers:{'Content-Type':'application/x-www-form-urlencoded','Content-Length':Buffer.byteLength(postData)}};// Set up the requestconstpostReq=https.request(postOptions,function(res){res.setEncoding('utf8');res.on('data',d=>{console.log('Response: '+d);});});postReq.on('error',error=>{console.log(error)});// Post the request with datapostReq.write(postData);postReq.end();});constserver=http.createServer(app);server.listen(8080);}main().catch(console.error);
http/استراحت
این مثال پایتون از چارچوب Flask و کتابخانه درخواست ها برای نشان دادن جریان وب OAUTH 2.0 استفاده می کند. توصیه می کنیم برای این جریان از کتابخانه مشتری Google API برای Python استفاده کنید. (مثال در برگه پایتون از کتابخانه مشتری استفاده می کند.)
importjsonimportflaskimportrequestsapp=flask.Flask(__name__)# To get these credentials (CLIENT_ID CLIENT_SECRET) and for your application, visit# https://console.cloud.google.com/apis/credentials.CLIENT_ID='123456789.apps.googleusercontent.com'CLIENT_SECRET='abc123'# Read from a file or environmental variable in a real app# Access scopes for two non-Sign-In scopes: Read-only Drive activity and Google Calendar.SCOPE='https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly'# Indicate where the API server will redirect the user after the user completes# the authorization flow. The redirect URI is required. The value must exactly# match one of the authorized redirect URIs for the OAuth 2.0 client, which you# configured in the API Console. If this value doesn't match an authorized URI,# you will get a 'redirect_uri_mismatch' error.REDIRECT_URI='http://example.com/oauth2callback'@app.route('/')defindex():if'credentials'notinflask.session:returnflask.redirect(flask.url_for('oauth2callback'))credentials=json.loads(flask.session['credentials'])ifcredentials['expires_in'] <=0:returnflask.redirect(flask.url_for('oauth2callback'))else:# User authorized the request. Now, check which scopes were granted.if'https://www.googleapis.com/auth/drive.metadata.readonly'incredentials['scope']:# User authorized read-only Drive activity permission.# Example of using Google Drive API to list filenames in user's Drive.headers={'Authorization':'Bearer {}'.format(credentials['access_token'])}req_uri='https://www.googleapis.com/drive/v2/files'r=requests.get(req_uri,headers=headers).textelse:# User didn't authorize read-only Drive activity permission.# Update UX and application accordinglyr='User did not authorize Drive permission.'# Check if user authorized Calendar read permission.if'https://www.googleapis.com/auth/calendar.readonly'incredentials['scope']:# User authorized Calendar read permission.# Calling the APIs, etc.r+='User authorized Calendar permission.'else:# User didn't authorize Calendar read permission.# Update UX and application accordinglyr+='User did not authorize Calendar permission.'returnr@app.route('/oauth2callback')defoauth2callback():if'code'notinflask.request.args:state=str(uuid.uuid4())flask.session['state']=state# Generate a url that asks permissions for the Drive activity# and Google Calendar scope. Then, redirect user to the url.auth_uri=('https://accounts.google.com/o/oauth2/v2/auth?response_type=code''&client_id={}&redirect_uri={}&scope={}&state={}').format(CLIENT_ID,REDIRECT_URI,SCOPE,state)returnflask.redirect(auth_uri)else:if'state'notinflask.request.argsorflask.request.args['state']!=flask.session['state']:return'State mismatch. Possible CSRF attack.',400auth_code=flask.request.args.get('code')data={'code':auth_code,'client_id':CLIENT_ID,'client_secret':CLIENT_SECRET,'redirect_uri':REDIRECT_URI,'grant_type':'authorization_code'}# Exchange authorization code for access and refresh tokens (if access_type is offline)r=requests.post('https://oauth2.googleapis.com/token',data=data)flask.session['credentials']=r.textreturnflask.redirect(flask.url_for('index'))if__name__=='__main__':importuuidapp.secret_key=str(uuid.uuid4())app.debug=Falseapp.run()
قوانین اعتبار سنجی URI را هدایت کنید
Google قوانین اعتبار سنجی زیر را برای هدایت URIS به منظور کمک به توسعه دهندگان در حفظ امنیت برنامه های خود اعمال می کند. URI های تغییر مسیر شما باید به این قوانین رعایت کنند. برای تعریف دامنه ، میزبان ، مسیر ، پرس و جو ، طرح و UserInfo ، که در زیر ذکر شده است ، به بخش 3986 به بخش 3986 مراجعه کنید.
تغییر مسیر URIS نمی تواند حاوی دامنه های کوتاه کننده URL باشد (به عنوان مثال goo.gl ) مگر اینکه برنامه صاحب دامنه باشد. علاوه بر این ، اگر برنامه ای که صاحب دامنه Shortener است ، تغییر مسیر به آن دامنه را انتخاب می کند ، این URI را تغییر مسیر می دهد یا باید در مسیر خود “/google-callback/” باشد یا با “/google-callback” پایان یابد.
تغییر مسیر URIS نمی تواند حاوی یک مسیر مسیری باشد (که به آن Backtracking Directory نیز گفته می شود) ، که توسط “/..” یا “\..” یا رمزگذاری URL آنها نشان داده شده است.
تغییر مسیر URIS نمی تواند شامل شخصیت های خاصی از جمله:
شخصیت های Wildcard ( '*' )
شخصیت های غیر قابل چاپ ASCII
رمزگذاری درصد نامعتبر (هر درصد رمزگذاری که از فرم رمزگذاری URL از یک درصد درصد پیروی نمی کند و به دنبال آن دو رقم شش ضلعی)
کاراکترهای تهی (یک شخصیت تهی رمزگذاری شده ، به عنوان مثال ، %00 ، %C0%80 )
مجوز افزایشی
در پروتکل OAUTH 2.0 ، برنامه شما از مجوز دسترسی به منابع ، که توسط Scopes مشخص می شود ، درخواست می کند. این بهترین عمل تجربه تجربه کاربر برای درخواست مجوز برای منابع در زمان نیاز به آنها است. برای فعال کردن این عمل ، سرور مجوز Google از مجوز افزایشی پشتیبانی می کند. این ویژگی به شما امکان می دهد تا از آنجا که لازم است ، از Scopes درخواست کنید و اگر کاربر اجازه دامنه جدید را اعطا کند ، یک کد مجوز را باز می گرداند که ممکن است برای نشانه ای که شامل تمام حوزه هایی است که کاربر به پروژه اعطا کرده است ، مبادله شود.
به عنوان مثال ، برنامه ای که به افراد اجازه می دهد آهنگ های موسیقی را نمونه برداری کنند و مخلوط ها را ایجاد کنند ، ممکن است در زمان ورود به سیستم به منابع بسیار کمی احتیاج داشته باشند ، شاید چیزی بیش از نام شخصی که وارد سیستم می شود. با این حال ، صرفه جویی در ترکیب کامل نیاز به دسترسی به Google Drive خود دارد. بیشتر افراد اگر فقط از آنها خواسته می شد به Google Drive خود دسترسی پیدا کنند ، این برنامه طبیعی را طبیعی می دانند.
در این حالت ، در زمان ورود به سیستم ، برنامه ممکن است از Scopes openid و profile برای انجام ورود به سیستم اصلی درخواست کند ، و سپس بعداً از https://www.googleapis.com/auth/drive.file در زمان اولین درخواست برای صرفه جویی در مخلوط درخواست می کند.
برای اجرای مجوزهای افزایشی ، شما جریان عادی را برای درخواست نشانه دسترسی تکمیل می کنید اما اطمینان حاصل کنید که درخواست مجوز شامل دامنه های قبلی است. این رویکرد به برنامه شما اجازه می دهد تا از مدیریت چندین نشانه دسترسی جلوگیری کند.
قوانین زیر برای یک نشانه دسترسی به دست آمده از مجوز افزایشی اعمال می شود:
از این نشانه می توان برای دسترسی به منابع مربوط به هر یک از دامنه های موجود در مجوز جدید و ترکیبی استفاده کرد.
هنگامی که از نشانه های تازه برای مجوز ترکیبی برای به دست آوردن یک نشانه دسترسی استفاده می کنید ، نشانه دسترسی نشان دهنده مجوز ترکیبی است و می تواند برای هر یک از مقادیر scope موجود در پاسخ استفاده شود.
مجوز ترکیبی شامل کلیه دامنه هایی است که کاربر به پروژه API اعطا کرده است حتی اگر کمک های مالی از مشتری های مختلف درخواست شده باشد. به عنوان مثال ، اگر کاربر با استفاده از مشتری دسک تاپ یک برنامه به یک دامنه دسترسی داشته باشد و سپس از طریق مشتری تلفن همراه ، دامنه دیگری را به همان برنامه اعطا کند ، مجوز ترکیبی شامل هر دو دامنه است.
اگر نشانه ای را که نمایانگر یک مجوز ترکیبی است ، لغو کنید ، دسترسی به همه اسکوپ های مجوز از طرف کاربر مرتبط به طور همزمان ابطال می شود.
در پایتون ، آرگومان کلیدی include_granted_scopes را true کنید تا اطمینان حاصل شود که یک درخواست مجوز شامل دامنه های قبلاً اعطا شده است. بسیار ممکن است که include_granted_scopesتنها آرگومان کلیدی نیست که شما تنظیم می کنید ، همانطور که در مثال زیر نشان داده شده است.
authorization_url,state=flow.authorization_url(# Enable offline access so that you can refresh an access token without# re-prompting the user for permission. Recommended for web server apps.access_type='offline',# Enable incremental authorization. Recommended as a best practice.include_granted_scopes='true')
constauthorizationUrl=oauth2Client.generateAuthUrl({// 'online' (default) or 'offline' (gets refresh_token)access_type:'offline',/** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */scope:scopes,// Enable incremental authorization. Recommended as a best practice.include_granted_scopes:true});
http/استراحت
GET https://accounts.google.com/o/oauth2/v2/auth?
client_id=your_client_id&
response_type=code&
state=state_parameter_passthrough_value&
scope=https%3A//www.googleapis.com/auth/drive.metadata.readonly%20https%3A//www.googleapis.com/auth/calendar.readonly&
redirect_uri=https%3A//oauth2.example.com/code&
prompt=consent&
include_granted_scopes=true
تازه کردن یک نشانه دسترسی (دسترسی آفلاین)
نشانه های دسترسی به صورت دوره ای منقضی می شوند و برای یک درخواست API مربوطه اعتبار نامعتبر می شوند. در صورت درخواست دسترسی آفلاین به دامنه های مرتبط با نشانه ، می توانید یک نشانه دسترسی را بدون ایجاد مجوز (از جمله وقتی کاربر حضور نداشته باشد) تازه کنید.
اگر از یک کتابخانه مشتری Google API استفاده می کنید ، شیء مشتری تا زمانی که آن شیء را برای دسترسی آفلاین پیکربندی می کنید ، نشانه دسترسی را تازه می کند.
اگر از کتابخانه مشتری استفاده نمی کنید ، باید هنگام هدایت کاربر به سرور OAUTH 2.0 Google ، پارامتر پرس و جو access_type HTTP را به offline تنظیم کنید. در این حالت ، سرور مجوز Google هنگام تبادل یک کد مجوز برای یک نشانه دسترسی ، یک نشانه تازه را برمی گرداند. سپس ، اگر نشانه دسترسی منقضی شود (یا در هر زمان دیگری) ، می توانید از یک نشانه تازه برای بدست آوردن یک نشانه دسترسی جدید استفاده کنید.
درخواست دسترسی آفلاین یک الزام برای هر برنامه ای است که در صورت عدم حضور کاربر نیاز به دسترسی به API Google دارد. به عنوان مثال ، برنامه ای که خدمات پشتیبان را انجام می دهد یا اقدامات را در زمان های از پیش تعیین شده انجام می دهد ، باید در صورت عدم حضور کاربر ، می تواند نشانه دسترسی خود را تازه کند. سبک پیش فرض دسترسی online نامیده می شود.
برنامه های وب سمت سرور ، برنامه های نصب شده و دستگاه ها همه در طی فرایند مجوز نشانه های تازه سازی را بدست می آورند. نشانه های تازه سازی به طور معمول در برنامه های وب طرف مشتری (JavaScript) استفاده نمی شوند.
PHP
اگر برنامه شما به دسترسی آفلاین به یک API Google نیاز دارد ، نوع دسترسی مشتری API را به offline تنظیم کنید:
$client->setAccessType("offline");
بعد از اینکه کاربر دسترسی آفلاین به دامنه های درخواست شده را اعطا می کند ، می توانید در هنگام آفلاین ، از API Client برای دسترسی به Google API ها از طرف کاربر استفاده کنید. شیء مشتری در صورت لزوم نشانه دسترسی را تازه می کند.
پایتون
در پایتون ، آرگومان کلیدی access_type را به offline تنظیم کنید تا اطمینان حاصل کنید که بدون نیاز به مجوز کاربر برای مجوز ، می توانید نشانه دسترسی را تازه کنید. بسیار ممکن است که access_typeتنها آرگومان کلیدی نیست که شما تنظیم کرده اید ، همانطور که در مثال زیر نشان داده شده است.
authorization_url,state=flow.authorization_url(# Enable offline access so that you can refresh an access token without# re-prompting the user for permission. Recommended for web server apps.access_type='offline',# Enable incremental authorization. Recommended as a best practice.include_granted_scopes='true')
بعد از اینکه کاربر دسترسی آفلاین به دامنه های درخواست شده را اعطا می کند ، می توانید در هنگام آفلاین ، از API Client برای دسترسی به Google API ها از طرف کاربر استفاده کنید. شیء مشتری در صورت لزوم نشانه دسترسی را تازه می کند.
روبی
اگر برنامه شما به دسترسی آفلاین به یک API Google نیاز دارد ، نوع دسترسی مشتری API را به offline تنظیم کنید:
بعد از اینکه کاربر دسترسی آفلاین به دامنه های درخواست شده را اعطا می کند ، می توانید در هنگام آفلاین ، از API Client برای دسترسی به Google API ها از طرف کاربر استفاده کنید. شیء مشتری در صورت لزوم نشانه دسترسی را تازه می کند.
Node.js
اگر برنامه شما به دسترسی آفلاین به یک API Google نیاز دارد ، نوع دسترسی مشتری API را به offline تنظیم کنید:
constauthorizationUrl=oauth2Client.generateAuthUrl({// 'online' (default) or 'offline' (gets refresh_token)access_type:'offline',/** Pass in the scopes array defined above. * Alternatively, if only one scope is needed, you can pass a scope URL as a string */scope:scopes,// Enable incremental authorization. Recommended as a best practice.include_granted_scopes:true});
بعد از اینکه کاربر دسترسی آفلاین به دامنه های درخواست شده را اعطا می کند ، می توانید در هنگام آفلاین ، از API Client برای دسترسی به Google API ها از طرف کاربر استفاده کنید. شیء مشتری در صورت لزوم نشانه دسترسی را تازه می کند.
دسترسی به نشانه ها منقضی می شود. این کتابخانه به طور خودکار از یک نشانه تازه برای به دست آوردن یک نشانه دسترسی جدید در صورت انقضا استفاده می کند. یک راه آسان برای اطمینان از اینکه همیشه جدیدترین نشانه ها را ذخیره می کنید ، استفاده از رویداد توکن ها است:
oauth2Client.on('tokens',(tokens)=>{if(tokens.refresh_token){// store the refresh_token in your secure persistent databaseconsole.log(tokens.refresh_token);}console.log(tokens.access_token);});
این رویداد توکن ها فقط در اولین مجوز رخ می دهد ، و شما باید هنگام تماس با روش generateAuthUrl برای دریافت نشانه تازه ، access_type خود را به offline تنظیم کنید. اگر قبلاً برنامه خود را مجوزهای مورد نیاز را بدون تعیین محدودیت های مناسب برای دریافت نشانه تازه سازی ، به برنامه خود داده اید ، برای دریافت یک نشانه تازه تازه ، باید مجدداً مجوز برنامه را مجدداً وارد کنید.
برای تنظیم مجدد refresh_token در زمان بعدی ، می توانید از روش setCredentials استفاده کنید:
هنگامی که مشتری یک نشانه تازه سازی داشته باشد ، در تماس بعدی به API به طور خودکار به دست می آید و به طور خودکار تازه می شود.
http/استراحت
برای تازه کردن یک نشانه دسترسی ، برنامه شما درخواست POST HTTPS را به سرور مجوز Google ( https://oauth2.googleapis.com/token ) ارسال می کند که شامل پارامترهای زیر است:
تا زمانی که کاربر دسترسی اعطا شده به برنامه را باطل نکرده باشد ، سرور توکن یک شیء JSON را که حاوی یک نشانه دسترسی جدید است ، برمی گرداند. قطعه زیر پاسخ نمونه را نشان می دهد:
توجه داشته باشید که در تعداد نشانه های تازه سازی که صادر می شوند محدودیت هایی وجود دارد. یک حد برای هر ترکیب مشتری/کاربر و دیگری برای هر کاربر در کلیه مشتری ها. شما باید نشانه های تازه سازی را در ذخیره سازی بلند مدت ذخیره کنید و تا زمانی که معتبر باشند ، به استفاده از آنها ادامه دهید. اگر درخواست شما درخواست بسیاری از نشانه های تازه سازی را داشته باشد ، ممکن است به این محدودیت ها برسد ، در این صورت نشانه های تازه سازی قدیمی تر کار را متوقف می کنند.
همچنین برای برنامه کاربردی امکان لغو برنامه ای دسترسی داده شده به آن وجود دارد. ابطال برنامه نویسی در مواردی که کاربر مشترک است ، یک برنامه را حذف می کند ، یا منابع API مورد نیاز یک برنامه به طور قابل توجهی تغییر کرده است. به عبارت دیگر ، بخشی از فرآیند حذف می تواند شامل یک درخواست API برای اطمینان از مجوزهای قبلاً به برنامه حذف شود.
PHP
برای ابطال برنامه ای ، با revokeToken() تماس بگیرید:
$client->revokeToken();
پایتون
برای ابطال برنامه نویسی ، یک درخواست را به https://oauth2.googleapis.com/revoke که شامل نشانه به عنوان یک پارامتر است و هدر Content-Type را تنظیم می کند ، درخواست کنید.
نشانه می تواند یک نشانه دسترسی یا یک نشانه تازه باشد. اگر توکن یک نشانه دسترسی باشد و دارای یک نشانه تازه سازی مربوط باشد ، نشانه تازه سازی نیز ابطال می شود.
اگر ابطال با موفقیت پردازش شود ، کد وضعیت پاسخ 200 است. برای شرایط خطا ، یک کد وضعیت 400 به همراه یک کد خطا بازگردانده می شود.
Node.js
برای ابطال برنامه نویسی ، یک درخواست پست HTTPS را به نقطه پایانی /revoke کنید:
consthttps=require('https');// Build the string for the POST requestletpostData="token="+userCredential.access_token;// Options for POST request to Google's OAuth 2.0 server to revoke a tokenletpostOptions={host:'oauth2.googleapis.com',port:'443',path:'/revoke',method:'POST',headers:{'Content-Type':'application/x-www-form-urlencoded','Content-Length':Buffer.byteLength(postData)}};// Set up the requestconstpostReq=https.request(postOptions,function(res){res.setEncoding('utf8');res.on('data',d=>{console.log('Response: '+d);});});postReq.on('error',error=>{console.log(error)});// Post the request with datapostReq.write(postData);postReq.end();
پارامتر توکن می تواند یک نشانه دسترسی یا یک نشانه تازه باشد. اگر توکن یک نشانه دسترسی باشد و دارای یک نشانه تازه سازی مربوط باشد ، نشانه تازه سازی نیز ابطال می شود.
اگر ابطال با موفقیت پردازش شود ، کد وضعیت پاسخ 200 است. برای شرایط خطا ، یک کد وضعیت 400 به همراه یک کد خطا بازگردانده می شود.
http/استراحت
برای ابطال برنامه ای ، برنامه شما درخواست https://oauth2.googleapis.com/revoke را ارائه می دهد و شامل این است که به عنوان یک پارامتر:
نشانه می تواند یک نشانه دسترسی یا یک نشانه تازه باشد. اگر توکن یک نشانه دسترسی باشد و دارای یک نشانه تازه سازی مربوط باشد ، نشانه تازه سازی نیز ابطال می شود.
اگر ابطال با موفقیت پردازش شود ، کد وضعیت HTTP پاسخ 200 است. برای شرایط خطا ، یک کد وضعیت HTTP 400 به همراه کد خطا بازگردانده می شود.
دسترسی مبتنی بر زمان
دسترسی مبتنی بر زمان به کاربر اجازه می دهد تا برنامه خود را برای مدت زمان محدود به داده های خود دسترسی دهد تا یک عمل را انجام دهد. دسترسی مبتنی بر زمان در محصولات Google Select در طول جریان رضایت در دسترس است و به کاربران این امکان را می دهد که برای مدت زمان محدود دسترسی را اعطا کنند. به عنوان مثال ، API قابلیت حمل داده است که انتقال یک بار داده را امکان پذیر می کند.
هنگامی که یک کاربر دسترسی مبتنی بر زمان برنامه شما را اعطا می کند ، Token Refresh پس از مدت زمان مشخص منقضی می شود. توجه داشته باشید که نشانه های تازه سازی ممکن است قبلاً در شرایط خاص باطل شوند. برای جزئیات بیشتر به این موارد مراجعه کنید. قسمت refresh_token_expires_in در پاسخ مبادله کد مجوز بازگشت ، زمان باقی مانده را تا زمانی که توکن تازه در چنین مواردی منقضی می شود ، نشان می دهد.
اجرای حفاظت از حساب متقابل
یک قدم اضافی که باید برای محافظت از حساب کاربری کاربران خود بردارید ، اجرای حفاظت از حساب متقابل با استفاده از سرویس محافظت از حساب متقابل Google است. این سرویس به شما امکان می دهد تا در اعلان های رویداد امنیتی که اطلاعاتی را در مورد تغییرات اساسی در حساب کاربری ارائه می دهد ، مشترک شوید. سپس می توانید بسته به نحوه تصمیم گیری در پاسخ به وقایع ، از اطلاعات برای انجام اقدامات استفاده کنید.
برخی از نمونه های نوع رویداد ارسال شده توسط سرویس محافظت از حساب متقابل Google: عبارتند از:
تاریخ آخرین بهروزرسانی 2025-08-27 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-08-27 بهوقت ساعت هماهنگ جهانی."],[],[]]