Trang này được dịch bởi Cloud Translation API.

Thông tin cập nhật của FedCM: Bản dùng thử theo nguyên gốc cho gói API Tiếp tục và cấp tự động API Truy cập bộ nhớ

Eiji Kitamura

Từ Chrome 126, nhà phát triển có thể bắt đầu chạy bản dùng thử theo nguyên gốc cho gói tính năng của API Quản lý thông tin xác thực liên kết (FedCM) trên máy tính để bàn hỗ trợ một số trường hợp sử dụng Uỷ quyền. Gói này bao gồm API Tiếp tục và API Thông số, cho phép trải nghiệm giống như quy trình uỷ quyền OAuth liên quan đến hộp thoại cấp quyền do nhà cung cấp danh tính (IdP) cung cấp. Gói này cũng bao gồm các thay đổi khác như API Trường, Nhiều cấu hình và Nhãn tài khoản tuỳ chỉnh. Từ Chrome 126, chúng tôi cũng sẽ giới thiệu bản dùng thử theo nguyên gốc cho API Truy cập bộ nhớ (SAA) mà sẽ tự động cấp SAA cho các yêu cầu nếu người dùng đã đăng nhập thành công bằng FedCM trước đây.

Bản dùng thử theo nguyên gốc: Gói FedCM Continuation API

Gói API Tiếp tục FedCM bao gồm nhiều đuôi FedCM:

API Tiếp tục
Parameters API (API Thông số)
API Trường
Nhiều cấu hình
Nhãn tài khoản tuỳ chỉnh

API Tiếp tục

Một người dùng đang đăng nhập vào RP sau đó cấp quyền thông qua chế độ nút.

Bạn có thể xem bản minh hoạ về API trên Glitch.

API Tiếp tục cho phép điểm cuối xác nhận mã nhận dạng của IdP tuỳ ý trả về một URL mà FedCM sẽ hiển thị để cho phép người dùng tiếp tục quy trình đăng nhập nhiều bước. Điều này cho phép IdP yêu cầu người dùng cấp các quyền bên tin cậy (RP) ngoài những quyền có thể thực hiện trong giao diện người dùng FedCM hiện có, chẳng hạn như quyền truy cập vào tài nguyên phía máy chủ của người dùng.

Thông thường, điểm cuối xác nhận mã nhận dạng sẽ trả về một mã thông báo bắt buộc để xác thực.

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

Tuy nhiên, với API Continuation, điểm cuối của câu nhận định mã nhận dạng có thể trả về một thuộc tính continue_on bao gồm một đường dẫn tuyệt đối hoặc một đường dẫn tương đối đến điểm cuối của câu nhận định nhận dạng.

{
  // 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=..."
}

Ngay khi trình duyệt nhận được phản hồi continue_on, một cửa sổ bật lên mới sẽ mở ra và chuyển người dùng đến đường dẫn đã chỉ định.

Sau khi người dùng tương tác với trang, chẳng hạn như cấp thêm quyền để chia sẻ thêm thông tin với RP, trang IdP có thể gọi IdentityProvider.resolve() để phân giải lệnh gọi navigator.credentials.get() ban đầu và trả về một mã thông báo làm đối số.

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

Sau đó, trình duyệt sẽ tự đóng cửa sổ bật lên và trả về mã thông báo cho phương thức gọi API.

Nếu người dùng từ chối yêu cầu, bạn có thể đóng cửa sổ đó bằng cách gọi IdentityProvider.close().

IdentityProvider.close();

Nếu vì lý do nào đó mà người dùng đã thay đổi tài khoản của họ trong cửa sổ bật lên (ví dụ: IdP cung cấp chức năng "chuyển đổi người dùng" hoặc trong các trường hợp uỷ quyền), thì lệnh gọi phân giải sẽ lấy một đối số thứ hai không bắt buộc cho phép những việc như:

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

Parameters API (API Tham số)

Parameters API (API Thông số) cho phép RP cung cấp thêm tham số cho điểm cuối của nội dung xác nhận giá trị nhận dạng. Với Parameters API (API Thông số), bên bị hạn chế có thể truyền các tham số bổ sung đến IdP để yêu cầu cấp quyền đối với các tài nguyên ngoài thông tin đăng nhập cơ bản. Người dùng sẽ cấp quyền cho các quyền này thông qua một quy trình trải nghiệm người dùng do IdP kiểm soát chạy qua API Tiếp tục.

Để sử dụng API này, hãy thêm các tham số vào thuộc tính params dưới dạng đối tượng trong lệnh gọi 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',
      }
    },
  }
});

Tên thuộc tính trong đối tượng params được thêm vào trước param_. Trong ví dụ trên, thuộc tính tham số chứa IDP_SPECIFIC_PARAM là '1', foo là 'BAR', ETC là 'MOAR' và scope là 'calendar.readonly photos.write'. Lệnh này sẽ được dịch là param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write trong phần nội dung HTTP của yêu cầu:

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

