این صفحه پیادهسازی گوگل را به عنوان یک ارائهدهنده OpenID Connect شرح میدهد و مرجع فنی برای نقاط پایانی OIDC گوگل را ارائه میدهد. مشخصات OpenID Connect (OIDC) Core 1.0 پروتکل احراز هویت کاربران و دریافت اطلاعات هویتی را تعریف میکند.
این مرجع قصد ارائه دستورالعملهای گام به گام در مورد نحوه پیادهسازی OIDC را ندارد؛ برای جزئیات پیادهسازی، به راهنمای OpenID Connect مراجعه کنید.
سند کشف
سند کشف شامل فرادادههایی درباره پیکربندی OpenID Connect گوگل، آنطور که در مشخصات OpenID Connect Discovery 1.0 تعریف شده است، میباشد.
آدرس اینترنتی: https://accounts.google.com/.well-known/openid-configuration
روش درخواست پشتیبانی شده: GET
بدنه پاسخ
فیلدهای پاسخ در یک شیء JSON در بدنه پاسخ HTTP به درخواست GET درخواستکننده به آدرس https://accounts.google.com/.well-known/openid-configuration بازگردانده میشوند.
| میدان | نوع | توضیحات |
|---|---|---|
issuer | string | شناسه صادرکننده. URL حساس به حروف بزرگ و کوچک با استفاده از طرح https . مقدار مدرن https://accounts.google.com است؛ با این حال، accounts.google.com نیز برای پیادهسازیهای قدیمی بازگردانده میشود. |
authorization_endpoint | string | آدرس اینترنتی (URL) نقطه پایانی مجوز (Authorization Endpoint). |
device_authorization_endpoint | string | آدرس اینترنتی (URL) نقطه پایانی احراز هویت دستگاه. |
token_endpoint | string | آدرس اینترنتی (URL) نقطه پایانی توکن. |
userinfo_endpoint | string | آدرس اینترنتی (URL) نقطه پایانی UserInfo. |
revocation_endpoint | string | آدرس اینترنتی (URL) نقطه پایانی ابطال. |
jwks_uri | string | آدرس اینترنتی سند مجموعه کلید وب JSON (JWKS). |
response_types_supported | array | فهرستی از مقادیر response_type پشتیبانی شده. |
response_modes_supported | array | فهرستی از مقادیر response_mode پشتیبانی شده. |
authorization_response_iss_parameter_supported | boolean | بولی که نشان دهنده پشتیبانی از RFC 9207 است. |
subject_types_supported | array | فهرستی از انواع شناسههای موضوعی پشتیبانیشده. |
id_token_signing_alg_values_supported | array | فهرستی از الگوریتمهای پشتیبانیشده برای امضای شناسه توکن. |
scopes_supported | array | فهرستی از مقادیر دامنه پشتیبانی شده. |
claims_supported | array | فهرستی از ادعاهای پشتیبانیشده. |
token_endpoint_auth_methods_supported | array | فهرستی از روشهای احراز هویت پشتیبانیشده برای Token Endpoint. |
code_challenge_methods_supported | array | فهرستی از روشهای پشتیبانیشده برای چالش کد در PKCE. |
grant_types_supported | array | فهرستی از انواع کمکهزینههای پشتیبانیشده در OAuth 2.0. |
توکن شناسایی (مطالبات)
مقدار id_token که در پاسخها برگردانده میشود، یک JSON Web Token (JWT) امضا شده است که باید با استفاده از اطلاعات کلیدگذاری بهدستآمده از jwks_uri موجود در سند Discovery تأیید شود. جدول زیر محتوای payload رمزگشاییشدهی ID Token را شرح میدهد.
| ادعا | نوع | توضیحات |
|---|---|---|
iss | string | الزامی. شناسه صادرکننده برای صادرکننده پاسخ. معمولاً https://accounts.google.com است؛ با این حال، accounts.google.com نیز برای پیادهسازیهای قدیمی بازگردانده میشود. |
sub | string | الزامی. یک شناسه برای کاربر، منحصر به فرد در بین تمام حسابهای گوگل و هرگز دوباره استفاده نمیشود. یک حساب گوگل میتواند چندین آدرس ایمیل در مقاطع زمانی مختلف داشته باشد، اما مقدار sub هرگز تغییر نمیکند. sub در برنامه خود به عنوان کلید شناسه منحصر به فرد برای کاربر استفاده کنید. حداکثر طول ۲۵۵ کاراکتر ASCII حساس به حروف بزرگ و کوچک. |
azp | string | شناسهی کلاینتِ ارائهدهندهی مجاز، که از کنسول گوگل کلود دریافت شده است. این ادعا فقط زمانی مورد نیاز است که طرف درخواستکنندهی شناسه توکن، همان مخاطب شناسه توکن نباشد. |
aud | string | الزامی. مخاطبی که توکن شناسه برای آن در نظر گرفته شده است. این شناسه کلاینت برنامه شما است که از کنسول Google Cloud دریافت شده است. |
iat | integer | الزامی. زمان صدور توکن شناسایی. نمایش داده شده بر حسب زمان یونیکس (ثانیه صحیح). |
exp | integer | الزامی. زمان انقضایی که در آن یا پس از آن توکن شناسه نباید پذیرفته شود. در واحد زمان یونیکس (ثانیه صحیح) نمایش داده میشود. |
nonce | string | مقدار nonce ارائه شده توسط برنامه شما در درخواست احراز هویت. شما باید با ارائه این مقدار فقط یک بار، از حملات بازپخش جلوگیری کنید. |
auth_time | integer | زمان احراز هویت کاربر، یک عدد JSON که تعداد ثانیههای سپری شده از عصر یونیکس (۱ ژانویه ۱۹۷۰، ساعت ۰۰:۰۰:۰۰ UTC) را نشان میدهد. این مقدار زمانی ارائه میشود که عبارت auth_time در پارامتر claims درخواست احراز هویت گنجانده شده باشد. |
at_hash | string | هش توکن دسترسی. اعتبارسنجی میکند که توکن دسترسی به توکن هویت گره خورده است. اگر توکن شناسایی با مقدار access_token در جریان سرور صادر شود، این ادعا همیشه لحاظ میشود. |
email | string | آدرس ایمیل کاربر. فقط در صورتی ارائه میشود که محدوده email را در درخواست خود لحاظ کرده باشید. مقدار این ادعا ممکن است مختص این حساب نباشد و با گذشت زمان تغییر کند، بنابراین نباید از این مقدار به عنوان شناسه اصلی برای پیوند به رکورد کاربر خود استفاده کنید. همچنین نمیتوانید برای شناسایی کاربران سازمانهای Google Workspace یا Cloud به دامنه ادعای email تکیه کنید؛ در عوض از ادعای hd استفاده کنید.هشدار: از آدرس ایمیل به عنوان شناسه استفاده نکنید زیرا یک حساب گوگل میتواند چندین آدرس ایمیل در مقاطع زمانی مختلف داشته باشد. همیشه از فیلد sub به عنوان شناسه کاربر استفاده کنید. |
email_verified | boolean | اگر آدرس ایمیل کاربر تأیید شده باشد، مقدار True و در غیر این صورت مقدار False برمیگرداند. |
name | string | نام کامل کاربر، به صورت قابل نمایش. ممکن است زمانی ارائه شود که دامنه درخواست شامل profile رشتهای باشد یا توکن شناسه از بهروزرسانی توکن بازگردانده شود. |
picture | string | آدرس اینترنتی (URL) تصویر پروفایل کاربر. ممکن است زمانی ارائه شود که دامنه درخواست شامل رشته profile باشد یا توکن شناسه از بهروزرسانی توکن برگردانده شود. |
given_name | string | نام (های) کاربر یا نام کوچک او. ممکن است در صورت وجود ادعای name ، ارائه شود. |
family_name | string | نام خانوادگی یا نام خانوادگی کاربر. ممکن است در صورت وجود ادعای name ارائه شود. |
hd | string | دامنه مرتبط با سازمان فضای کاری گوگل یا فضای ابری کاربر. فقط در صورتی ارائه میشود که کاربر متعلق به یک سازمان فضای ابری گوگل باشد. هنگام محدود کردن دسترسی به یک منبع فقط به اعضای دامنههای خاص، باید این ادعا را بررسی کنید. عدم وجود این ادعا نشان میدهد که حساب متعلق به دامنه میزبانی شده توسط گوگل نیست. |
نقطه پایانی مجوز
نقطه پایانی مجوز برای احراز هویت کاربر و دریافت کد یا توکنهای مجوز استفاده میشود.
آدرس اینترنتی: https://accounts.google.com/o/oauth2/v2/auth
روشهای درخواست پشتیبانیشده: GET ، POST
پارامترهای درخواست
| پارامتر | نوع | مورد نیاز | توضیحات |
|---|---|---|---|
client_id | string | مورد نیاز | رشته شناسه کلاینت که از کنسول Google Cloud دریافت میکنید. |
nonce | string | اختیاری | یک مقدار تصادفی که توسط برنامه شما تولید میشود و محافظت در برابر تکرار را فعال میکند. فقط در صورت درخواست شناسه توکن (ID Token) مورد نیاز است (وقتی response_type شامل id_token باشد). |
response_type | string | مورد نیاز | جریان مورد استفاده را تعیین میکند. اگر مقدار code باشد، یک جریان کد مجوز راهاندازی میشود که برای دریافت توکنها نیاز به POST به نقطه پایانی توکن دارد. اگر مقدار token ، id_token ، token id_token یا id_token token باشد، یک جریان ضمنی راهاندازی میشود که نیاز به استفاده از جاوا اسکریپت در URI تغییر مسیر برای بازیابی توکنها از قطعه URI دارد . استفاده token به هر شکلی اکیداً توصیه نمیشود زیرا توکنهای دسترسی را در URL نمایش میدهد. این مقدار در OAuth 2.1 ممنوع است. |
response_mode | string | اختیاری | نحوهی ارائهی پاسخ مجوز را مشخص میکند. اگر response_type code باشد، پیشفرض query است. برای سایر انواع پاسخ، پیشفرض fragment است. مقادیر پشتیبانیشده: query ، fragment ، form_post . |
redirect_uri | string | مورد نیاز | تعیین میکند که پاسخ به کجا ارسال شود. مقدار این پارامتر باید دقیقاً با یکی از مقادیر مجاز تغییر مسیر که در کنسول Google Cloud تنظیم کردهاید (از جمله طرح HTTP یا HTTPS، حروف بزرگ و کوچک و در صورت وجود علامت '/' در انتهای آن) مطابقت داشته باشد. آدرسهای اینترنتی تغییر مسیر و مبدأهای مجاز جاوا اسکریپت باید از قوانین اعتبارسنجی مندرج در مستندات اعتبارسنجی URI OAuth 2.0 پیروی کنند. |
scope | string | مورد نیاز | فهرستی نامرتب و جدا شده با فاصله از هم. این فهرست باید شامل مقدار openid و سپس مقدار profile ، مقدار email یا هر دو باشد. همچنین میتوانید scopeهای غیر OIDC را نیز اضافه کنید. اگر مقدار scope profile وجود داشته باشد، ID Token ممکن است (اما تضمین نمیشود که) شامل claimهای پیشفرض profile کاربر باشد. اگر مقدار scope email وجود داشته باشد، ID Token شامل claimهای email و email_verified میشود. برای اطلاعات بیشتر، به Scopes OAuth 2.0 مراجعه کنید. |
state | string | توصیه شده | یک رشتهی مبهم که در پروتکل به صورت رفت و برگشتی (round-trip) برگردانده میشود؛ به عبارت دیگر، به عنوان یک پارامتر URI در جریان کد مجوز (Authorization Code) و در قطعهی URI در جریان ضمنی (Implicit) بازگردانده میشود. state میتواند برای مرتبط کردن درخواستها و پاسخها مفید باشد. از آنجا که redirect_uri شما قابل حدس زدن است، استفاده از مقدار state میتواند اطمینان شما را از اینکه یک اتصال ورودی نتیجهی یک درخواست احراز هویت آغاز شده توسط برنامهی شما است، افزایش دهد. این امر محافظت در برابر حملاتی مانند جعل درخواست بین سایتی (cross-site request forgery) را فراهم میکند. |
access_type | string | اختیاری | مقادیر مجاز offline و online هستند. اگر برنامه شما نیاز دارد که توکنهای دسترسی را زمانی که کاربر در مرورگر حضور ندارد، بهروزرسانی کند، offline استفاده کنید. این مقدار برای دریافت توکن بهروزرسانی (Refresh Token) الزامی است. |
hd | string | اختیاری | فرآیند ورود به سیستم برای حسابهای متعلق به یک سازمان Google Cloud را ساده کنید. با درج دامنه سازمان Google Cloud (به عنوان مثال، mycollege.edu )، میتوانید مشخص کنید که رابط کاربری انتخاب حساب باید برای حسابهای آن دامنه بهینه شود. برای بهینهسازی کلی برای حسابهای سازمان Google Cloud به جای فقط یک دامنه سازمان Google Cloud، مقداری مانند ستاره ( * ) تنظیم کنید: hd=* . |
login_hint | string | اختیاری | وقتی برنامه شما بداند که قصد احراز هویت کدام کاربر را دارد، میتواند این پارامتر را به عنوان یک راهنما به سرور احراز هویت ارائه دهد. ارسال این راهنما، انتخاب حساب کاربری را متوقف میکند و یا کادر ایمیل را در فرم ورود از قبل پر میکند، یا جلسه مناسب را انتخاب میکند که میتواند به شما کمک کند از مشکلاتی که در صورت ورود برنامه شما به حساب کاربری اشتباه رخ میدهد، جلوگیری کنید. مقدار میتواند یک آدرس ایمیل یا sub رشته باشد که معادل شناسه گوگل کاربر است. |
prompt | string | اختیاری | لیستی از مقادیر رشتهای که با فاصله از هم جدا شدهاند و مشخص میکنند که آیا سرور احراز هویت از کاربر درخواست احراز هویت مجدد و رضایت میکند یا خیر. مقادیر ممکن: none (بدون رابط کاربری)، consent (درخواست برای رضایت)، select_account (درخواست برای انتخاب حساب). |
hl | string | اختیاری | یک برچسب زبان BCP 47 که برای مشخص کردن زبان نمایش برای صفحات ورود به سیستم، انتخاب حساب کاربری و رضایتنامه استفاده میشود. استفاده از این پارامتر توصیه نمیشود، زیرا تنظیمات مرورگر و تنظیمات حساب گوگل معمولاً شاخصهای بهتری برای ترجیح زبان کاربر هستند. |
include_granted_scopes | boolean | اختیاری | اگر به این پارامتر مقدار true داده شود و درخواست مجوز اعطا شود، مجوز شامل هرگونه مجوز قبلی اعطا شده به این ترکیب کاربر/برنامه برای سایر حوزهها نیز خواهد بود؛ به مجوز افزایشی مراجعه کنید. |
claims | object | اختیاری | پارامتر claims برای مشخص کردن یک یا چند فیلد اختیاری برای درج در پاسخ UserInfo یا شناسه توکن استفاده میشود. برای درخواست auth_time claim، claims={\"id_token\":{\"auth_time\":{\"essential\":true}}} استفاده کنید. |
پارامترهای پاسخ
پاسخ احراز هویت با استفاده از یک تغییر مسیر HTTP GET به آدرس اینترنتی تغییر مسیر ( redirect_uri ) کاربر ارسال میشود. پارامترهای پاسخ، بسته به response_type و response_mode ، به آدرس اینترنتی تغییر مسیر در رشته پرسوجو یا قطعه URL اضافه میشوند.
| پارامتر | نوع | توضیحات |
|---|---|---|
iss | string | شناسه صادرکننده. طبق RFC 9207 ، این پارامتر همیشه برگردانده میشود و روی https://accounts.google.com تنظیم میشود. |
code | string | کد مجوزی که میتواند با توکن دسترسی و توکن شناسایی مبادله شود. |
state | string | همان مقدار پارامتر state از درخواست. |
id_token | string | یک توکن وب JSON (JWT) که حاوی اطلاعات هویتی کاربر است. |
access_token | string | توکن دسترسی که میتواند به یک API گوگل ارسال شود. |
token_type | string | نوع توکن برگشتی. همیشه Bearer . |
expires_in | integer | طول عمر توکن دسترسی بر حسب ثانیه، نسبت به زمان صدور توکن. |
scope | string | محدودههای دسترسی اعطا شده توسط code یا access_token که به صورت لیستی از رشتههای جدا شده با فاصله و حساس به حروف بزرگ و کوچک بیان میشوند. |
error | string | کد خطا در صورت عدم موفقیت درخواست. |
error_description | string | شرح خطا در صورت عدم موفقیت درخواست. |
پاسخهای خطا
برای نقطه پایانی احراز هویت، خطاها یا به عنوان پارامترهایی در رشته پرس و جو یا قطعه URL به redirect_uri کلاینت بازگردانده میشوند، یا به عنوان یک صفحه خطای میزبانی شده توسط گوگل به کاربر نمایش داده میشوند.
خطاهای هدایتشده
کدهای خطای زیر ممکن است به redirect_uri شما بازگردانده شوند:
| خطا | توضیحات |
|---|---|
access_denied | کاربر یا سرور احراز هویت، درخواست را رد کرد. |
invalid_request | درخواست فاقد پارامتر الزامی است، شامل مقدار پارامتر نامعتبر است، شامل یک پارامتر بیش از یک بار است، یا به هر نحو دیگری ناقص است. |
unauthorized_client | کلاینت مجاز به درخواست کد مجوز با استفاده از این روش نیست. |
unsupported_response_type | سرور احراز هویت از دریافت کد احراز هویت با استفاده از این روش پشتیبانی نمیکند. |
invalid_scope | محدوده درخواستی نامعتبر، ناشناخته یا ناقص است. |
خطاهای مربوط به کاربر
در برخی موارد، مانند زمانی که client_id یا redirect_uri نامعتبر است، سرور احراز هویت نمیتواند کاربر را به طور ایمن به برنامه شما هدایت کند. در این موارد، یک صفحه خطا مستقیماً به کاربر نمایش داده میشود.
| خطا | توضیحات |
|---|---|
admin_policy_enforced | حساب گوگل به دلیل سیاستهای مدیر Google Workspace خود قادر به تأیید یک یا چند محدوده درخواستی نیست. برای اطلاعات بیشتر در مورد اینکه چگونه یک مدیر میتواند دسترسی را تا زمانی که دسترسی به طور صریح به شناسه کلاینت OAuth شما اعطا نشده است، محدود کند، به مقاله راهنمای مدیر Google Workspace مراجعه کنید. |
disallowed_useragent | نقطه پایانی احراز هویت درون یک عامل کاربری تعبیهشده نمایش داده میشود که توسط سیاستهای OAuth 2.0 گوگل مجاز نیست. |
org_internal | شناسه کلاینت OAuth در درخواست، بخشی از پروژهای است که دسترسی به حسابهای گوگل را در یک سازمان ابری خاص گوگل محدود میکند. |
deleted_client | کلاینت OAuth که برای ایجاد درخواست استفاده شده بود، حذف شده است. حذف میتواند به صورت دستی یا خودکار در مورد کلاینتهای بلااستفاده انجام شود. |
invalid_grant | پارامتر code_challenge هنگام استفاده از PKCE نامعتبر است یا وجود ندارد. هنگام بهروزرسانی توکن دسترسی یا استفاده از مجوز افزایشی، ممکن است توکن منقضی شده، نامعتبر شده باشد یا حساب کاربری حذف یا غیرفعال شده باشد. |
redirect_uri_mismatch | redirect_uri ارسال شده در درخواست با یک URI تغییر مسیر مجاز برای شناسه کلاینت مطابقت ندارد. URI های تغییر مسیر مجاز را در کنسول Google Cloud بررسی کنید. این خطا همچنین ممکن است در صورتی رخ دهد که درخواست از جریان منسوخ شده OAuth out-of-band (OOB) استفاده کند. |
invalid_client | مبدایی که درخواست از آن ارسال شده است برای این کلاینت مجاز نیست، پیکربندی کلاینت نادرست است، یا رمز کلاینت OAuth نادرست است. |
origin_mismatch | طرح، دامنه و/یا پورت جاوا اسکریپتی که درخواست مجوز از آن ارسال شده است، با URI مجاز جاوا اسکریپت ثبت شده برای شناسه کلاینت OAuth مطابقت ندارد. منابع مجاز جاوا اسکریپت را در کنسول Google Cloud بررسی کنید. |
invalid_request | مشکلی در درخواست وجود دارد. این مشکل میتواند به دلیل درخواست ناقص، عدم وجود پارامترهای الزامی یا استفاده از روش مجوزدهی باشد که گوگل از آن پشتیبانی نمیکند. |
نقطه پایانی توکن
نقطه پایانی توکن برای تبادل کد مجوز با یک توکن دسترسی و یک توکن شناسه استفاده میشود.
آدرس اینترنتی: https://oauth2.googleapis.com/token
روش درخواست پشتیبانی شده: POST
پارامترهای درخواست (اعطای کد مجوز)
| پارامتر | نوع | مورد نیاز | توضیحات |
|---|---|---|---|
code | string | مورد نیاز | کد مجوز دریافتی از نقطه پایانی مجوز. |
client_id | string | مورد نیاز | شناسه کلاینت برای برنامه شما، که از کنسول Google Cloud دریافت شده است. |
client_secret | string | مورد نیاز | رمز کلاینت برنامه شما، که از کنسول گوگل کلود دریافت شده است. |
redirect_uri | string | مورد نیاز | آدرس اینترنتی تغییر مسیر (Redirection URI) که در درخواست مجوز اولیه استفاده شده است. آدرسهای اینترنتی تغییر مسیر و منابع جاوا اسکریپت مجاز باید از قوانین اعتبارسنجی مندرج در مستندات اعتبارسنجی URI OAuth 2.0 پیروی کنند. |
grant_type | string | مورد نیاز | باید روی authorization_code تنظیم شود. |
پارامترهای درخواست (جریان دستگاه)
| پارامتر | نوع | مورد نیاز | توضیحات |
|---|---|---|---|
client_id | string | مورد نیاز | شناسه کلاینت برای برنامه شما، که از کنسول Google Cloud دریافت شده است. |
client_secret | string | مورد نیاز | رمز کلاینت برنامه شما، که از کنسول گوگل کلود دریافت شده است. |
device_code | string | مورد نیاز | device_code که توسط نقطه پایانی احراز هویت دستگاه برگردانده میشود. |
grant_type | string | مورد نیاز | باید روی urn:ietf:params:oauth:grant-type:device_code تنظیم شود. |
پارامترهای درخواست (بهروزرسانی توکن دسترسی)
| پارامتر | نوع | مورد نیاز | توضیحات |
|---|---|---|---|
client_id | string | مورد نیاز | شناسه کلاینت برای برنامه شما، که از کنسول Google Cloud دریافت شده است. |
client_secret | string | مورد نیاز | رمز کلاینت برنامه شما، که از کنسول گوگل کلود دریافت شده است. |
grant_type | string | مورد نیاز | باید مطابق تعریفشده در مشخصات OpenID Connect Refresh Token، روی refresh_token تنظیم شود. |
refresh_token | string | مورد نیاز | توکن بهروزرسانی (Refresh Token) که از تبادل کد مجوز (Authorization Code) برگردانده شده است. |
scope | string | اختیاری | فهرستی از محدودههای درخواستشده برای Access Token جدید که با فاصله از هم جدا شدهاند. محدودههای درخواستشده باید زیرمجموعهای از محدودههای اعطاشده در درخواست مجوز اولیه باشند. |
بدنه پاسخ
فیلدهای پاسخ در یک شیء JSON در بدنه پاسخ HTTP به درخواست POST درخواستکننده به https://oauth2.googleapis.com/token بازگردانده میشوند.
| میدان | نوع | توضیحات |
|---|---|---|
access_token | string | توکن دسترسی که میتواند به یک API گوگل ارسال شود. |
expires_in | integer | طول عمر توکن دسترسی (Access Token) بر حسب ثانیه، نسبت به زمان صدور توکن. |
id_token | string | یک توکن وب JSON (JWT) که حاوی اطلاعات هویتی کاربر است. این توکن در طول تبادل اولیه کد مجوز بازگردانده میشود و در صورت اعطای دامنه openid میتواند در طول درخواست Refresh Token نیز بازگردانده شود. |
scope | string | دامنههای دسترسی اعطا شده توسط access_token به صورت فهرستی از رشتههای جدا شده با فاصله و حساس به حروف بزرگ و کوچک بیان میشوند. |
token_type | string | نوع توکن برگشتی. همیشه Bearer . |
refresh_token | string | (اختیاری) توکنی که میتواند برای دریافت توکنهای دسترسی جدید استفاده شود. این فیلد فقط در تبادل اولیه کد مجوز در صورتی که access_type=offline درخواست شده باشد، بازگردانده میشود. |
refresh_token_expires_in | integer | (اختیاری) طول عمر باقیماندهی Refresh Token بر حسب ثانیه. این مقدار فقط زمانی تنظیم میشود که کاربر دسترسی مبتنی بر زمان را اعطا کند. |
پاسخهای خطا
اگر درخواست با شکست مواجه شود، سرور احراز هویت یک شیء JSON با فیلدهای زیر برمیگرداند:
| میدان | نوع | توضیحات |
|---|---|---|
error | string | یک کد خطا. |
error_description | string | شرح خطا در صورت عدم موفقیت درخواست. |
جدول زیر کدهای خطای احتمالی و کدهای وضعیت HTTP مرتبط با آنها را شرح میدهد:
| خطا | کد وضعیت HTTP | توضیحات |
|---|---|---|
invalid_request | 400 | درخواست فاقد پارامتر الزامی است، شامل مقدار پارامتر نامعتبر است، یا به هر نحو دیگری ناقص است. |
invalid_client | 401 | احراز هویت کلاینت ناموفق بود. برای مثال، client_id یا client_secret نامعتبر است، یا نوع کلاینت نادرست است. |
invalid_grant | 400 | کد مجوز، توکن بهروزرسانی یا کد دستگاه ارائه شده نامعتبر، منقضی شده، لغو شده یا با URI تغییر مسیر استفاده شده در درخواست مجوز مطابقت ندارد. |
unauthorized_client | 400 | کلاینت احراز هویت شده مجاز به استفاده از این نوع اعطای مجوز نیست. |
unsupported_grant_type | 400 | نوع اعطای مجوز توسط سرور مجوز پشتیبانی نمیشود. |
invalid_scope | 400 | محدوده درخواستی نامعتبر، ناشناخته یا ناقص است. |
authorization_pending | 428 | (جریان دستگاه) کاربر هنوز جریان مجوز را تکمیل نکرده است. |
slow_down | 429 | (جریان دستگاه) دستگاه درخواستهای نظرسنجی را بیش از حد ارسال میکند. |
access_denied | 403 | (جریان دستگاه) کاربر از اعطای دسترسی به دستگاه خودداری کرد. |
expired_token | 400 | (جریان دستگاه) device_code منقضی شده است. |
admin_policy_enforced | 400 | کاربر به دلیل سیاستهای اعمالشده توسط مدیر Google Workspace خود، قادر به تأیید محدودههای درخواستی نیست. |
org_internal | 403 | شناسه مشتری بخشی از پروژهای است که دسترسی به یک سازمان ابری خاص گوگل را محدود میکند. |
نقطه پایانی احراز هویت دستگاه
نقطه پایانی احراز هویت دستگاه در جریان دستگاه OAuth 2.0 برای دریافت کد کاربری و URL تأیید برای دستگاههایی با قابلیتهای ورودی محدود استفاده میشود.
آدرس اینترنتی: https://oauth2.googleapis.com/device/code
روش درخواست پشتیبانی شده: POST
پارامترهای درخواست
| پارامتر | نوع | مورد نیاز | توضیحات |
|---|---|---|---|
client_id | string | مورد نیاز | شناسه کلاینت برای برنامه شما، که از کنسول Google Cloud دریافت شده است. |
scope | string | مورد نیاز | فهرستی از محدودهها که با فاصله از هم جدا شدهاند و منابعی را که برنامه شما میتواند از طرف کاربر به آنها دسترسی داشته باشد، مشخص میکنند. |
بدنه پاسخ
پاسخ یک شیء JSON است که شامل فیلدهای زیر است:
| میدان | نوع | توضیحات |
|---|---|---|
device_code | string | مقداری که گوگل به طور منحصر به فرد برای شناسایی دستگاهی که برنامه درخواست مجوز را اجرا میکند، اختصاص میدهد. |
user_code | string | یک مقدار حساس به حروف بزرگ و کوچک که به گوگل محدودههایی را که برنامه درخواست دسترسی به آنها را دارد، مشخص میکند. رابط کاربری شما به کاربر دستور میدهد که این مقدار را در یک دستگاه جداگانه با قابلیتهای ورودی غنیتر وارد کند. |
verification_url | string | یک URL که کاربر باید در یک دستگاه جداگانه به آن مراجعه کند تا user_code وارد کند و دسترسی به برنامه شما را اعطا یا رد کند. |
expires_in | integer | مدت زمانی (بر حسب ثانیه) که device_code و user_code معتبر هستند. |
interval | integer | مدت زمانی (برحسب ثانیه) که دستگاه شما باید بین درخواستهای نظرسنجی منتظر بماند. |
نقطه پایانی ابطال
نقطه پایانی ابطال به برنامه شما اجازه میدهد تا یک توکن دسترسی یا یک توکن بهروزرسانی را ابطال کند.
آدرس اینترنتی: https://oauth2.googleapis.com/revoke
روش درخواست پشتیبانی شده: POST
پارامترهای درخواست
| پارامتر | نوع | مورد نیاز | توضیحات |
|---|---|---|---|
token | string | مورد نیاز | توکن دسترسی یا توکن بهروزرسانی که میخواهید لغو کنید. |
بدنه پاسخ
اگر لغو موفقیتآمیز باشد، پاسخ یک HTTP 200 OK خالی است. اگر لغو ناموفق باشد، یک پاسخ خطا در یک شیء JSON بازگردانده میشود.
| میدان | نوع | توضیحات |
|---|---|---|
error | string | کد خطا در صورت عدم موفقیت درخواست. |
error_description | string | شرح خطا در صورت عدم موفقیت درخواست. |
جدول زیر کدهای خطای احتمالی را شرح میدهد:
| خطا | توضیحات |
|---|---|
invalid_token | توکن ارائه شده در درخواست، منقضی شده یا لغو شده است. |
invalid_request | درخواست فاقد پارامتر الزامی است، شامل مقدار پارامتر نامعتبر است، یا به هر نحو دیگری ناقص است. |
نقطه پایانی اطلاعات کاربری
UserInfo Endpoint اطلاعات پروفایل مربوط به کاربر احراز هویت شده را برمیگرداند.
آدرس اینترنتی: https://openidconnect.googleapis.com/v1/userinfo
روشهای درخواست پشتیبانیشده: GET ، POST
درخواست سربرگها
| سربرگ | توضیحات |
|---|---|
Authorization | الزامی. باید روی Bearer: access_token تنظیم شود. |
بدنه پاسخ
فیلدهای پاسخ در یک شیء JSON در بدنه پاسخ HTTP به درخواست GET یا POST درخواستکننده به آدرس https://openidconnect.googleapis.com/v1/userinfo بازگردانده میشوند.
| میدان | نوع | توضیحات |
|---|---|---|
sub | string | الزامی. شناسهای برای کاربر، منحصر به فرد در بین تمام حسابهای گوگل و هرگز دوباره استفاده نمیشود. رشتهای حساس به حروف بزرگ و کوچک که بیش از ۲۵۵ کاراکتر نباشد. |
name | string | نام کامل کاربر، به شکلی قابل نمایش. |
given_name | string | نام (های) کوچک یا نام کوچک کاربر. |
family_name | string | نام خانوادگی یا نام خانوادگی کاربر. |
picture | string | آدرس اینترنتی (URL) تصویر پروفایل کاربر. |
email | string | آدرس ایمیل کاربر. |
email_verified | boolean | اینکه آیا آدرس ایمیل کاربر تأیید شده است یا خیر. |
hd | string | دامنه میزبانیشده مرتبط با سازمان Google Workspace یا Cloud کاربر. |
نقطه پایانی Tokeninfo
نقطه پایانی tokeninfo یک پیادهسازی مخصوص گوگل است که برای اعتبارسنجی یک توکن ID به منظور اشکالزدایی استفاده میشود.
آدرس اینترنتی: https://oauth2.googleapis.com/tokeninfo
روشهای درخواست پشتیبانیشده: GET ، POST
پارامترهای درخواست
| پارامتر | نوع | مورد نیاز | توضیحات |
|---|---|---|---|
id_token | string | مورد نیاز | توکن شناسایی برای اعتبارسنجی. |
بدنه پاسخ
فیلدهای پاسخ در یک شیء JSON در بدنه پاسخ HTTP به درخواست GET یا POST درخواستکننده به https://oauth2.googleapis.com/tokeninfo بازگردانده میشوند.
| میدان | نوع | توضیحات |
|---|---|---|
iss | string | شناسه صادرکننده. همیشه https://accounts.google.com . |
sub | string | شناسهای برای کاربر، منحصر به فرد در بین تمام حسابهای گوگل و هرگز دوباره استفاده نمیشود. |
aud | string | مخاطبی که توکن شناسایی برای آن در نظر گرفته شده است. این شناسه کلاینت برنامه شما است که از کنسول Google Cloud دریافت شده است. |
iat | integer | زمانی که JWT صادر شده است. به صورت تعداد ثانیهها از تاریخ 1970-01-01T0:0:0Z و بر حسب UTC نمایش داده میشود. |
exp | integer | زمان انقضایی که در آن یا پس از آن، توکن شناسه نباید برای پردازش پذیرفته شود. به صورت تعداد ثانیهها از 1970-01-01T0:0:0Z و بر حسب UTC نمایش داده میشود. |
email | string | آدرس ایمیل کاربر. |
email_verified | string | آیا آدرس ایمیل کاربر تأیید شده است یا خیر. مقدار آن رشتهای از نوع "true" یا "false" است. |
access_type | string | نوع دسترسی درخواست شده در درخواست مجوز اولیه. |
azp | string | شناسهی کلاینتِ ارائهدهندهی مجاز، که از کنسول گوگل کلود دریافت شده است. |
scope | string | فهرست محدودههای مجاز اعطا شده به توکن که با فاصله از هم جدا شدهاند. |
alg | string | الگوریتمی که برای امضای شناسه توکن استفاده میشود. |
kid | string | شناسه کلید مورد استفاده برای امضای شناسه توکن. |
typ | string | نوع توکن. همیشه JWT . |