این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

به‌روزرسانی‌های FedCM: آزمایش‌های اولیه برای بسته API Continuation و اعطای خودکار API دسترسی به حافظه

Eiji Kitamura

از Chrome 126، توسعه‌دهندگان می‌توانند یک نسخه آزمایشی اصلی را برای مجموعه‌ای از ویژگی‌های مدیریت اعتبار فدرال API (FedCM) دسک‌تاپ که برخی از موارد استفاده از مجوز را فعال می‌کنند، شروع کنند. این بسته شامل Continuation API و Parameters API است که تجربه‌ای مشابه جریان مجوز OAuth را که شامل گفتگوی مجوز ارائه‌شده توسط ارائه‌دهنده هویت (IdP) است، فعال می‌کند. این بسته همچنین شامل تغییرات دیگری مانند Fields API، چندین configURL و برچسب‌های حساب سفارشی است. از Chrome 126، ما همچنین یک نسخه آزمایشی اصلی را برای Storage Access API (SAA) معرفی می‌کنیم که اگر کاربر با استفاده از FedCM در گذشته با موفقیت وارد سیستم شده باشد، درخواست‌های SAA را به‌طور خودکار اعطا می‌کند.

آزمایش اولیه: بسته نرم افزاری API ادامه FedCM

بسته نرم افزاری API Continuation FedCM از چندین افزونه FedCM تشکیل شده است:

Continuation API
API پارامترها
Fields API
چندین configURL
برچسب های حساب سفارشی

Continuation API

کاربر در حال ورود به RP است و سپس از طریق حالت دکمه مجوز می دهد.

می‌توانید نسخه آزمایشی API را در Glitch بررسی کنید.

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

به طور معمول، نقطه پایانی ادعای ID یک رمز مورد نیاز برای احراز هویت را برمی‌گرداند.

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

با این حال، با Continuation API، نقطه پایانی ادعای ID می‌تواند یک ویژگی continue_on را برگرداند که شامل یک مسیر مطلق یا یک مسیر نسبی به نقطه پایانی ادعای ID است.

{
  // In the id_assertion_endpoint, instead of returning a typical
  // "token" response, the IdP decides that it needs the user to
  // continue on a pop-up window:
  "continue_on": "/oauth/authorize?scope=..."
}

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

پس از تعامل کاربر با صفحه، به عنوان مثال اجازه بیشتر برای به اشتراک گذاشتن اطلاعات اضافی با RP، صفحه IdP می تواند IdentityProvider.resolve() را فراخوانی کند تا فراخوانی navigator.credentials.get() اصلی را حل کند و یک توکن را به عنوان آرگومان برگرداند. .

document.getElementById('allow_btn').addEventListener('click', async () => {
  let accessToken = await fetch('/generate_access_token.cgi');
  // Closes the window and resolves the promise (that is still hanging
  // in the relying party's renderer) with the value that is passed.
  IdentityProvider.resolve(accessToken);
});

سپس مرورگر به خودی خود پنجره بازشو را می بندد و توکن را به تماس گیرنده API برمی گرداند.

اگر کاربر درخواست را رد کرد، می توانید با فراخوانی IdentityProvider.close() پنجره را ببندید.

IdentityProvider.close();

اگر به دلایلی کاربر حساب خود را در پنجره بازشو تغییر داده باشد (مثلاً IdP یک عملکرد "تغییر کاربر" یا در موارد تفویض اختیار ارائه می دهد)، فراخوانی حل یک آرگومان دوم اختیاری را می گیرد که چیزی شبیه به:

IdentityProvider.resolve(token, {accountId: '1234');

API پارامترها

Parameters API به RP اجازه می دهد تا پارامترهای اضافی را به نقطه پایانی ادعای ID ارائه دهد. با Parameters API، RP ها می توانند پارامترهای اضافی را به IdP ارسال کنند تا مجوزهایی را برای منابعی فراتر از ورود به سیستم اولیه درخواست کنند. کاربر این مجوزها را از طریق یک جریان UX کنترل شده با IdP که از طریق Continuation API راه اندازی می شود، مجاز می کند.

برای استفاده از API، پارامترهایی را به ویژگی 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',
        ETC: 'MOAR',
        scope: 'calendar.readonly photos.write',
      }
    },
  }
});

نام خصوصیات در شی params با param_ اضافه می شود. در مثال بالا، ویژگی params شامل IDP_SPECIFIC_PARAM به عنوان '1' ، foo به عنوان 'BAR' ، ETC به عنوان 'MOAR' و scope به عنوان 'calendar.readonly photos.write' . این به عنوان param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write در متن HTTP درخواست ترجمه می‌شود:

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

