راهنمای توسعه‌دهنده API مدیریت اعتبار فدرال، راهنمای توسعه‌دهنده API مدیریت اعتبار فدرال

یاد بگیرید که چگونه از FedCM برای فدراسیون حفظ حریم خصوصی استفاده کنید.

FedCM (مدیریت اعتبار فدرال) یک رویکرد حفظ حریم خصوصی برای خدمات هویتی فدرال (مانند "ورود به سیستم با...") است که در آن کاربران می توانند بدون به اشتراک گذاشتن اطلاعات شخصی خود با سرویس هویت یا سایت وارد سایت ها شوند.

برای کسب اطلاعات بیشتر در مورد موارد استفاده FedCM، جریان های کاربر و نقشه راه API ، مقدمه FedCM API را بررسی کنید.

محیط توسعه FedCM

برای استفاده از FedCM به یک زمینه امن (HTTPS یا localhost) هم در IdP و هم در RP در کروم نیاز دارید.

کد اشکال زدایی در کروم در اندروید

برای رفع اشکال کد FedCM خود، سروری را به صورت محلی تنظیم و اجرا کنید. می‌توانید در Chrome در دستگاه Android متصل شده با استفاده از کابل USB با پورت فوروارد به این سرور دسترسی داشته باشید .

می‌توانید از DevTools در دسک‌تاپ برای اشکال‌زدایی Chrome در Android با پیروی از دستورالعمل‌های Remote Debug دستگاه‌های Android استفاده کنید.

کوکی‌های شخص ثالث را در Chrome مسدود کنید

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

می‌توانید قبل از اجرای واقعی FedCM بدون کوکی‌های شخص ثالث در Chrome آزمایش کنید.

برای مسدود کردن کوکی‌های شخص ثالث، از حالت ناشناس استفاده کنید یا «مسدود کوکی‌های شخص ثالث» را در تنظیمات دسک‌تاپ خود در chrome://settings/cookies یا در تلفن همراه با رفتن به تنظیمات > تنظیمات سایت > کوکی‌ها انتخاب کنید.

با استفاده از FedCM API

شما با ایجاد یک فایل شناخته شده ، فایل پیکربندی و نقاط پایانی برای لیست حساب ها ، صدور ادعا و به صورت اختیاری ابرداده مشتری ، با FedCM ادغام می شوید.

از آنجا، FedCM API های جاوا اسکریپت را نشان می دهد که RP ها می توانند برای ورود به سیستم با IdP از آنها استفاده کنند.

یک فایل شناخته شده ایجاد کنید

برای جلوگیری از سوء استفاده ردیاب‌ها از API ، یک فایل شناخته شده باید از /.well-known/web-identity eTLD+1 IdP ارائه شود.

به عنوان مثال، اگر نقاط پایانی IdP تحت https://accounts.idp.example/ ارائه می شوند، باید یک فایل شناخته شده در https://idp.example/.well-known/web-identity و همچنین یک فایل ارائه دهند. فایل پیکربندی IdP . در اینجا یک نمونه از محتوای فایل معروف است:

{
  "provider_urls": ["https://accounts.idp.example/config.json"]
}

فایل JSON باید دارای ویژگی provider_urls با آرایه‌ای از URLهای فایل پیکربندی IdP باشد که می‌تواند به عنوان بخشی از مسیر configURL در navigator.credentials.get توسط RP‌ها مشخص شود. تعداد رشته‌های URL در آرایه به یک رشته محدود است، اما ممکن است با بازخورد شما در آینده تغییر کند.

یک فایل پیکربندی IdP و نقاط پایانی ایجاد کنید

فایل پیکربندی IdP لیستی از نقاط پایانی مورد نیاز برای مرورگر را ارائه می دهد. IdP ها میزبان این فایل پیکربندی و نقاط پایانی و URL های مورد نیاز خواهند بود. همه پاسخ‌های JSON باید با نوع محتوای application/json ارائه شوند.

URL فایل پیکربندی با مقادیر ارائه شده به تماس navigator.credentials.get که در یک RP انجام می شود تعیین می شود.

