راهنمای توسعه‌دهنده 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 مسدود کنید

می‌توانید قبل از اجرای واقعی 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 انتظار دارد که شامل ویژگی های زیر است:

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

در اینجا یک نمونه بدن پاسخ از 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 از چندین حساب پشتیبانی کند، این نقطه پایانی همه حساب‌های وارد شده را برمی‌گرداند.

مرورگر یک درخواست 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 با آرایه ای از اطلاعات حساب با ویژگی های زیر است:

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

{
  "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. با فراداده مشتری پاسخ دهید.

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

مرورگر انتظار پاسخ 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 به این نقطه پایانی ارسال می کند. اطلاعات زیر:

هدر 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": "***********"
}

توکن برگشتی توسط مرورگر به 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 به این نقطه پایانی قطع با اطلاعات زیر ارسال می کند:

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 پیامی را نشان می دهد که ورود به سیستم را پیشنهاد می کند.

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

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

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

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

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 را می گیرد که دارای ویژگی های زیر هستند:

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

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

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

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

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

انتظار می رود 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 ورود به سیستم مشخص شده در فایل پیکربندی باز می شود. سپس پیوند با اشاره ورود و پارامترهای پرس و جو اشاره دامنه اضافه می شود.

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

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

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 برای استفاده در دسترس است. به عنوان مثال، کاربر FedCM را به صورت سراسری یا برای RP در تنظیمات غیرفعال نکرده است.
• کاربر فقط از یک حساب با FedCM API برای ورود به وب سایت در این مرورگر استفاده کرده است.
• کاربر با آن حساب وارد IdP شده است.
• احراز هویت مجدد خودکار در 10 دقیقه گذشته انجام نشد.
• RP بعد از ورود به سیستم قبلی، navigator.credentials.preventSilentAccess() را فراخوانی نکرده است.

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

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

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