account_id=123&client_id=client1234&nonce=234234&disclosure_text_shown=false&param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write

مجوزها را به صورت پویا دریافت کنید

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

برای درخواست مجوز به صورت پویا با FedCM، IdP می تواند:

navigator.credentials.get() را با پارامترهای مورد نیازی که IdP می تواند بفهمد، مانند scope فراخوانی کنید.
نقطه پایانی ادعای شناسه تأیید می‌کند که کاربر قبلاً وارد سیستم شده است و با URL continue_on پاسخ می‌دهد.
مرورگر یک پنجره بازشو با صفحه مجوز IdP باز می کند که از آن درخواست مجوز اضافی می کند که با محدوده های درخواستی مطابقت دارد.
هنگامی که از طریق IdentityProvider.resolve() توسط IdP مجاز شد، پنجره بسته می شود و فراخوانی navigator.credentials.get() اصلی RP یک توکن مربوطه یا یک کد مجوز دریافت می کند تا RP بتواند آن را با یک توکن دسترسی مناسب مبادله کند.

Fields API

Fields API به RP اجازه می دهد تا ویژگی های حساب را برای درخواست از IdP اعلام کند تا مرورگر بتواند یک UI افشای مناسب را در گفتگوی FedCM ارائه دهد. این مسئولیت IdP است که فیلدهای درخواستی را در توکن برگشتی قرار دهد. این را در نظر بگیرید که یک "نمایه پایه" در OpenID Connect در مقابل "scopes" در OAuth درخواست کنید.

برای استفاده از Fields API، در فراخوانی navigator.credentials.get() پارامترهایی را به ویژگی fields به عنوان یک آرایه اضافه کنید. فیلدها می‌توانند فعلاً حاوی 'name' ، 'email' و 'picture' باشند، اما می‌توان آن‌ها را برای گنجاندن مقادیر بیشتری در آینده گسترش داد.

یک درخواست با fields به شکل زیر است:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      fields: ['name', 'email', 'picture'],
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      params: {
        scope: 'drive.readonly calendar.readonly',
      }
    },
  }
  mediation: 'optional',
});

درخواست HTTP به نقطه پایانی ادعای شناسه شامل پارامتر fields مشخص شده با RP، با پارامتر disclosure_text_shown در صورتی که کاربر بازگشتی نباشد، true ، و فیلدهایی که مرورگر در پارامتر disclosure_shown_for برای کاربر فاش کرده است:

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=true&fields=email,name,picture&disclosure_shown_for=email,name,picture

اگر RP نیاز به دسترسی به هر گونه داده اضافی از IdP، مانند دسترسی به یک تقویم دارد، باید با یک پارامتر سفارشی همانطور که در بالا ذکر شد مدیریت شود. IdP یک URL continue_on را برای درخواست مجوز برمی‌گرداند.

اگر fields یک آرایه خالی باشد، درخواست به شکل زیر خواهد بود:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      fields: [],
      clientId: '1234',
      configURL: 'https://idp.example/fedcm.json',
      params: {
        scope: 'drive.readonly calendar.readonly',
      }
    },
  }
  mediation: 'optional',
});

اگر 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

چندین configURL

چندین configURL به IdP ها اجازه می دهد تا چندین فایل پیکربندی را برای یک IdP با مشخص کردن accounts_endpoint و login_url در فایل شناخته شده مانند فایل های پیکربندی در خود جای دهند.

اگر accounts_endpoint و login_url به فایل شناخته شده اضافه شوند، provider_urls نادیده گرفته می شود تا IdP بتواند چندین فایل پیکربندی را پشتیبانی کند. اگر اینطور نیست، provider_urls همچنان به کار خود ادامه می دهد تا با نسخه قبلی سازگار باشد.

فایل معروفی که از چندین configURL پشتیبانی می کند می تواند به شکل زیر باشد:

{
  "provider_urls": [ "https://idp.example/fedcm.json" ],
  "accounts_endpoint": "https://idp.example/accounts",
  "login_url": "https://idp.example/login"
}

این به ما امکان می دهد:

سازگاری عقب و جلو را با فایل‌های شناخته شده موجود و نسخه قبلی مرورگرهایی که قبلاً در طبیعت مستقر شده‌اند، حفظ کنید.
تعداد دلخواه فایل های پیکربندی داشته باشید—تا زمانی که همه آنها به یک accounts_endpoint و login_url اشاره کنند.
هیچ فرصتی برای آنتروپی برای اضافه شدن به درخواست واکشی اعتباری ارائه شده به accounts_endpoint وجود ندارد، زیرا باید در سطح ".well-known" مشخص شود.