const credential = await navigator.credentials.get({
  identity: {
    context: 'signup',
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

URL کامل محل فایل پیکربندی IdP را به عنوان configURL مشخص کنید. هنگامی که navigator.credentials.get() در RP فراخوانی می شود ، مرورگر فایل پیکربندی را با یک درخواست GET بدون سرصفحه Origin یا هدر Referer واکشی می کند. درخواست کوکی ندارد و از تغییر مسیرها پیروی نمی کند. این به طور موثری از IdP جلوگیری می‌کند که بفهمد چه کسی درخواست را انجام داده و کدام RP را در تلاش برای اتصال است. به عنوان مثال:

GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity

مرورگر یک پاسخ JSON از IdP انتظار دارد که شامل ویژگی های زیر است:

اموال توضیحات
accounts_endpoint (الزامی) URL برای نقطه پایانی حساب‌ها .
client_metadata_endpoint (اختیاری) URL برای نقطه پایانی فراداده مشتری .
id_assertion_endpoint (الزامی) URL برای نقطه پایانی ادعای شناسه .
disconnect (اختیاری) URL برای نقطه پایانی قطع ارتباط .
login_url (الزامی) آدرس صفحه ورود به سیستم برای ورود کاربر به IdP.
branding (اختیاری) شیئی که شامل گزینه های مختلف برندسازی است.
branding.background_color (اختیاری) گزینه برندینگ که رنگ پس‌زمینه دکمه «ادامه به‌عنوان...» را تنظیم می‌کند. از نحو CSS مربوطه، یعنی hex-color ، hsl() rgb() یا named-color استفاده کنید.
branding.color (اختیاری) گزینه برندینگ که رنگ متن دکمه "ادامه به عنوان..." را تنظیم می کند. از نحو CSS مربوطه، یعنی hex-color ، hsl() rgb() یا named-color استفاده کنید.
branding.icons (اختیاری) گزینه برندینگ که شی نماد نمایش داده شده در گفتگوی ورود را تنظیم می کند. شی نماد آرایه ای با دو پارامتر است:
  • url (الزامی): URL تصویر نماد. این از تصاویر SVG پشتیبانی نمی کند.
  • size (اختیاری): ابعاد نماد، که توسط برنامه به صورت مربع و وضوح تک فرض شده است. این عدد باید بزرگتر یا مساوی 25 باشد.

RP می تواند رشته را در رابط کاربری گفتگوی FedCM از طریق مقدار () identity.context برای navigator.credentials.get() تغییر دهد تا زمینه های احراز هویت از پیش تعریف شده را در خود جای دهد. ویژگی اختیاری می تواند یکی از "signin" (پیش فرض)، "signup" ، "use" یا "continue" باشد.

نحوه اعمال نام تجاری در گفتگوی FedCM
نحوه اعمال نام تجاری در گفتگوی FedCM

در اینجا یک نمونه بدن پاسخ از IdP آمده است:

{
  "accounts_endpoint": "/accounts.php",
  "client_metadata_endpoint": "/client_metadata.php",
  "id_assertion_endpoint": "/assertion.php",
  "disconnect_endpoint": "/disconnect.php",
  "login_url": "/login",
  "branding": {
    "background_color": "green",
    "color": "#FFEEAA",
    "icons": [{
      "url": "https://idp.example/icon.ico",
      "size": 25
    }]
  }
}

هنگامی که مرورگر فایل پیکربندی را واکشی می کند، درخواست های بعدی را به نقاط پایانی IdP ارسال می کند:

نقاط پایانی IdP
نقاط پایانی IdP

نقطه پایانی حساب ها

نقطه پایانی حساب های IdP لیستی از حساب هایی را که کاربر در حال حاضر در IdP وارد آنها شده است، برمی گرداند. اگر IdP از چندین حساب پشتیبانی کند، این نقطه پایانی همه حساب‌های وارد شده را برمی‌گرداند.

مرورگر یک درخواست GET را با کوکی‌هایی با SameSite=None ارسال می‌کند، اما بدون پارامتر client_id ، سرصفحه Origin یا Referer . این به طور موثری از IdP جلوگیری می کند تا یاد بگیرد که کاربر قصد دارد به کدام RP وارد شود. به عنوان مثال:

GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

پس از دریافت درخواست، سرور باید:

  1. بررسی کنید که درخواست حاوی سرصفحه HTTP Sec-Fetch-Dest: webidentity باشد.
  2. کوکی‌های جلسه را با شناسه‌های حساب‌هایی که قبلاً وارد سیستم شده‌اند مطابقت دهید.
  3. با لیست حساب ها پاسخ دهید.

مرورگر انتظار پاسخ JSON را دارد که شامل یک ویژگی accounts با آرایه ای از اطلاعات حساب با ویژگی های زیر است:

اموال توضیحات
id (الزامی) شناسه منحصر به فرد کاربر
name (الزامی) نام و نام خانوادگی کاربر.
email (الزامی) آدرس ایمیل کاربر.
given_name (اختیاری) نام کاربر.
picture (اختیاری) URL تصویر آواتار کاربر.
approved_clients (اختیاری) آرایه ای از شناسه های مشتری RP که کاربر با آن ثبت نام کرده است.
login_hints (اختیاری) آرایه ای از انواع فیلترهای ممکن که IdP برای تعیین یک حساب پشتیبانی می کند. RP می تواند navigator.credentials.get() را با ویژگی loginHint فراخوانی کند تا به صورت انتخابی حساب مشخص شده را نشان دهد.
domain_hints (اختیاری) آرایه ای از تمام دامنه هایی که حساب با آنها مرتبط است. RP می‌تواند navigator.credentials.get() را با ویژگی domainHint فراخوانی کند تا حساب‌ها را فیلتر کند.

نمونه بدن پاسخ:

{
  "accounts": [{
    "id": "1234",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "approved_clients": ["123", "456", "789"],
    "login_hints": ["demo1", "demo1@idp.example"]
  }, {
    "id": "5678",
    "given_name": "Johnny",
    "name": "Johnny",
    "email": "johnny@idp.example",
    "picture": "https://idp.example/profile/456",
    "approved_clients": ["abc", "def", "ghi"],
    "login_hints": ["demo2", "demo2@idp.example"],
    "domain_hints": ["corp.example"]
  }]
}

اگر کاربر وارد سیستم نشده است، با HTTP 401 (غیر مجاز) پاسخ دهید.

لیست حساب های برگشتی توسط مرورگر مصرف می شود و برای RP در دسترس نخواهد بود.

نقطه پایانی فراداده مشتری

نقطه پایانی فراداده مشتری IdP، فراداده طرف متکی را مانند خط مشی رازداری و شرایط خدمات RP را برمی گرداند. RP ها باید پیوندهایی به خط مشی رازداری و شرایط خدمات خود را از قبل در اختیار IdP قرار دهند. زمانی که کاربر هنوز در RP با IdP ثبت نام نکرده باشد، این پیوندها در گفتگوی ورود به سیستم نمایش داده می شوند.

مرورگر یک درخواست GET را با استفاده از client_id navigator.credentials.get بدون کوکی ارسال می کند. به عنوان مثال:

GET /client_metadata.php?client_id=1234 HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Accept: application/json
Sec-Fetch-Dest: webidentity

پس از دریافت درخواست، سرور باید:

  1. RP را برای client_id تعیین کنید.
  2. با فراداده مشتری پاسخ دهید.

ویژگی‌های نقطه پایانی فراداده مشتری عبارتند از:

اموال توضیحات
privacy_policy_url (اختیاری) URL خط مشی رازداری RP.
terms_of_service_url (اختیاری) URL شرایط خدمات RP.

مرورگر انتظار پاسخ JSON را از نقطه پایانی دارد:

{
  "privacy_policy_url": "https://rp.example/privacy_policy.html",
  "terms_of_service_url": "https://rp.example/terms_of_service.html",
}

ابرداده مشتری برگشتی توسط مرورگر مصرف می شود و برای RP در دسترس نخواهد بود.

نقطه پایان ادعای شناسه

نقطه پایانی ادعای شناسه IdP یک ادعا را برای کاربر واردشده به سیستم باز می‌گرداند. هنگامی که کاربر با استفاده از navigator.credentials.get() وارد یک وب سایت RP می شود، مرورگر یک درخواست POST با کوکی هایی با SameSite=None و یک نوع محتوا از application/x-www-form-urlencoded به این نقطه پایانی ارسال می کند. اطلاعات زیر:

اموال توضیحات
client_id (الزامی) شناسه مشتری RP.
account_id (الزامی) شناسه منحصر به فرد کاربر در حال ورود به سیستم.
nonce (اختیاری) درخواست هیچ، ارائه شده توسط RP.
disclosure_text_shown نتیجه در یک رشته "true" یا "false" (به جای یک بولی). اگر متن افشا نشان داده نشود، نتیجه "false" است. این زمانی اتفاق می‌افتد که شناسه مشتری RP در لیست ویژگی‌های approved_clients پاسخ از نقطه پایانی حساب‌ها گنجانده شده باشد یا اگر مرورگر در گذشته یک لحظه ثبت‌نام را در غیاب approved_clients مشاهده کرده باشد.
is_auto_selected اگر احراز هویت مجدد خودکار در RP انجام شود، is_auto_selected نشان دهنده "true" است. در غیر این صورت "false" . این برای پشتیبانی بیشتر از ویژگی های مرتبط با امنیت مفید است. به عنوان مثال، برخی از کاربران ممکن است سطح امنیتی بالاتری را ترجیح دهند که نیاز به میانجیگری صریح کاربر در احراز هویت دارد. اگر یک IdP یک درخواست توکن را بدون چنین میانجی‌گری دریافت کند، می‌تواند درخواست را به گونه‌ای متفاوت مدیریت کند. به عنوان مثال، یک کد خطایی را برگردانید به طوری که RP بتواند دوباره FedCM API را با mediation: required .

هدر HTTP مثال:

POST /assertion.php HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true&is_auto_selected=true

پس از دریافت درخواست، سرور باید:

  1. با CORS (اشتراک گذاری منابع متقابل) به درخواست پاسخ دهید.
  2. بررسی کنید که درخواست حاوی سرصفحه HTTP Sec-Fetch-Dest: webidentity باشد.
  3. هدر Origin را با مبدا RP که توسط client_id تعیین می شود مطابقت دهید. اگر مطابقت نداشتند رد کنید.
  4. account_id با شناسه حسابی که قبلاً وارد سیستم شده‌اید مطابقت دهید. اگر مطابقت نداشتند رد کنید.
  5. با یک نشانه پاسخ دهید. اگر درخواست رد شد، با یک پاسخ خطا پاسخ دهید.

نحوه صدور توکن به IdP بستگی دارد، اما به طور کلی، با اطلاعاتی مانند شناسه حساب، شناسه مشتری، مبدا صادرکننده، nonce امضا می شود تا RP بتواند اصل بودن توکن را تأیید کند.

مرورگر انتظار پاسخ JSON را دارد که شامل ویژگی زیر است:

اموال توضیحات
token (الزامی) توکن رشته‌ای است که حاوی ادعاهایی درباره احراز هویت است.
{
  "token": "***********"
}

توکن برگشتی توسط مرورگر به RP ارسال می شود تا RP بتواند احراز هویت را تأیید کند.

پاسخ خطا را برگردانید

id_assertion_endpoint همچنین می تواند یک پاسخ "خطا" را برگرداند که دارای دو فیلد اختیاری است:

  • code : IdP می تواند یکی از خطاهای شناخته شده را از لیست خطاهای مشخص شده OAuth 2.0 ( invalid_request ، unauthorized_client ، access_denied ، server_error و temporarily_unavailable ) انتخاب کند یا از هر رشته دلخواه استفاده کند. اگر مورد دوم باشد، Chrome رابط کاربری خطا را با یک پیام خطای عمومی ارائه می‌کند و کد را به RP ارسال می‌کند.
  • url : یک صفحه وب قابل خواندن توسط انسان را با اطلاعات مربوط به خطا شناسایی می کند تا اطلاعات بیشتری در مورد خطا به کاربران ارائه دهد. این فیلد برای کاربران مفید است زیرا مرورگرها نمی توانند پیام های خطای غنی را در یک رابط کاربری بومی ارائه کنند. به عنوان مثال، پیوندهایی برای مراحل بعدی، اطلاعات تماس خدمات مشتری و غیره. اگر کاربر می‌خواهد درباره جزئیات خطا و نحوه رفع آن اطلاعات بیشتری کسب کند، می‌تواند برای جزئیات بیشتر به صفحه ارائه شده از رابط کاربری مرورگر مراجعه کند. URL باید همان سایتی باشد که IdP configURL . 
// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

نقطه پایانی را قطع کنید

با فراخوانی IdentityCredential.disconnect() ، مرورگر یک درخواست POST متقاطع را با کوکی هایی با SameSite=None و یک نوع محتوا از application/x-www-form-urlencoded به این نقطه پایانی قطع با اطلاعات زیر ارسال می کند:

اموال توضیحات
account_hint راهنمایی برای حساب IdP..
client_id شناسه مشتری RP.
POST /disconnect.php HTTP/1.1
Host: idp.example
Origin: rp.example
Content-Type: application/x-www-form-urlencoded
Cookie: 0x123
Sec-Fetch-Dest: webidentity

account_hint=account456&client_id=rp123

پس از دریافت درخواست، سرور باید:

  1. با CORS (اشتراک گذاری منابع متقابل) به درخواست پاسخ دهید.
  2. بررسی کنید که درخواست حاوی سرصفحه HTTP Sec-Fetch-Dest: webidentity باشد.
  3. هدر Origin را با مبدا RP که توسط client_id تعیین می شود مطابقت دهید. اگر مطابقت نداشتند رد کنید.
  4. account_hint با شناسه‌های حساب‌هایی که قبلاً وارد سیستم شده‌اند مطابقت دهید.
  5. حساب کاربری را از RP جدا کنید.
  6. با اطلاعات حساب کاربری شناسایی شده در قالب JSON به مرورگر پاسخ دهید.

یک نمونه پاسخ JSON payload به این صورت است: 

{
  "account_id": "account456"
}

در عوض، اگر IdP بخواهد مرورگر همه حساب‌های مرتبط با RP را قطع کند، رشته‌ای را ارسال کنید که با هیچ شناسه حسابی مطابقت ندارد، به عنوان مثال "*" .

URL ورود

با Login Status API ، IdP باید وضعیت ورود کاربر را به مرورگر اطلاع دهد. با این حال، وضعیت ممکن است هماهنگ نباشد، مانند زمانی که جلسه منقضی شود . در چنین سناریویی، مرورگر می تواند به صورت پویا به کاربر اجازه دهد از طریق URL صفحه ورود مشخص شده با login_url فایل پیکربندی idp وارد IdP شود.

همانطور که در تصویر زیر نشان داده شده است، کادر گفتگوی FedCM پیامی را نشان می دهد که ورود به سیستم را پیشنهاد می کند.

الف
گفتگوی FedCM که پیشنهاد می کند به IdP وارد شوید.

هنگامی که کاربر روی دکمه Continue کلیک می کند، مرورگر یک پنجره بازشو برای صفحه ورود IdP باز می کند.

یک
یک گفتگوی مثال پس از کلیک بر روی ورود به دکمه IdP نشان داده شده است.

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

  • هدر Set-Login: logged-in ارسال کنید یا با navigator.login.setStatus("logged-in") API تماس بگیرید تا به مرورگر اطلاع دهید که کاربر وارد سیستم شده است.
  • برای بستن دیالوگ IdentityProvider.close() را فراخوانی کنید.
الف
کاربر پس از ورود به IdP با استفاده از FedCM وارد RP می شود.

مرورگر را در مورد وضعیت ورود کاربر در ارائه دهنده هویت مطلع کنید

Login Status API مکانیزمی است که در آن یک وب سایت، به ویژه یک IdP، وضعیت ورود کاربر را در IdP به مرورگر اطلاع می دهد. با این API، مرورگر می‌تواند درخواست‌های غیرضروری را به IdP کاهش دهد و حملات احتمالی زمان‌بندی را کاهش دهد.

IdP ها می توانند با ارسال یک هدر HTTP یا با فراخوانی یک API جاوا اسکریپت هنگام ورود کاربر به سیستم IdP یا زمانی که کاربر از تمام حساب های IdP خود خارج شده است، وضعیت ورود به سیستم کاربر را به مرورگر سیگنال دهند. برای هر IdP (که توسط URL پیکربندی آن مشخص می شود) مرورگر یک متغیر سه حالته را نگه می دارد که نشان دهنده وضعیت ورود به سیستم با مقادیر احتمالی logged-in ، logged-out و unknown . حالت پیش فرض unknown است.

برای نشان دادن اینکه کاربر وارد سیستم شده است، یک سرصفحه HTTP Set-Login: logged-in در یک ناوبری سطح بالا یا یک درخواست منبع فرعی همان سایت در مبدا IdP ارسال کنید: 

Set-Login: logged-in

همچنین، JavaScript API navigator.login.setStatus("logged-in") از مبدا IdP در یک پیمایش سطح بالا فراخوانی کنید: 

navigator.login.setStatus("logged-in")

این تماس‌ها وضعیت ورود کاربر را به‌عنوان logged-in ثبت می‌کنند. هنگامی که وضعیت ورود کاربر logged-in است، RP که FedCM را فرا می‌خواند، درخواست‌هایی را به نقطه پایانی حساب‌های IdP می‌دهد و حساب‌های موجود را در گفتگوی FedCM به کاربر نمایش می‌دهد.

برای اینکه نشان دهید کاربر از همه حساب‌های خود خارج شده است، سرصفحه HTTP Set-Login: logged-out در یک ناوبری سطح بالا یا یک درخواست منبع فرعی همان سایت در مبدا IdP ارسال کنید: 

Set-Login: logged-out

همچنین، JavaScript API navigator.login.setStatus("logged-out") از مبدا IdP در یک ناوبری سطح بالا فراخوانی کنید: 

navigator.login.setStatus("logged-out")

این تماس‌ها وضعیت ورود کاربر را به‌عنوان logged-out ثبت می‌کنند. هنگامی که وضعیت ورود به سیستم کاربر logged-out می‌شود، فراخوانی FedCM بی‌صدا بدون درخواست به نقطه پایانی حساب‌های IdP انجام نمی‌شود.

وضعیت unknown قبل از ارسال سیگنال توسط IdP با استفاده از Login Status API تنظیم می شود. Unknown برای انتقال بهتر معرفی شد، زیرا ممکن است کاربر از قبل در هنگام ارسال این API وارد IdP شده باشد. ممکن است تا زمانی که FedCM برای اولین بار فراخوانی می شود، IdP فرصتی برای ارسال این سیگنال به مرورگر نداشته باشد. در این مورد، Chrome به نقطه پایانی حساب‌های IdP درخواست می‌کند و وضعیت را براساس پاسخ نقطه پایانی حساب‌ها به‌روزرسانی می‌کند:

  • اگر نقطه پایانی فهرستی از حساب‌های فعال را برمی‌گرداند، وضعیت را به logged-in به‌روزرسانی کنید و کادر گفتگوی FedCM را برای نمایش آن حساب‌ها باز کنید.
  • اگر نقطه پایانی هیچ حسابی برگرداند، وضعیت را به logged-out به‌روزرسانی کنید و تماس FedCM ناموفق باشد.

به کاربر اجازه دهید از طریق یک جریان ورود پویا وارد سیستم شود

حتی اگر IdP وضعیت ورود کاربر به مرورگر را به اطلاع می‌رساند، ممکن است مانند زمانی که جلسه منقضی می‌شود، هماهنگ نباشد. هنگامی که وضعیت ورود به سیستم logged-in مرورگر سعی می‌کند یک درخواست اعتبارسنجی را به نقطه پایانی حساب‌ها ارسال کند، اما سرور هیچ حسابی برمی‌گرداند زیرا جلسه دیگر در دسترس نیست. در چنین سناریویی، مرورگر می‌تواند به صورت پویا به کاربر اجازه دهد از طریق یک پنجره بازشو به IdP وارد شود .

با ارائه دهنده هویت به طرف متکی وارد شوید

هنگامی که پیکربندی و نقاط پایانی IdP در دسترس هستند، RP ها می توانند با فراخوانی navigator.credentials.get() درخواست کنند تا کاربران بتوانند با IdP وارد RP شوند.

قبل از تماس با API، باید تأیید کنید که [FedCM در مرورگر کاربر موجود است]. برای بررسی اینکه آیا FedCM در دسترس است، این کد را در اطراف پیاده سازی FedCM خود بپیچید: 

if ('IdentityCredential' in window) {
  // If the feature is available, take action
}

برای درخواست اجازه دادن به کاربران برای ورود به IdP از RP، به عنوان مثال موارد زیر را انجام دهید: 

const credential = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

ویژگی providers آرایه ای از اشیاء IdentityProvider را می گیرد که دارای ویژگی های زیر هستند:

اموال توضیحات
configURL (الزامی) مسیر کامل فایل پیکربندی IdP.
clientId (الزامی) شناسه مشتری RP، صادر شده توسط IdP.
nonce (اختیاری) یک رشته تصادفی برای اطمینان از صدور پاسخ برای این درخواست خاص. از حملات تکراری جلوگیری می کند.
loginHint (اختیاری) با مشخص کردن یکی از مقادیر login_hints ارائه شده توسط نقاط پایانی حساب ها ، گفتگوی FedCM به صورت انتخابی حساب مشخص شده را نشان می دهد.
domainHint (اختیاری) با مشخص کردن یکی از مقادیر domain_hints ارائه شده توسط نقاط پایانی حساب ها ، گفتگوی FedCM به صورت انتخابی حساب مشخص شده را نشان می دهد.

مرورگر بسته به وجود approved_clients در پاسخ از نقطه پایانی فهرست حساب‌ها، موارد استفاده از ثبت نام و ورود به سیستم را متفاوت مدیریت می‌کند. اگر کاربر قبلاً در RP ثبت نام کرده باشد، مرورگر متن افشای "برای ادامه با ..." را نمایش نمی دهد.

وضعیت ثبت نام بر اساس رعایت یا عدم رعایت شرایط زیر تعیین می شود:

  • اگر approved_clients شامل clientId RP باشد.
  • اگر مرورگر به خاطر آورد که کاربر قبلاً در RP ثبت نام کرده است.
کاربر با استفاده از FedCM وارد RP می شود

هنگامی که RP navigator.credentials.get() را فرا می خواند، فعالیت های زیر انجام می شود:

  1. مرورگر درخواست ها را ارسال می کند و چندین سند را واکشی می کند:
    1. فایل شناخته شده و یک فایل پیکربندی IdP که نقاط پایانی را اعلام می کند.
    2. لیست حساب ها
    3. اختیاری: نشانی‌های وب برای خط‌مشی رازداری و شرایط خدمات RP، بازیابی شده از نقطه پایانی فراداده مشتری .
  2. مرورگر فهرستی از حساب‌هایی را که کاربر می‌تواند برای ورود به سیستم از آن‌ها استفاده کند، و همچنین شرایط خدمات و خط‌مشی رازداری در صورت وجود را نمایش می‌دهد.
  3. هنگامی که کاربر حسابی را برای ورود به سیستم انتخاب کرد، یک درخواست به نقطه پایانی ادعای ID برای بازیابی یک نشانه به IdP ارسال می شود.
  4. RP می تواند توکن را برای احراز هویت کاربر تأیید کند.
تماس API ورود به سیستم
تماس API ورود به سیستم

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

هنگامی که رمز توسط سرور RP تأیید شد، RP ممکن است کاربر را ثبت کند یا به او اجازه ورود به سیستم و شروع یک جلسه جدید را بدهد.

Login Hint API

پس از ورود کاربر به سیستم، گاهی اوقات طرف متکی (RP) از کاربر می خواهد که احراز هویت مجدد را انجام دهد. اما کاربر ممکن است مطمئن نباشد که از کدام حساب استفاده کرده است. اگر RP بتواند مشخص کند که با کدام حساب وارد شود، انتخاب حساب برای کاربر آسان تر خواهد بود.

RP ها می توانند به طور انتخابی یک حساب خاص را با فراخوانی navigator.credentials.get() با ویژگی loginHint با یکی از مقادیر login_hints که از نقطه پایانی لیست حساب ها واکشی شده است نشان دهند، همانطور که در نمونه کد زیر نشان داده شده است: 

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

وقتی هیچ حسابی با loginHint مطابقت نداشته باشد، کادر گفتگوی FedCM یک اعلان ورود را نشان می‌دهد که به کاربر اجازه می‌دهد به یک حساب IdP مطابق با راهنمایی درخواست شده توسط RP وارد شود. هنگامی که کاربر روی درخواست ضربه می زند، یک پنجره بازشو با URL ورود به سیستم مشخص شده در فایل پیکربندی باز می شود. سپس پیوند با اشاره ورود و پارامترهای پرس و جو اشاره دامنه اضافه می شود.

Domain Hint API

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

RP ها می توانند به طور انتخابی فقط حساب های منطبق را با فراخوانی navigator.credentials.get() با ویژگی domainHint با یکی از مقادیر domain_hints که از نقطه پایانی لیست حساب ها واکشی شده است نشان دهند، همانطور که در نمونه کد زیر نشان داده شده است: 

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.example"
    }]
  }
});

