احزاب متکی (RP) برای فعال کردن FedCM در سایت خود باید مراحل زیر را انجام دهند:
- مطمئن شوید که نقاط پایانی FedCM در سایت RP مجاز است.
- از FedCM JavaScript API برای شروع احراز هویت کاربر استفاده کنید.
- ابردادههای آنها (مانند آدرسهای اینترنتی خطمشی رازداری و شرایط خدمات) را در اختیار IdP قرار دهید.
- [اختیاری] با انتخاب حالت UX ، ارائه نکات ورود به سیستم یا دامنه ، ارسال پارامترهای سفارشی ، درخواست اطلاعات کاربر خاص ، ارائه یک پیام خطای سفارشی ، یا انتخاب نحوه احراز هویت مجدد کاربران، تجربه کاربر را سفارشی کنید.
هنگامی که پیکربندی و نقاط پایانی IdP در دسترس هستند، RP ها می توانند با فراخوانی navigator.credentials.get()
درخواست کنند تا کاربران بتوانند با IdP وارد RP شوند.
قبل از تماس با API، باید تأیید کنید که FedCM در مرورگر کاربر در دسترس است . برای بررسی اینکه آیا FedCM در دسترس است، این کد را در اطراف پیاده سازی FedCM خود بپیچید:
if ('IdentityCredential' in window) {
// If the feature is available, take action
} else {
// FedCM is not supported, use a different identity solution
}
برای اینکه کاربران بتوانند با استفاده از FedCM وارد IdP در یک RP شوند، RP میتواند navigator.credentials.get()
را فراخوانی کند، برای مثال:
const credential = await navigator.credentials.get({
identity: {
context: 'signin',
providers: [{
configURL: 'https://accounts.idp.example/config.json',
clientId: '********',
mode: 'active',
params: {
nonce: '******'
}
}]
}
});
const { token } = credential;
ویژگی زمینه
با ویژگی context
اختیاری، RP میتواند رشته را در رابط کاربری گفتگوی FedCM تغییر دهد (به عنوان مثال، "ورود به rp.example..."، "استفاده از idp.example...") تا برای مثال، زمینههای احراز هویت از پیش تعریف شده را در خود جای دهد. ویژگی context
می تواند مقادیر زیر را داشته باشد:
-
signin
(پیش فرض) -
signup
-
use

به عنوان مثال، تنظیم context
برای use
پیام زیر را به همراه خواهد داشت:

