OAuth 2.0 برای برنامه های موبایل و دسکتاپ

این سند توضیح می‌دهد که چگونه برنامه‌های نصب‌شده در دستگاه‌هایی مانند تلفن‌ها، تبلت‌ها و رایانه‌ها از نقاط پایانی OAuth 2.0 Google برای اجازه دسترسی به APIهای Google استفاده می‌کنند.

OAuth 2.0 به کاربران اجازه می دهد تا داده های خاصی را با یک برنامه به اشتراک بگذارند در حالی که نام کاربری، رمز عبور و سایر اطلاعات خود را خصوصی نگه می دارند. به عنوان مثال، یک برنامه می تواند از OAuth 2.0 برای دریافت مجوز از کاربران برای ذخیره فایل ها در Google Drives خود استفاده کند.

برنامه‌های نصب‌شده در دستگاه‌های جداگانه توزیع می‌شوند و فرض بر این است که این برنامه‌ها نمی‌توانند اسرار را حفظ کنند. وقتی کاربر در برنامه حضور دارد یا زمانی که برنامه در پس‌زمینه اجرا می‌شود، می‌توانند به Google API دسترسی داشته باشند.

این جریان مجوز مشابه جریان مورد استفاده برای برنامه های کاربردی وب سرور است. تفاوت اصلی این است که برنامه های نصب شده باید مرورگر سیستم را باز کنند و یک URI تغییر مسیر محلی برای رسیدگی به پاسخ ها از سرور مجوز Google ارائه دهند.

جایگزین ها

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

برای برنامه‌هایی که روی دستگاه‌هایی اجرا می‌شوند که از مرورگر سیستم پشتیبانی نمی‌کنند یا دارای قابلیت‌های ورودی محدودی هستند، مانند تلویزیون‌ها، کنسول‌های بازی، دوربین‌ها یا چاپگرها، به OAuth 2.0 برای تلویزیون‌ها و دستگاه‌ها یا ورود به سیستم در تلویزیون‌ها و دستگاه‌های ورودی محدود مراجعه کنید.

کتابخانه ها و نمونه ها

ما کتابخانه ها و نمونه های زیر را برای کمک به پیاده سازی جریان OAuth 2.0 که در این سند توضیح داده شده است، توصیه می کنیم:

• AppAuth برای کتابخانه اندروید
• AppAuth برای کتابخانه iOS
• OAuth برای برنامه ها: نمونه های ویندوز

پیش نیازها

API ها را برای پروژه خود فعال کنید

هر برنامه‌ای که Google API را فراخوانی می‌کند، باید آن APIها را در آن فعال کند API Console.

برای فعال کردن یک API برای پروژه خود:

1. Open the API Library در Google API Console.
2. If prompted, select a project, or create a new one.
3. را API Library همه API های موجود را فهرست می کند که بر اساس خانواده محصول و محبوبیت گروه بندی شده اند. اگر API که می‌خواهید فعال کنید در لیست قابل مشاهده نیست، از جستجو برای پیدا کردن آن استفاده کنید یا روی مشاهده همه در خانواده محصولی که به آن تعلق دارد کلیک کنید.
4. API را که می خواهید فعال کنید انتخاب کنید، سپس روی دکمه Enable کلیک کنید.
5. If prompted, enable billing.
6. If prompted, read and accept the API's Terms of Service.

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

هر برنامه‌ای که از OAuth 2.0 برای دسترسی به APIهای Google استفاده می‌کند، باید دارای اعتبارنامه مجوز باشد که برنامه را در سرور OAuth 2.0 Google شناسایی کند. مراحل زیر نحوه ایجاد اعتبار برای پروژه خود را توضیح می دهد. سپس برنامه های شما می توانند از اعتبارنامه ها برای دسترسی به API هایی که برای آن پروژه فعال کرده اید استفاده کنند.

1. Go to the Credentials page.
2. روی ایجاد اعتبار > شناسه مشتری OAuth کلیک کنید.
3. بخش‌های زیر انواع سرویس گیرنده‌هایی را که سرور مجوز Google پشتیبانی می‌کند، توضیح می‌دهد. نوع سرویس گیرنده ای را که برای برنامه شما توصیه می شود انتخاب کنید، کلاینت OAuth خود را نام ببرید و فیلدهای دیگر را در فرم مناسب تنظیم کنید.

محدوده های دسترسی را شناسایی کنید

Scopes به برنامه شما امکان می‌دهد فقط درخواست دسترسی به منابع مورد نیاز خود را داشته باشد در حالی که کاربران را قادر می‌سازد تا میزان دسترسی را که به برنامه شما می‌دهند کنترل کنند. بنابراین، ممکن است بین تعداد دامنه های درخواستی و احتمال کسب رضایت کاربر رابطه معکوس وجود داشته باشد.