وقتی هیچ حسابی با domainHint مطابقت نداشته باشد، کادر گفتگوی FedCM یک اعلان ورود را نشان می‌دهد که به کاربر اجازه می‌دهد به یک حساب IdP مطابق با راهنمایی درخواست شده توسط RP وارد شود. هنگامی که کاربر روی درخواست ضربه می زند، یک پنجره بازشو با URL ورود به سیستم مشخص شده در فایل پیکربندی باز می شود. سپس پیوند با اشاره ورود و پارامترهای پرس و جو اشاره دامنه اضافه می شود.

یک مثال درخواست ورود به سیستم زمانی که هیچ حسابی با domainHint مطابقت نداشته باشد.
یک مثال درخواست ورود به سیستم زمانی که هیچ حسابی با domainHint مطابقت نداشته باشد.

نمایش یک پیام خطا

گاهی اوقات، IdP ممکن است به دلایل قانونی نتواند توکن صادر کند، مانند زمانی که مشتری غیرمجاز است، سرور موقتاً در دسترس نیست. اگر IdP یک پاسخ "خطا" را برگرداند، RP می تواند آن را دریافت کند، همچنین کروم با نشان دادن رابط کاربری مرورگر با اطلاعات خطای ارائه شده توسط IdP، کاربر را مطلع می کند.