Cấp quyền một cách linh động

Nhìn chung, đối với người dùng, việc yêu cầu cấp quyền khi cần thiết sẽ hữu ích nhất, thay vì khi nhà phát triển cảm thấy rằng các quyền đó dễ triển khai nhất. Ví dụ: yêu cầu cấp quyền truy cập vào camera khi người dùng sắp chụp ảnh sẽ được ưu tiên hơn là yêu cầu cấp quyền ngay khi người dùng truy cập vào trang web. Phương pháp này cũng áp dụng cho tài nguyên máy chủ. Chỉ yêu cầu cấp quyền khi người dùng cần. Đây được gọi là "uỷ quyền động".

Để yêu cầu uỷ quyền một cách linh động bằng FedCM, IdP có thể:

Gọi navigator.credentials.get() bằng các tham số bắt buộc mà IdP có thể hiểu, chẳng hạn như scope.
Điểm cuối xác nhận mã nhận dạng xác nhận người dùng đã đăng nhập và phản hồi bằng một URL continue_on.
Trình duyệt sẽ mở một cửa sổ bật lên có trang quyền của IdP để yêu cầu cấp thêm quyền phù hợp với phạm vi được yêu cầu.
Sau khi IdP được uỷ quyền qua IdentityProvider.resolve(), cửa sổ sẽ đóng lại và lệnh gọi navigator.credentials.get() ban đầu của RP sẽ nhận được mã thông báo liên quan hoặc mã uỷ quyền để RP có thể trao đổi với mã truy cập thích hợp.

API trường

API trường cho phép RP khai báo các thuộc tính tài khoản để yêu cầu từ IdP sao cho trình duyệt có thể hiển thị giao diện người dùng có thông tin công bố phù hợp trong hộp thoại FedCM; nhà cung cấp có trách nhiệm đưa các trường được yêu cầu vào mã thông báo được trả về. Hãy xem xét việc yêu cầu này một "hồ sơ cơ bản" trong OpenID Connect so với "phạm vi" trong OAuth.

Để sử dụng API Trường, hãy thêm các tham số vào thuộc tính fields dưới dạng một mảng trong lệnh gọi navigator.credentials.get(). Các trường hiện có thể chứa 'name', 'email' và 'picture', nhưng có thể mở rộng để thêm nhiều giá trị hơn trong tương lai.

Yêu cầu với fields sẽ có dạng như sau:

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',
});

Yêu cầu HTTP đến điểm cuối xác nhận mã nhận dạng bao gồm tham số fields do RP chỉ định, với tham số disclosure_text_shown được đặt là true nếu đây không phải là người dùng cũ và các trường mà trình duyệt đã công bố cho người dùng trong tham số 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

Nếu RP cần quyền truy cập vào bất kỳ dữ liệu bổ sung nào từ IdP, chẳng hạn như quyền truy cập vào lịch, thì bạn phải xử lý việc này bằng một tham số tuỳ chỉnh như đã đề cập ở trên. IdP trả về một URL continue_on để yêu cầu quyền.

Nếu fields là một mảng trống, yêu cầu sẽ có dạng như sau:

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',
});

Nếu fields là một mảng trống, thì tác nhân người dùng sẽ bỏ qua giao diện người dùng công bố thông tin.

Thông báo công bố không xuất hiện ở chế độ tiện ích. Trong quy trình của nút, giao diện người dùng của thông tin công bố bị bỏ qua hoàn toàn.

Trường hợp này áp dụng ngay cả khi phản hồi từ điểm cuối của tài khoản không chứa mã ứng dụng khách khớp với RP trong approved_clients.

Trong trường hợp này, disclosure_text_shown được gửi đến điểm cuối của câu nhận định mã nhận dạng sẽ là false trong phần nội dung 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

Nhiều configURLs

Nhiều cấu hình URL cho phép IdP (nhà cung cấp danh tính) hỗ trợ nhiều tệp cấu hình cho một IdP, bằng cách chỉ định accounts_endpoint và login_url trong tệp phổ biến giống như tệp cấu hình.

Nếu accounts_endpoint và login_url được thêm vào tệp phổ biến, thì provider_urls sẽ bị bỏ qua để IdP có thể hỗ trợ nhiều tệp cấu hình. Nếu không, provider_urls sẽ tiếp tục có hiệu lực để tương thích ngược.

Tệp phổ biến hỗ trợ nhiều configURL có thể có dạng như sau:

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

Điều này cho phép chúng tôi:

Duy trì khả năng tương thích ngược và tiến với các tệp phổ biến hiện có và phiên bản cũ của các trình duyệt đã được triển khai tự nhiên.
Có số lượng tệp cấu hình tuỳ ý, miễn là tất cả các tệp đó đều trỏ đến cùng một accounts_endpoint và login_url.
Không có cơ hội để thêm entropy vào yêu cầu tìm nạp đã xác thực được gửi đến accounts_endpoint, vì bạn phải chỉ định entropy ở cấp "well-known".

Việc hỗ trợ nhiều configURLs là không bắt buộc và việc triển khai FedCM hiện tại có thể giữ nguyên.

Nhãn tài khoản tuỳ chỉnh

Nhãn tài khoản tuỳ chỉnh cho phép IDP FedCM chú thích tài khoản để bên bị hạn chế có thể lọc các tài khoản đó bằng cách chỉ định nhãn trong tệp cấu hình. Bạn có thể lọc tương tự bằng cách sử dụng API Gợi ý về miền và API Gợi ý đăng nhập bằng cách chỉ định chúng trong lệnh gọi navigator.credentials.get(), nhưng Nhãn tài khoản tuỳ chỉnh có thể lọc người dùng bằng cách chỉ định tệp cấu hình, điều này đặc biệt hữu ích khi sử dụng nhiều cấu hình URL. Nhãn tài khoản tuỳ chỉnh cũng khác ở chỗ nhãn được cung cấp từ máy chủ IdP, không phải RP (chẳng hạn như gợi ý thông tin đăng nhập hoặc gợi ý miền).

Ví dụ:

Nhà cung cấp danh tính (IdP) hỗ trợ 2 configURL tương ứng cho người dùng thông thường và doanh nghiệp. Tệp cấu hình dành cho người tiêu dùng có nhãn 'consumer', còn tệp cấu hình doanh nghiệp có nhãn 'enterprise'.

Với cách thiết lập như vậy, tệp phổ biến sẽ bao gồm accounts_endpoint và login_url để cho phép nhiều cấu hình URL.

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

Khi accounts_endpoint được cung cấp trong tệp phổ biến, provider_urls sẽ bị bỏ qua. RP có thể trỏ trực tiếp vào các tệp cấu hình tương ứng trong lệnh gọi navigator.credentials.get().

Tệp cấu hình của người dùng nằm tại https://idp.example/fedcm.json, bao gồm cả thuộc tính accounts chỉ định 'consumer' bằng 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"
  }
}

Tệp cấu hình doanh nghiệp nằm tại https://idp.example/enterprise/fedcm.json, bao gồm cả thuộc tính accounts chỉ định 'enterprise' bằng include.

{
  "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"
  }
}

Điểm cuối tài khoản phổ biến của IdP (trong ví dụ này là https://idp.example/accounts) trả về danh sách các tài khoản có chứa thuộc tính nhãn được chỉ định labels trong một mảng cho mỗi tài khoản. Sau đây là phản hồi mẫu cho một người dùng có hai tài khoản. Một phương thức dành cho người tiêu dùng và một phương thức dành cho doanh nghiệp:

{
 "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"]
  }]
}

Khi một bên bị hạn chế muốn cho phép người dùng 'enterprise' đăng nhập, họ có thể chỉ định 'enterprise' configURL 'https://idp.example/enterprise/fedcm.json' trong lệnh gọi navigator.credentials.get():

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

Do đó, người dùng chỉ có thể sử dụng mã tài khoản '4567' để đăng nhập. Trình duyệt đã tự động ẩn mã tài khoản của '123' để người dùng sẽ không được cung cấp một tài khoản không được IdP hỗ trợ trên trang web này.

Lưu ý:

Nhãn là các chuỗi. Nếu mảng labels hoặc trường include chứa nội dung không phải là chuỗi, thì nội dung đó sẽ bị bỏ qua.
Nếu không có nhãn nào được chỉ định trong configURL, tất cả tài khoản sẽ hiển thị trong trình chọn tài khoản FedCM.
Nếu không có nhãn nào được chỉ định cho một tài khoản, tài khoản đó sẽ chỉ hiển thị trong trình chọn tài khoản nếu configURL cũng không chỉ định nhãn.
Nếu không có tài khoản nào khớp với nhãn được yêu cầu trong quy trình tiện ích (tương tự như API Gợi ý miền), thì hộp thoại FedCM sẽ hiển thị lời nhắc đăng nhập, cho phép người dùng đăng nhập vào tài khoản IdP. Đối với luồng nút, cửa sổ bật lên đăng nhập sẽ mở trực tiếp.

Bản dùng thử theo nguyên gốc: FedCM làm tín hiệu tin cậy cho Storage Access API

Chrome 126 đang bắt đầu bản dùng thử theo nguyên gốc của FedCM làm tín hiệu tin cậy cho API Truy cập bộ nhớ. Với thay đổi này, việc cấp quyền trước đó qua FedCM sẽ trở thành lý do hợp lệ để tự động phê duyệt yêu cầu truy cập bộ nhớ của API Truy cập bộ nhớ.