قبل از شروع اجرای مجوز OAuth 2.0، توصیه می‌کنیم محدوده‌هایی را که برنامه شما برای دسترسی به آنها نیاز به مجوز دارد، شناسایی کنید.

سند OAuth 2.0 API Scopes حاوی فهرست کاملی از حوزه‌هایی است که ممکن است برای دسترسی به Google API از آنها استفاده کنید.

دریافت توکن های دسترسی OAuth 2.0

مراحل زیر نشان می دهد که چگونه برنامه شما با سرور OAuth 2.0 Google برای کسب رضایت کاربر برای انجام یک درخواست API از طرف کاربر تعامل دارد. برنامه شما قبل از اینکه بتواند یک درخواست Google API را که نیاز به مجوز کاربر دارد، اجرا کند، باید این رضایت را داشته باشد.

مرحله 1: یک تأیید کننده کد و چالش ایجاد کنید

Google از پروتکل Proof Key for Code Exchange (PKCE) پشتیبانی می کند تا جریان برنامه نصب شده را ایمن تر کند. برای هر درخواست مجوز یک تأیید کننده کد منحصر به فرد ایجاد می شود و مقدار تبدیل شده آن به نام "code_challenge" برای دریافت کد مجوز به سرور مجوز ارسال می شود.

تایید کننده کد را ایجاد کنید

یک code_verifier یک رشته رمزنگاری تصادفی با آنتروپی بالا با استفاده از کاراکترهای رزرو نشده [AZ] / [az] / [0-9] / "-" / " است. / "_" / "~"، با حداقل طول 43 کاراکتر و حداکثر طول 128 کاراکتر.

تأیید کننده کد باید آنتروپی کافی داشته باشد تا حدس زدن مقدار را غیرعملی کند.

چالش کد را ایجاد کنید

دو روش ایجاد چالش کد پشتیبانی می شود.

code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))

code_challenge = code_verifier

مرحله 2: درخواستی را به سرور OAuth 2.0 Google ارسال کنید

برای دریافت مجوز کاربر، درخواستی را به سرور مجوز Google در https://accounts.google.com/o/oauth2/v2/auth ارسال کنید. این نقطه پایانی جستجوی جلسه فعال را کنترل می کند، کاربر را احراز هویت می کند و رضایت کاربر را دریافت می کند. نقطه پایانی فقط از طریق SSL قابل دسترسی است و از اتصالات HTTP (غیر SSL) خودداری می کند.

سرور مجوز از پارامترهای رشته کوئری زیر برای برنامه های نصب شده پشتیبانی می کند:

نمونه URL های مجوز

برگه های زیر نمونه URL های مجوز را برای گزینه های مختلف URI تغییر مسیر نشان می دهد.

URL ها به جز مقدار پارامتر redirect_uri یکسان هستند. URL ها همچنین حاوی پارامترهای response_type و client_id مورد نیاز و همچنین پارامتر state اختیاری هستند. هر URL حاوی خطوط شکسته و فاصله برای خوانایی است.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

مرحله 3: گوگل رضایت کاربر را درخواست می کند

در این مرحله، کاربر تصمیم می گیرد که آیا به اپلیکیشن شما دسترسی درخواستی را بدهد یا خیر. در این مرحله، گوگل یک پنجره رضایت را نمایش می دهد که نام برنامه شما و سرویس های Google API را نشان می دهد که درخواست اجازه دسترسی به آن ها را با اعتبار مجوز کاربر و خلاصه ای از محدوده های دسترسی که باید اعطا شود را نشان می دهد. سپس کاربر می تواند با اعطای دسترسی به یک یا چند حوزه درخواست شده توسط برنامه شما موافقت کند یا درخواست را رد کند.

برنامه شما در این مرحله نیازی به انجام هیچ کاری ندارد زیرا منتظر پاسخ سرور OAuth 2.0 Google است که نشان می دهد آیا دسترسی اعطا شده است یا خیر. این پاسخ در مرحله زیر توضیح داده شده است.

مرحله 4: پاسخ سرور OAuth 2.0 را مدیریت کنید

روشی که برنامه شما پاسخ مجوز را دریافت می کند به طرح URI تغییر مسیری که استفاده می کند بستگی دارد. صرف نظر از طرح، پاسخ شامل یک کد مجوز ( code ) یا یک خطا ( error ) خواهد بود. برای مثال error=access_denied نشان می دهد که کاربر درخواست را رد کرده است.

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

مرحله 5: کد مجوز را برای به‌روزرسانی و دسترسی به توکن‌ها مبادله کنید

برای تبادل کد مجوز برای یک نشانه دسترسی، با https://oauth2.googleapis.com/token endpoint تماس بگیرید و پارامترهای زیر را تنظیم کنید:

قطعه زیر یک نمونه درخواست را نشان می دهد:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=http://127.0.0.1:9004&
grant_type=authorization_code

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

پاسخ شامل فیلدهای زیر است:

قطعه زیر یک نمونه پاسخ را نشان می دهد:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

فراخوانی Google API

پس از اینکه برنامه شما یک نشانه دسترسی به دست آورد، در صورتی که دامنه دسترسی مورد نیاز توسط API اعطا شده باشد، می توانید از این رمز برای برقراری تماس با Google API از طرف یک حساب کاربری خاص استفاده کنید. برای انجام این کار، توکن دسترسی را با درج یک پارامتر query access_token یا یک مقدار Authorization HTTP header Bearer در درخواست API قرار دهید. در صورت امکان، هدر HTTP ترجیح داده می شود، زیرا رشته های پرس و جو در گزارش های سرور قابل مشاهده هستند. در بیشتر موارد می‌توانید از کتابخانه سرویس گیرنده برای تنظیم تماس‌های خود با Google API استفاده کنید (به عنوان مثال، هنگام تماس با Drive Files API ).

می‌توانید همه APIهای Google را امتحان کنید و دامنه آنها را در OAuth 2.0 Playground مشاهده کنید.

نمونه های HTTP GET

تماس با نقطه پایانی drive.files (API فایل‌های Drive) با استفاده از هدر HTTP Authorization: Bearer ممکن است به شکل زیر باشد. توجه داشته باشید که باید رمز دسترسی خود را مشخص کنید:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

در اینجا یک فراخوانی به همان API برای کاربر تأیید شده با استفاده از پارامتر رشته query access_token وجود دارد:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

نمونه های curl

می توانید این دستورات را با برنامه خط فرمان curl آزمایش کنید. در اینجا یک مثال است که از گزینه هدر HTTP (ترجیح) استفاده می کند:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

یا، گزینه پارامتر query string:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

در حال بازخوانی نشانه دسترسی

توکن‌های دسترسی به‌صورت دوره‌ای منقضی می‌شوند و برای یک درخواست API مرتبط به اعتبارنامه‌های نامعتبر تبدیل می‌شوند. اگر درخواست دسترسی آفلاین به محدوده‌های مرتبط با رمز را داشته باشید، می‌توانید یک نشانه دسترسی را بدون درخواست اجازه از کاربر (از جمله زمانی که کاربر حضور ندارد) بازخوانی کنید.

برای تازه کردن یک نشانه دسترسی، برنامه شما یک درخواست HTTPS POST به سرور مجوز Google ( https://oauth2.googleapis.com/token ) ارسال می کند که شامل پارامترهای زیر است:

قطعه زیر یک نمونه درخواست را نشان می دهد:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

تا زمانی که کاربر دسترسی اعطا شده به برنامه را لغو نکرده باشد، سرور توکن یک شی JSON را که حاوی یک نشانه دسترسی جدید است برمی گرداند. قطعه زیر یک نمونه پاسخ را نشان می دهد:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

توجه داشته باشید که محدودیت‌هایی در تعداد نشانه‌های تازه‌سازی صادر شده وجود دارد. یک محدودیت برای هر ترکیب کلاینت/کاربر، و دیگری برای هر کاربر در همه مشتریان. شما باید توکن‌های تازه‌سازی را در فضای ذخیره‌سازی طولانی‌مدت ذخیره کنید و تا زمانی که معتبر هستند به استفاده از آنها ادامه دهید. اگر برنامه شما توکن‌های به‌روزرسانی بیش از حد درخواست کند، ممکن است با این محدودیت‌ها مواجه شود، در این صورت توکن‌های تازه‌سازی قدیمی‌تر کار نمی‌کنند.

باطل کردن یک نشانه

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

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

برای لغو برنامه‌ای یک نشانه، برنامه شما درخواستی به https://oauth2.googleapis.com/revoke می‌کند و توکن را به عنوان یک پارامتر شامل می‌شود:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

توکن می تواند یک نشانه دسترسی یا یک نشانه تازه سازی باشد. اگر توکن یک نشانه دسترسی باشد و دارای یک نشانه رفرش متناظر باشد، توکن رفرش نیز باطل می شود.

اگر ابطال با موفقیت پردازش شود، کد وضعیت HTTP پاسخ 200 است. برای شرایط خطا، کد وضعیت HTTP 400 به همراه یک کد خطا برگردانده می شود.

روش های تغییر مسیر برنامه

از برنامه های خود محافظت کنید

ادامه مطلب

IETF بهترین تمرین فعلی OAUTH 2.0 برای برنامه های بومی بسیاری از بهترین شیوه های مستند شده در اینجا را تعیین می کند.