الف
یک گفتگوی FedCM که پیام خطا را پس از شکست تلاش کاربر برای ورود به سیستم نشان می دهد. رشته با نوع خطا مرتبط است. 
try {
  const cred = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: "https://idp.example/manifest.json",
          clientId: "1234",
        },
      ],
    }
  });
} catch (e) {
  const code = e.code;
  const url = e.url;
}

احراز هویت مجدد خودکار کاربران پس از احراز هویت اولیه

احراز هویت مجدد خودکار FedCM (به طور خلاصه «تأیید مجدد خودکار») می تواند به کاربران اجازه دهد که پس از احراز هویت اولیه با استفاده از FedCM دوباره به طور خودکار احراز هویت شوند. "تأیید هویت اولیه" در اینجا به این معنی است که کاربر با ضربه زدن روی دکمه "ادامه به عنوان..." در گفتگوی ورود به سیستم FedCM برای اولین بار در همان نمونه مرورگر، یک حساب ایجاد می کند یا به وب سایت RP وارد می شود.

در حالی که تجربه کاربری صریح قبل از ایجاد حساب فدرال توسط کاربر برای جلوگیری از ردیابی (که یکی از اهداف اصلی FedCM است) منطقی است، پس از اینکه کاربر یک بار آن را گذرانده است، غیرضروری دست و پا گیر است: پس از اعطای مجوز به کاربر برای اجازه دادن به آن. ارتباط بین RP و IdP، هیچ مزیتی برای حفظ حریم خصوصی یا امنیتی برای اعمال تأیید صریح کاربر دیگر برای چیزی که قبلاً تأیید کرده است وجود ندارد.