Điều này rất hữu ích khi iframe được nhúng muốn truy cập vào các tài nguyên được cá nhân hoá: ví dụ: nếu idp.example được nhúng trong rp.example và cần hiển thị tài nguyên được cá nhân hoá. Nếu trình duyệt hạn chế quyền truy cập vào cookie của bên thứ ba, ngay cả khi người dùng đăng nhập vào rp.example bằng idp.example bằng FedCM, iframe idp.example nhúng sẽ không thể yêu cầu tài nguyên được cá nhân hoá vì các yêu cầu sẽ không bao gồm cookie của bên thứ ba.

Để đạt được điều này, idp.example cần có quyền truy cập vào bộ nhớ thông qua iframe được nhúng trên trang web và điều này chỉ có thể nhận được thông qua lời nhắc cấp quyền.

Với FedCM là tín hiệu tin cậy cho API Truy cập bộ nhớ, việc kiểm tra quyền API Truy cập bộ nhớ không chỉ chấp nhận hoạt động cấp quyền do lời nhắc truy cập bộ nhớ đưa ra mà còn chấp nhận quyền được cấp qua lời nhắc 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();

Sau khi người dùng đăng nhập bằng FedCM, quyền này sẽ tự động được cấp miễn là phương thức xác thực FedCM đang hoạt động. Điều này có nghĩa là sau khi người dùng bị ngắt kết nối, việc yêu cầu quyền sẽ hiển thị lời nhắc.

Tham gia dùng thử theo nguyên gốc

Bạn có thể dùng thử gói API Tiếp tục FedCM trên thiết bị bằng cách bật cờ Chrome chrome://flags#fedcm-authz trên Chrome 126 trở lên. Bạn cũng có thể dùng thử FedCM làm tín hiệu tin cậy cho API Truy cập bộ nhớ trên thiết bị bằng cách bật #fedcm-with-storage-access-api trên Chrome 126 trở lên.

Những tính năng này cũng được cung cấp dưới dạng bản dùng thử theo nguyên gốc. Bản dùng thử theo nguyên gốc cho phép bạn dùng thử các tính năng mới và đưa ra ý kiến phản hồi về khả năng hữu dụng, tính thiết thực và hiệu quả của các tính năng đó. Để biết thêm thông tin, hãy xem bài viết Bắt đầu sử dụng bản dùng thử theo nguyên gốc.

Để dùng thử bản dùng thử theo nguyên gốc gói FedCM Continuation API, hãy tạo 2 mã dùng thử theo nguyên gốc:

Đăng ký dùng thử. Nhúng mã thông báo vào nguồn gốc của IdP.
Đăng ký bản dùng thử theo nguyên gốc, sau đó chọn hộp đánh dấu so khớp bên thứ ba. Làm theo hướng dẫn trong phần Đăng ký bản dùng thử theo nguyên gốc của bên thứ ba cho RP để nhúng mã thông báo cho RP đó.

Nếu bạn muốn bật API Tiếp tục cùng với quy trình nút, hãy bật bản dùng thử theo nguyên gốc API Chế độ nút:

Đăng ký sử dụng bản dùng thử theo nguyên gốc với tư cách là một bên thứ ba. Làm theo hướng dẫn trong phần Đăng ký bản dùng thử theo nguyên gốc của bên thứ ba cho RP để nhúng mã thông báo cho RP đó.

Cách dùng thử FedCM làm tín hiệu tin cậy cho bản dùng thử theo nguyên gốc Storage Access API:

Đăng ký bản dùng thử theo nguyên gốc. Nhúng mã thông báo vào nguồn gốc của IdP.

Bản dùng thử theo nguyên gốc gói Continuation API (API Tiếp tục) và FedCM làm tín hiệu tin cậy cho bản dùng thử theo nguyên gốc Storage Access API hiện có trên Chrome 126.

Đăng ký một bản dùng thử theo nguyên gốc của bên thứ ba cho RP

Truy cập vào trang đăng ký bản dùng thử theo nguyên gốc.
Nhấp vào nút Register (Đăng ký) rồi điền vào biểu mẫu để yêu cầu mã thông báo.
Nhập nguồn gốc của IdP làm Nguồn gốc web.
Kiểm tra tính năng So khớp bên thứ ba để chèn mã thông báo bằng JavaScript trên các nguồn gốc khác.
Nhấp vào Gửi.
Nhúng mã thông báo đã phát hành vào trang web của bên thứ ba.

Để nhúng mã thông báo vào một trang web của bên thứ ba, hãy thêm mã sau vào thư viện JavaScript của IdP hoặc SDK được phân phát từ nguồn gốc của IdP.

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

Thay thế TOKEN_GOES_HERE bằng mã thông báo của riêng bạn.