پشتیبانی از چندین configURL اختیاری است و پیاده سازی های موجود FedCM می توانند ثابت بمانند.

برچسب های حساب سفارشی

برچسب‌های حساب سفارشی به IdP‌های FedCM اجازه می‌دهند حساب‌ها را حاشیه‌نویسی کنند تا RPها بتوانند با تعیین برچسب در یک فایل پیکربندی، آن‌ها را فیلتر کنند. فیلتر کردن مشابهی با استفاده از Domain Hint API و Login Hint API با مشخص کردن آنها در فراخوانی navigator.credentials.get() امکان پذیر بوده است، اما برچسب های حساب سفارشی می توانند کاربران را با تعیین فایل پیکربندی فیلتر کنند، که مخصوصاً برای چندین configURL مفید است. استفاده می شوند. برچسب‌های حساب سفارشی نیز از این جهت متفاوت هستند که از سرور IdP ارائه می‌شوند، برخلاف RP، مانند نکات ورود به سیستم یا دامنه.

مثال

یک IdP به ترتیب از دو configURL برای مصرف کننده و شرکت پشتیبانی می کند. فایل پیکربندی مصرف‌کننده دارای برچسب 'consumer' و فایل پیکربندی سازمانی دارای برچسب 'enterprise' است.

با چنین تنظیماتی، فایل شناخته شده شامل accounts_endpoint و login_url است تا چندین configURL را مجاز کند.

{
  "provider_urls": [ "https://idp.example/fedcm.json" ],
  "accounts_endpoint": "https://idp.example/accounts",
  "login_url": "https://idp.example/login"
}

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

فایل پیکربندی مصرف‌کننده در https://idp.example/fedcm.json است که شامل ویژگی accounts است که 'consumer' با استفاده از include مشخص می‌کند.

{
  "accounts_endpoint": "https://idp.example/accounts",
  "client_metadata_endpoint": "/client_metadata",
  "login_url": "https://idp.example/login",
  "id_assertion_endpoint": "/assertion",
  "accounts": {
    "include": "consumer"
  }
}

فایل پیکربندی سازمانی در https://idp.example/enterprise/fedcm.json قرار دارد، که شامل ویژگی accounts است که با استفاده از include 'enterprise' مشخص می‌کند.

{
  "accounts_endpoint": "https://idp.example/accounts",
  "client_metadata_endpoint": "/enterprise/client_metadata",
  "login_url": "https://idp.example/login",
  "id_assertion_endpoint": "/assertion",
  "accounts": {
    "include": "enterprise"
  }
}