با احراز هویت مجدد خودکار، مرورگر رفتار خود را بسته به گزینه ای که هنگام فراخوانی navigator.credentials.get() برای mediation تعیین می کنید تغییر می دهد. 

const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/fedcm.json",
      clientId: "1234",
    }],
  },
  mediation: 'optional', // this is the default
});

// `isAutoSelected` is `true` if auto-reauthn was performed.
const isAutoSelected = cred.isAutoSelected;

mediation یک ویژگی در Credential Management API است، مانند PasswordCredential و FederatedCredential رفتار می کند و تا حدی توسط PublicKeyCredential نیز پشتیبانی می شود. این ویژگی چهار مقدار زیر را می پذیرد:

  • 'optional' (پیش‌فرض): در صورت امکان احراز هویت مجدد خودکار، در غیر این صورت نیاز به میانجیگری دارد. توصیه می کنیم این گزینه را در صفحه ورود به سیستم انتخاب کنید.
  • 'required' : همیشه برای ادامه به واسطه نیاز دارد، برای مثال، روی دکمه "ادامه" در رابط کاربری کلیک کنید. اگر از کاربران شما انتظار می رود هر بار که نیاز به احراز هویت دارند، به صراحت اجازه دهند این گزینه را انتخاب کنید.
  • 'silent' : در صورت امکان، احراز هویت مجدد خودکار، در غیر این صورت بدون نیاز به میانجیگری، بی‌صدا شکست می‌خورد. توصیه می‌کنیم این گزینه را در صفحاتی غیر از صفحه ورود به سیستم اختصاصی، اما در جایی که می‌خواهید کاربران را وارد سیستم کنید، انتخاب کنید - برای مثال، صفحه موردی در وب‌سایت حمل و نقل یا صفحه مقاله در یک وب‌سایت خبری.
  • 'conditional' : برای WebAuthn استفاده می شود و در حال حاضر برای FedCM در دسترس نیست.

