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

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