مرورگر بسته به وجود approved_clients
در پاسخ از نقطه پایانی فهرست حسابها، موارد استفاده از ثبت نام و ورود به سیستم را متفاوت مدیریت میکند. اگر کاربر قبلاً در RP ثبت نام کرده باشد، مرورگر متن افشای «برای ادامه با ...» را نمایش نمی دهد.
ویژگی providers
آرایه ای از اشیاء IdentityProvider را می گیرد که دارای ویژگی های زیر هستند:
اموال را ارائه می دهد
ویژگی providers
آرایه ای از اشیاء IdentityProvider
را می گیرد که دارای ویژگی های زیر هستند:
اموال | توضیحات |
---|---|
configURL (الزامی) | مسیر کامل فایل پیکربندی IdP. |
clientId (الزامی) | شناسه مشتری RP، صادر شده توسط IdP. |
loginHint (اختیاری) | با مشخص کردن یکی از مقادیر login_hints ارائه شده توسط نقاط پایانی حساب ها ، گفتگوی FedCM به صورت انتخابی حساب مشخص شده را نشان می دهد. |
domainHint (اختیاری) | با مشخص کردن یکی از مقادیر domain_hints ارائه شده توسط نقاط پایانی حساب ها ، کادر گفتگوی FedCM به صورت انتخابی حساب مشخص شده را نشان می دهد. |
mode (اختیاری) | رشته ای که حالت رابط کاربری FedCM را مشخص می کند. می تواند یکی از این مقادیر باشد:
توجه: پارامتر mode از Chrome 132 پشتیبانی میشود. |
fields (اختیاری) | آرایهای از رشتهها که اطلاعات کاربر ("نام"، "ایمیل"، "تصویر") را مشخص میکند که RP به IdP نیاز دارد تا با آنها به اشتراک بگذارد. توجه: Field API توسط Chrome 132 و جدیدتر پشتیبانی میشود. |
params (اختیاری) | شی سفارشی که امکان تعیین پارامترهای کلید-مقدار اضافی را فراهم می کند:
توجه: params از Chrome 132 پشتیبانی می شود. |
حالت فعال
FedCM از تنظیمات مختلف حالت UX پشتیبانی می کند. حالت غیرفعال حالت پیش فرض است و توسعه دهندگان نیازی به پیکربندی آن ندارند.
برای استفاده از FedCM در حالت فعال:
- در دسترس بودن ویژگی در مرورگر کاربر را بررسی کنید.
- API را با یک حرکت گذرا کاربر، مانند کلیک کردن روی دکمه، فراخوانی کنید.
- پارامتر
mode
را به فراخوانی API ارسال کنید:
let supportsFedCmMode = false;
try {
navigator.credentials.get({
identity: Object.defineProperty(
// Check if this Chrome version supports the Mode API.
{}, 'mode', {
get: function () { supportsFedCmMode = true; }
}
)
});
} catch(e) {}
if (supportsFedCmMode) {
// The button mode is supported. Call the API with mode property:
return await navigator.credentials.get({
identity: {
providers: [{
configURL: 'https://idp.example/config.json',
clientId: '123',
}],
// The 'mode' value defines the UX mode of FedCM.
// - 'active': Must be initiated by user interaction (e.g., clicking a button).
// - 'passive': Can be initiated without direct user interaction.
mode: 'active'
}
});
}
نماد سفارشی در حالت فعال
حالت فعال به IdP ها اجازه می دهد نماد لوگوی رسمی RP را مستقیماً در پاسخ نقطه پایانی فراداده مشتری قرار دهند. RP باید داده های نام تجاری خود را از قبل ارائه دهد.
با FedCM از داخل یک iframe متقاطع تماس بگیرید
FedCM را میتوان از داخل یک iframe متقاطع با استفاده از یک خطمشی مجوزهای identity-credentials-get
فراخوانی کرد، در صورتی که قاب والد آن را اجازه دهد. برای انجام این کار، ویژگی 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")
میتوانید درباره نحوه عملکرد خطمشی مجوزها در کنترل ویژگیهای مرورگر با خطمشی مجوزها اطلاعات بیشتری کسب کنید.
Login Hint API
با استفاده از راهنمای ورود، RP می تواند توصیه کند که کاربر باید با کدام حساب وارد شود. این می تواند برای احراز هویت مجدد کاربرانی که مطمئن نیستند قبلاً از کدام حساب استفاده کرده اند مفید باشد.
RP ها می توانند به طور انتخابی یک حساب خاص را با فراخوانی navigator.credentials.get()
با ویژگی loginHint
با یکی از مقادیر login_hints
که از نقطه پایانی لیست حساب ها واکشی شده است نشان دهند، همانطور که در نمونه کد زیر نشان داده شده است:
return await navigator.credentials.get({
identity: {
providers: [{
configURL: 'https://idp.example/manifest.json',
clientId: '123',
// Accounts endpoint can specify a 'login_hints' array for an account.
// When RP specifies a 'exampleHint' value, only those accounts will be
// shown to the user whose 'login_hints' array contains the 'exampleHint'
// value
loginHint : 'exampleHint'
}]
}
});
وقتی هیچ حسابی با loginHint
مطابقت نداشته باشد، کادر گفتگوی FedCM یک اعلان ورود را نشان میدهد که به کاربر اجازه میدهد به یک حساب IdP مطابق با راهنمایی درخواست شده توسط RP وارد شود. هنگامی که کاربر روی درخواست ضربه می زند، یک پنجره بازشو با URL ورود به سیستم مشخص شده در فایل پیکربندی باز می شود. سپس پیوند با اشاره ورود و پارامترهای پرس و جو اشاره دامنه اضافه می شود.
Domain Hint API
RP ها می توانند به طور انتخابی فقط حساب های مرتبط با یک دامنه خاص را نشان دهند. این می تواند برای RP هایی که به یک دامنه شرکتی محدود شده اند مفید باشد.
برای نمایش تنها حسابهای دامنه خاص، RP باید navigator.credentials.get()
با ویژگی domainHint
با یکی از مقادیر domain_hints
که از نقطه پایانی فهرست حسابها واکشی شده است، فراخوانی کند، همانطور که در نمونه کد زیر نشان داده شده است:
return await navigator.credentials.get({
identity: {
providers: [{
configURL: 'https://idp.example/manifest.json',
clientId: 'abc',
// Accounts endpoint can specify a 'domain_hints' array for an account.
// When RP specifies a '@domain.example' value, only those accounts will be
// shown to the user whose 'domain_hints' array contains the
// '@domain.example' value
domainHint : '@domain.example'
}]
}
});
وقتی هیچ حسابی با domainHint
مطابقت نداشته باشد، کادر گفتگوی FedCM یک اعلان ورود را نشان میدهد که به کاربر اجازه میدهد به یک حساب IdP مطابق با راهنمایی درخواست شده توسط RP وارد شود. هنگامی که کاربر روی درخواست ضربه می زند، یک پنجره بازشو با URL ورود به سیستم مشخص شده در فایل پیکربندی باز می شود. سپس پیوند با اشاره ورود و پارامترهای پرس و جو اشاره دامنه اضافه می شود.