با این تماس، احراز هویت مجدد خودکار در شرایط زیر انجام می شود:

هنگامی که این شرایط برآورده می شود، به محض فراخوانی FedCM navigator.credentials.get() تلاش برای احراز هویت مجدد خودکار کاربر شروع می شود.

هنگامی که mediation: optional ، احراز هویت مجدد خودکار ممکن است به دلایلی که فقط مرورگر می داند در دسترس نباشد . RP می تواند با بررسی ویژگی isAutoSelected بررسی کند که آیا احراز هویت مجدد خودکار انجام می شود یا خیر.

این برای ارزیابی عملکرد API و بهبود UX بر این اساس مفید است. همچنین، هنگامی که در دسترس نیست، ممکن است از کاربر خواسته شود با میانجیگری صریح کاربر وارد سیستم شود، که یک جریان با mediation: required .

کاربر احراز هویت مجدد خودکار از طریق FedCM.

اجرای میانجیگری با preventSilentAccess()

احراز هویت مجدد خودکار کاربران بلافاصله پس از خروج از سیستم، تجربه کاربری بسیار خوبی را ایجاد نمی کند. به همین دلیل است که FedCM برای جلوگیری از این رفتار، یک دوره 10 دقیقه‌ای سکوت پس از احراز هویت مجدد خودکار دارد. این بدان معناست که احراز هویت مجدد خودکار حداکثر هر 10 دقیقه یک بار اتفاق می‌افتد مگر اینکه کاربر در عرض 10 دقیقه دوباره وارد سیستم شود. RP باید navigator.credentials.preventSilentAccess() را فراخوانی کند تا صراحتاً از مرورگر درخواست کند تا زمانی که کاربر بطور صریح از RP خارج می شود، مثلاً با کلیک کردن روی دکمه خروج، احراز هویت مجدد خودکار را غیرفعال کند. 

