پیوند هویت - OAuth 2.0

برای فعال کردن جلسات کاربری یکپارچه (مثلاً دسترسی به مزایای وفاداری، پیشنهادات شخصی‌سازی‌شده) و پرداخت‌های احراز هویت‌شده، باید قابلیت پیوند هویت را با استفاده از OAuth 2.0 پیاده‌سازی کنید. اگر پیوند هویت را پیاده‌سازی نمی‌کنید، باید از تجربیات مهمان پشتیبانی کنید.

در مورد هرگونه سؤالی در مورد مقررات حفظ حریم خصوصی و شیوه‌های رضایت، با تیم حقوقی خود مشورت کنید.

الزامات اصلی

پیوند هویت از OAuth 2.0 برای پیوند حساب‌های کاربری استفاده می‌کند. پیاده‌سازی OAuth 2.0 شما باید الزامات مستند شده در OAuth Linking را برآورده کند.

علاوه بر این، برای همسو شدن با بهترین شیوه‌های امنیتی پروتکل تجارت جهانی (UCP)، اکیداً توصیه می‌کنیم که از کلید اثبات برای تبادل کد (PKCE) با استفاده از S256 برای همه تبادلات کد مجوز استفاده کنید و از احراز هویت نامتقارن کلاینت (مانند private_key_jwt یا tls_client_auth ) در نقطه پایانی توکن خود استفاده کنید.

برای اطلاعات بیشتر اینجا را بخوانید: دستورالعمل‌های عمومی UCP .

محدوده‌ها

شما باید محدوده‌های زیر را پیاده‌سازی کنید که به شما اجازه می‌دهند تمام عملیات چرخه حیات پرداخت (ایجاد، به‌روزرسانی، تکمیل) و همچنین داده‌های سفارش را بخوانید.

• dev.ucp.shopping.order:read
• dev.ucp.shopping.checkout:manage

توجه: شما باید محدوده‌های درخواستی را به عنوان یک صفحه رضایت واحد و یکپارچه (مثلاً «به Google اجازه دهید جلسات پرداخت شما را مدیریت کند») ارائه دهید، نه به صورت گزینه‌های فنی جزئی و تفکیک‌شده.

استفاده از توکن

وقتی کاربری حساب خود را لینک می‌کند، گوگل توکن دسترسی کاربر را در هدر HTTP مربوط به Authorization برای تمام عملیات چرخه حیات پرداخت (ایجاد، به‌روزرسانی، تکمیل) و درخواست‌های داده‌های سفارش قرار می‌دهد:

Authorization: Bearer <access_token>

این همان هدری است که برای احراز هویت ماشین به ماشین استفاده می‌شود.

مدیریت خطا

وقتی یک عملیات احراز هویت کاربر به دلیل مشکل هویت با شکست مواجه می‌شود، شما باید طبق RFC 6750 یک هدر چالش WWW-Authenticate: Bearer به همراه کد وضعیت HTTP و پیام خطای UCP مناسب ارسال کنید.

identity_required

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

• وضعیت HTTP: 401 Unauthorized
• کد خطای UCP: identity_required
• WWW-Authenticate: realm="<your-issuer-uri>" نیز وارد کنید. اگر توکنی وجود داشت اما نامعتبر/منقضی شده بود، error="invalid_token" نیز وارد کنید.

دامنه_ناکافی

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

• وضعیت HTTP: 403 Forbidden
• کد خطای UCP: insufficient_scope
• WWW-Authenticate: شامل realm="<your-issuer-uri>" ، error="insufficient_scope" و scope="<space-separated list of required scopes>" .

پیوند هویت تبلیغاتی

شما باید قابلیت پیوند هویت را در پروفایل UCP خود اعلام کنید. برای مثالی از نحوه فهرست کردن این قابلیت، به پروفایل UCP مراجعه کنید.

لینک سازی ساده گوگل

Google Streamlined Linking یک افزونه اختیاری برای استاندارد OAuth 2.0 است. این افزونه از JWT assertionها برای ترکیب بررسی‌های intent و تبادل توکن در نقطه پایانی توکن OAuth 2.0 ( check ، create ، get intents) استفاده می‌کند.

لینک‌سازی ساده گوگل (Google Streamlined Linking) برای یک تجربه کاربری روان توصیه می‌شود. این روش به کاربران اجازه می‌دهد تا حساب‌های کاربری خود را بدون ترک رابط کاربری گوگل، به یکدیگر لینک دهند یا حساب‌های کاربری جدیدی ایجاد کنند. از آنجا که این جریان کاملاً در رابط کاربری گوگل رخ می‌دهد، نیازی به رابط کاربری لینک‌سازی نیست. این امر سربار توسعه را کاهش می‌دهد، ریدایرکت‌های مرورگر را حذف می‌کند و می‌تواند نرخ تبدیل را افزایش دهد.

• مشخصات: پیاده‌سازی باید از الزامات پیوند ساده پیروی کند.
• استانداردها: اگرچه مفاهیم را از RFC 7523 وام می‌گیرد، اما برای افزایش امنیت متفاوت است.

فراداده سرور احراز هویت (مثال JSON)

شما باید ابرداده سرور تأیید خود را در آدرس زیر منتشر کنید:

GET https://YOUR_DOMAIN/.well-known/oauth-authorization-server

مثال زیر نشان می‌دهد که این مورد چه شکلی می‌تواند داشته باشد:

{
  "issuer": "https://merchant.example.com",
  "authorization_endpoint": "https://merchant.example.com/oauth2/authorize",
  "token_endpoint": "https://merchant.example.com/oauth2/token",
  "revocation_endpoint": "https://merchant.example.com/oauth2/revoke",
  "scopes_supported": [
    "dev.ucp.shopping.order:read",
    "dev.ucp.shopping.checkout:manage"
  ],
  "response_types_supported": [
    "code"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic"
  ],
  "service_documentation": "https://merchant.example.com/docs/oauth2"
}