domainHint
مطابقت نداشته باشد.پارامترهای سفارشی
ویژگی پارامترهای سفارشی به RP اجازه می دهد تا پارامترهای کلیدی-مقدار اضافی را به نقطه پایانی ادعای ID ارائه دهد. با Parameters API، RP ها می توانند پارامترهای اضافی را به IdP ارسال کنند تا مجوزهایی را برای منابعی فراتر از ورود به سیستم اولیه درخواست کنند. ارسال پارامترهای اضافی می تواند در این سناریو مفید باشد:
- RP باید مجوزهای اضافی را به صورت پویا درخواست کند که IdP دارد، مانند آدرس صورتحساب یا دسترسی به تقویم. کاربر میتواند این مجوزها را از طریق یک جریان UX کنترلشده توسط IdP که با استفاده از ویژگی Continue on راهاندازی میشود، مجوز دهد و سپس IdP این اطلاعات را به اشتراک بگذارد.
برای استفاده از API، RP پارامترهایی را به ویژگی params
به عنوان یک شی در فراخوانی navigator.credentials.get()
اضافه می کند:
let {token} = await navigator.credentials.get({
identity: {
providers: [{
clientId: '1234',
configURL: 'https://idp.example/fedcm.json',
// Key/value pairs that need to be passed from the
// RP to the IdP but that don't really play any role with
// the browser.
params: {
IDP_SPECIFIC_PARAM: '1',
foo: 'BAR'
}
},
}
});
مرورگر به طور خودکار این را به یک درخواست POST به IdP با پارامترهایی به عنوان یک شیء سریالی JSON کدگذاری شده با URL تبدیل می کند:
// The assertion endpoint is drawn from the config file
POST /fedcm_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
// params are translated into urlencoded version of `{"IDP_SPECIFIC_PARAM":"1","foo":"bar"}`
account_id=123&client_id=client1234¶ms=%22%7B%5C%22IDP_SPECIFIC_PARAM%5C%22%3A1%2C%5C%22foo%5C%22%3A%5C%22BAR%5C%22%7D%22.
اگر RP به مجوزهای اضافی نیاز داشته باشد، IdP می تواند پیوند تغییر مسیر را ارائه دهد. به عنوان مثال، در node.js:
if (rpRequestsPermissions) {
// Response with a URL if the RP requests additional permissions
return res.json({
continue_on: '/example-redirect',
});
}
فیلدها
RP می تواند اطلاعات کاربری (هر ترکیبی از نام، آدرس ایمیل و عکس نمایه) را که به IdP نیاز دارند تا با آنها به اشتراک بگذارد، مشخص کند. اطلاعات درخواستی در رابط کاربری افشای گفتگوی FedCM گنجانده خواهد شد. کاربر پیامی را می بیند که به او اطلاع می دهد در صورتی که کاربر بخواهد وارد سیستم شود، idp.example
اطلاعات درخواستی را با rp.example
به اشتراک می گذارد.

برای استفاده از ویژگی Fields، RP باید یک آرایه fields
را در فراخوانی navigator.credentials.get()
اضافه کند. فیلدها می توانند شامل هر گونه تغییر name
، email
و picture
باشند. این را می توان گسترش داد تا در آینده مقادیر بیشتری را شامل شود. یک درخواست با fields
به شکل زیر است:
let { token } = await navigator.credentials.get({
identity: {
providers: [{
// RP requests the IdP to share only user email and profile picture
fields: [ 'email', 'picture'],
clientId: '1234',
configURL: 'https://idp.example/fedcm.json',
},
}
});
مرورگر به طور خودکار آن را به یک درخواست HTTP به نقطه پایانی ادعای ID که شامل پارامتر fields
مشخص شده با RP است، با فیلدهایی که مرورگر در پارامتر disclosure_shown_for
برای کاربر فاش کرده است، ترجمه می کند. برای سازگاری با عقب، مرورگر همچنین disclosure_text_shown=true
ارسال می کند اگر متن افشا نشان داده شده باشد و فیلدهای درخواستی شامل هر سه فیلد باشد: 'name'
، 'email'
و 'picture'
.
POST /id_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
// The RP only requested to share email and picture. The browser will send `disclosure_text_shown=false`, as the 'name' field value is missing
account_id=123&client_id=client1234&disclosure_text_shown=false&fields=email,picture&disclosure_shown_for=email,picture
اگر fields
یک آرایه خالی باشد، عامل کاربر رابط کاربری افشا را رد می کند.

این مورد حتی اگر پاسخ از نقطه پایانی حسابها حاوی شناسه مشتری نباشد که با RP در approved_clients
مطابقت داشته باشد.
در این مورد، disclosure_text_shown
ارسال شده به نقطه پایانی اعلام شناسه در بدنه HTTP نادرست است:
POST /id_assertion_endpoint HTTP/1.1
Host: 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=234234&disclosure_text_shown=false
نمایش یک پیام خطا
گاهی اوقات، IdP ممکن است به دلایل قانونی نتواند توکن صادر کند، مانند زمانی که مشتری غیرمجاز است یا سرور به طور موقت در دسترس نیست. اگر IdP پاسخ «خطا» را برگرداند، RP میتواند آن را پیدا کند و Chrome میتواند با نشان دادن رابط کاربری مرورگر با اطلاعات خطای ارائهشده توسط 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 در مرورگر قطع میشوند و وعده حل میشود. شناسه حساب های قطع شده در پاسخ از نقطه پایانی قطع شده مشخص شده است.