function signout() {
  navigator.credentials.preventSilentAccess();
  location.href = '/signout';
}

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

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

  • در کروم دسکتاپ، به chrome://password-manager/settings > ورود خودکار به سیستم بروید.
  • در Android Chrome، تنظیمات > مدیریت رمز عبور > روی چرخ دنده در گوشه بالا سمت راست > ورود خودکار ضربه بزنید.

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

IdP را از RP جدا کنید

اگر کاربر قبلاً با استفاده از IdP از طریق FedCM وارد RP شده باشد، این رابطه توسط مرورگر به صورت محلی به عنوان فهرست حساب‌های متصل حفظ می‌شود. RP ممکن است با فراخوانی تابع IdentityCredential.disconnect() قطع ارتباط را آغاز کند. این تابع را می توان از یک فریم RP سطح بالا فراخوانی کرد. RP باید یک configURL ، clientId که در زیر IdP استفاده می‌کند، و یک accountHint برای IdP که قطع شود، ارسال کند. اشاره حساب می تواند یک رشته دلخواه باشد تا زمانی که نقطه پایانی قطع ارتباط بتواند حساب را شناسایی کند ، به عنوان مثال یک آدرس ایمیل یا شناسه کاربری که لزوماً با شناسه حساب که نقطه پایانی لیست حساب ارائه داده است مطابقت ندارد: 