نقطه پایانی مشترک IdP حساب‌ها (در این مثال https://idp.example/accounts ) فهرستی از حساب‌ها را برمی‌گرداند که شامل یک ویژگی labels با labels اختصاص داده شده در یک آرایه برای هر حساب است. در زیر یک نمونه پاسخ برای کاربری است که دو حساب دارد. یکی برای مصرف کننده و دیگری برای شرکت است:

{
 "accounts": [{
   "id": "123",
   "given_name": "John",
   "name": "John Doe",
   "email": "john_doe@idp.example",
   "picture": "https://idp.example/profile/123",
   "labels": ["consumer"]
  }], [{
   "id": "4567",
   "given_name": "Jane",
   "name": "Jane Doe",
   "email": "jane_doe@idp.example",
   "picture": "https://idp.example/profile/4567",
   "labels": ["enterprise"]
  }]
}

هنگامی که یک RP می‌خواهد به کاربران 'enterprise' اجازه ورود به سیستم را بدهد، می‌توانند configURL 'enterprise' 'https://idp.example/enterprise/fedcm.json' در فراخوانی navigator.credentials.get() مشخص کنند:

let { token } = await navigator.credentials.get({
  identity: {
    providers: [{
      clientId: '1234',
      nonce: '234234',
      configURL: 'https://idp.example/enterprise/fedcm.json',
    },
  }
});

در نتیجه، فقط شناسه حساب '4567' برای ورود کاربر در دسترس است. شناسه حساب '123' به‌طور بی‌صدا توسط مرورگر پنهان می‌شود تا حسابی به کاربر ارائه نشود که توسط آن پشتیبانی نمی‌شود. IdP در این سایت

توجه:

برچسب ها رشته هستند. اگر آرایه labels یا فیلد include چیزی باشد که رشته نیست، نادیده گرفته می‌شود.
اگر هیچ برچسبی در configURL مشخص نشده باشد، همه حساب ها در انتخابگر حساب FedCM نمایش داده می شوند.
اگر هیچ برچسبی برای یک حساب مشخص نشده باشد، تنها در صورتی در انتخابگر حساب نمایش داده می شود که configURL نیز برچسبی را مشخص نکرده باشد.
اگر هیچ حسابی با برچسب درخواستی در جریان ویجت مطابقت نداشته باشد (شبیه به Domain Hint API)، گفتگوی FedCM یک اعلان ورود را نشان می دهد که به کاربر اجازه می دهد به یک حساب IdP وارد شود. برای جریان دکمه، پنجره بازشوی ورود مستقیماً باز می شود.

آزمایش اولیه: FedCM به عنوان یک سیگنال اعتماد برای Storage Access API

Chrome 126 در حال شروع آزمایش اولیه FedCM به عنوان یک سیگنال اعتماد برای Storage Access API است. با این تغییر، اعطای مجوز قبلی از طریق FedCM دلیل معتبری برای تأیید خودکار درخواست دسترسی به فضای ذخیره‌سازی توسط Storage Access APIها می‌شود.

این زمانی مفید است که یک iframe تعبیه‌شده بخواهد به منابع شخصی‌شده دسترسی پیدا کند: برای مثال، اگر idp.example در rp.example جاسازی شده باشد و نیاز به نشان دادن یک منبع شخصی‌شده داشته باشد. اگر مرورگر دسترسی به کوکی‌های شخص ثالث را محدود کند، حتی اگر کاربر با استفاده از idp.example با FedCM وارد rp.example شده باشد، iframe idp.example جاسازی‌شده نمی‌تواند منابع شخصی‌شده را درخواست کند، زیرا درخواست‌ها شامل نمی‌شوند. کوکی های شخص ثالث

برای رسیدن به این هدف، idp.example باید از طریق iframe تعبیه‌شده در وب‌سایت، مجوز دسترسی به فضای ذخیره‌سازی را دریافت کند، و این فقط از طریق یک درخواست مجوز قابل دریافت است.

با FedCM به‌عنوان یک سیگنال اعتماد برای Storage Access API ، بررسی‌های مجوز API دسترسی به ذخیره‌سازی نه تنها اعطای مجوزی را که توسط یک درخواست دسترسی به ذخیره‌سازی داده می‌شود، بلکه اعطای مجوز ارائه شده توسط یک درخواست FedCM را نیز می‌پذیرد.

// In top-level rp.example:

// Ensure FedCM permission has been granted.
const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://idp.example/fedcm.json',
      clientId: '123',
    }],
  },
  mediation: 'optional',
});

// In an embedded IdP iframe:

// No user gesture is needed to call this, and the call will be auto-granted.
await document.requestStorageAccess();

// This returns `true`.
const hasAccess = await document.hasStorageAccess();

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

در آزمایش مبدا شرکت کنید

با روشن کردن پرچم Chrome chrome://flags#fedcm-authz در Chrome 126 یا جدیدتر، می‌توانید بسته API Continuation FedCM را به صورت محلی امتحان کنید. همچنین می‌توانید با روشن کردن #fedcm-with-storage-access-api در Chrome 126 یا جدیدتر، FedCM را به‌عنوان یک سیگنال اعتماد برای Storage Access API به صورت محلی امتحان کنید.

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

برای امتحان نسخه آزمایشی اولیه بسته نرم افزاری FedCM Continuation ، دو نشانه آزمایشی مبدا ایجاد کنید:

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

اگر علاقه مند به فعال کردن Continuation API به همراه جریان دکمه هستید، آزمایش اولیه API Button Mode را نیز فعال کنید:

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

برای امتحان FedCM به عنوان یک سیگنال اعتماد برای آزمایش اولیه Storage Access API :

برای آزمایش اولیه ثبت نام کنید. توکن را در مبدا IdP جاسازی کنید .

نسخه آزمایشی اصلی بسته API Continuation و FedCM به عنوان یک سیگنال اعتماد برای آزمایش اولیه Storage Access API از Chrome 126 در دسترس هستند.

یک آزمایش اولیه شخص ثالث برای RP ثبت کنید

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

برای جاسازی توکن در یک وب سایت شخص ثالث، کد زیر را به کتابخانه جاوا اسکریپت IdP یا SDK که از مبدا IdP ارائه می شود، اضافه کنید.

const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = 'TOKEN_GOES_HERE';
document.head.appendChild(tokenElement);

TOKEN_GOES_HERE با توکن خود جایگزین کنید.