اجرای میانجیگری با 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 فراخوانی می‌شود.
• configURL نامعتبر است یا نقطه پایانی قطع ارتباط را ندارد.
• بررسی خط مشی امنیت محتوا (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")

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

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

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

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

محیط توسعه FEDCM

برای استفاده از FEDCM ، به یک زمینه امن (HTTPS یا LocalHost) در IDP و RP در Chrome نیاز دارید.

کد اشکال زدایی در Chrome در Android

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

با پیروی از دستورالعمل های موجود در دستگاه های Android از راه دور اشکال زدایی ، می توانید از DevTools on Desktop برای اشکال زدایی Chrome در Android استفاده کنید.

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

شما می توانید قبل از اجرای آن ، چگونه FEDCM را بدون کوکی های شخص ثالث روی Chrome کار می کند.

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

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

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

از آنجا ، FEDCM API های JavaScript را که RPS می تواند برای ورود به سیستم با 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 توسط RPS مشخص شود. تعداد رشته های 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 را دارد که شامل خواص زیر است:

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

در اینجا یک مثال پاسخ به عنوان مثال از 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 از چندین حساب پشتیبانی کند ، این نقطه پایانی تمام امضا شده در حساب ها را برمی گرداند.

مرورگر درخواست 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. تأیید کنید که این درخواست حاوی یک Sec-Fetch-Dest: webidentity .
2. کوکی های جلسه را با شناسه حساب های ثبت شده در حال حاضر مطابقت دهید.
3. با لیست حساب ها پاسخ دهید.

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

مثال پاسخ بدن:

{
  "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 و شرایط خدمات را برمی گرداند. RPS باید از قبل پیوندهایی به خط مشی رازداری و شرایط خدمات خود به IDP ارائه دهد. این پیوندها وقتی کاربر هنوز در RP با IDP ثبت نام نکرده است ، در گفتگوی ورود به سیستم نمایش داده می شود.

مرورگر با استفاده از client_id navigator.credentials.get بدون کوکی 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. با ابرداده مشتری پاسخ دهید.

خصوصیات نقطه پایانی ابرداده مشتری شامل موارد زیر است:

مرورگر انتظار پاسخ 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 به این نقطه پایانی ارسال می کند. اطلاعات زیر:

مثال هدر 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. تأیید کنید که این درخواست حاوی یک Sec-Fetch-Dest: webidentity .
3. هدر Origin در مقابل مبدا RP تعیین کنید که توسط client_id تعیین شده است. اگر آنها مطابقت نداشته باشند ، رد کنید.
4. account_id در برابر شناسه حساب از قبل امضا شده مطابقت دهید. اگر آنها مطابقت نداشته باشند ، رد کنید.
5. با یک نشانه پاسخ دهید. اگر درخواست رد شد ، با پاسخ خطا پاسخ دهید.

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

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

{
  "token": "***********"
}

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

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

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

• code : IDP می تواند یکی از خطاهای شناخته شده را از لیست خطای مشخص شده OAUTH 2.0 انتخاب کند ( invalid_request ، unauthorized_client ، access_denied ، server_error و temporarily_unavailable ) یا از هر رشته دلخواه استفاده کنید. اگر دومی ، Chrome با یک پیام خطای عمومی UI خطا را ارائه می دهد و کد را به RP منتقل می کند.
• url : این یک صفحه وب قابل خواندن با انسانی را با اطلاعات مربوط به خطا برای ارائه اطلاعات بیشتر در مورد خطا برای کاربران مشخص می کند. این زمینه برای کاربران مفید است زیرا مرورگرها نمی توانند پیام های خطای غنی را در یک UI بومی ارائه دهند. به عنوان مثال ، پیوندها برای مراحل بعدی ، اطلاعات تماس با خدمات مشتری و غیره. اگر کاربر بخواهد در مورد جزئیات خطا و نحوه رفع آن اطلاعات بیشتری کسب کند ، می تواند برای اطلاعات بیشتر به صفحه ارائه شده از UI مرورگر مراجعه کند. URL باید از همان سایت با configURL IDP باشد.

// 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 با اطلاعات زیر ارسال می کند:

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. تأیید کنید که این درخواست حاوی یک Sec-Fetch-Dest: webidentity .
3. هدر Origin در مقابل مبدا RP تعیین کنید که توسط client_id تعیین شده است. اگر آنها مطابقت نداشته باشند ، رد کنید.
4. مطابق با account_hint حساب های ثبت شده در حال حاضر.
5. حساب کاربری را از RP جدا کنید.
6. با اطلاعات حساب کاربری شناسایی شده با فرمت JSON به مرورگر پاسخ دهید.

یک پاسخ به عنوان مثال JSON Payload به این شکل است:

{
  "account_id": "account456"
}

در عوض ، اگر IDP آرزو می کند که مرورگر تمام حساب های مرتبط با RP را جدا کند ، رشته ای را منتقل کنید که با هیچ شناسه حساب مطابقت ندارد ، به عنوان مثال "*" .

URL ورود به سیستم

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

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

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

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

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

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

API وضعیت ورود به سیستم مکانیسمی است که یک وب سایت ، به ویژه یک IDP ، وضعیت ورود کاربر را در IDP به مرورگر اطلاع می دهد. با استفاده از این API ، مرورگر می تواند درخواست های غیر ضروری را به IDP کاهش داده و حملات زمان بندی بالقوه را کاهش دهد.

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

برای اینکه سیگنال شود که کاربر وارد سیستم شده است ، یک 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 Calling FedCM درخواست هایی را به نقطه پایانی حساب های IDP می دهد و حساب های موجود را در گفتگوی FEDCM به کاربر نشان می دهد.

برای نشان دادن اینکه کاربر از تمام حسابهای خود امضا شده است ، 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 سیگنال با استفاده از API وضعیت ورود به سیستم تنظیم شده است. Unknown برای انتقال بهتر معرفی شد ، زیرا ممکن است کاربر هنگام حمل این API وارد IDP شود. IDP ممکن است فرصتی برای سیگنال این موضوع به مرورگر نداشته باشد تا زمانی که برای اولین بار FEDCM فراخوانی شود. در این حالت ، 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 را که دارای خواص زیر هستند ، می گیرد:

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

وضعیت ثبت نام بر اساس این که آیا شرایط زیر برآورده شده است یا خیر ، تعیین می شود:

• در صورت approved_clients شامل clientId RP است.
• اگر مرورگر به یاد داشته باشد که کاربر قبلاً در RP ثبت نام کرده است.

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

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

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

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

ورود به سیستم API

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

RPS می تواند با فراخوانی 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 وارد شود، اما بعداً با یک پیام خطا (یا در مواردی که ورود کار نمی کند خاموش شود) به دلیل استفاده نکردن از نوع درست حساب، به او نمایش داده می شود.

RPS می تواند با استفاده از 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 ورود به سیستم مشخص شده در فایل پیکربندی باز می شود. سپس پیوند با اشاره ورود و پارامترهای پرس و جو اشاره دامنه اضافه می شود.

پیام خطا را نشان دهید

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

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;
}

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

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

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

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

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 یک خاصیت در API مدیریت اعتبار است ، به همان روشی که برای گذرواژنی و فدرال فدرال انجام می شود رفتار می کند و بخشی از آن توسط PublicKeyCredential نیز پشتیبانی می شود. این ملک چهار مقدار زیر را می پذیرد:

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

با این تماس ، Auto-reeauthn تحت شرایط زیر اتفاق می افتد:

• FedCM برای استفاده در دسترس است. به عنوان مثال ، کاربر FEDCM را در سطح جهان یا RP در تنظیمات غیرفعال نکرده است.
• کاربر فقط از یک حساب با FEDCM API برای ورود به وب سایت در این مرورگر استفاده کرد.
• کاربر با آن حساب وارد IdP شده است.
• احراز هویت مجدد خودکار در 10 دقیقه گذشته انجام نشد.
• RP پس از ورود به سیستم قبلی ، navigator.credentials.preventSilentAccess() را فراخوانی نکرده است.

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

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

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

واسطه گری را با preventSilentAccess() اجرا کنید

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

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

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

کاربران می توانند از منوی تنظیمات از طریق مجدد خودکار خودداری کنند:

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

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

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 را در تنظیمات مرورگر غیرفعال کرده است.

When the IdP's disconnect endpoint returns a response , the RP and the IdP are disconnected on the browser and the promise is resolved. The ID of the disconnected accounts are specified in the response from the disconnect endpoint .

Call FedCM from within a cross-origin iframe

FedCM can be invoked from within a cross-origin iframe using an identity-credentials-get permissions policy, if the parent frame allows it. To do so, append the allow="identity-credentials-get" attribute to the iframe tag as follows:

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

You can see it in action in an example .

Optionally, if the parent frame wants to restrict the origins to call FedCM, send a Permissions-Policy header with a list of allowed origins.

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

You can learn more about how the Permissions Policy works at Controlling browser features with Permissions Policy .