// Disconnect an IdP account "account456" from the RP "https://idp.com/". This is invoked on the RP domain.
IdentityCredential.disconnect({
  configURL: "https://idp.com/config.json",
  clientId: "rp123",
  accountHint: "account456"
});

IdentityCredential.disconnect() Promise ای را برمی گرداند. این قول ممکن است به دلایل زیر استثناء کند:

  • کاربر با استفاده از IDP از طریق FEDCM وارد RP نشده است.
  • API از درون یک IFRAME بدون سیاست مجوزهای FEDCM فراخوانی می شود.
  • پیکربندی نامعتبر است یا نقطه پایانی قطع ارتباط را از دست نمی دهد.
  • بررسی خط مشی امنیت محتوا (CSP) انجام نمی شود.
  • یک درخواست قطع ارتباط در انتظار است.
  • کاربر FEDCM را در تنظیمات مرورگر غیرفعال کرده است.

هنگامی که نقطه پایانی IDP پاسخی را برمی گرداند ، RP و IDP بر روی مرورگر قطع می شوند و قول برطرف می شود. شناسه حسابهای قطع شده در پاسخ از نقطه پایانی قطع ارتباط مشخص شده است.

با FEDCM از درون یک Iframe متقاطع تماس بگیرید

اگر قاب والدین اجازه آن را بدهد ، می توان با استفاده از یک خط مشی مجوزهای identity-credentials-get ، از طریق یک Iframe متقاطع استفاده کرد. برای انجام این کار ، ویژگی allow="identity-credentials-get" به برچسب Iframe به شرح زیر اضافه کنید: 

<iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>

در یک مثال می توانید آن را در عمل مشاهده کنید.

به صورت اختیاری ، اگر قاب والدین بخواهد منشأ را برای تماس با FEDCM محدود کند ، یک هدر Permissions-Policy با لیستی از ریشه های مجاز ارسال کنید. 

Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")

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