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 API Quản lý thông tin xác thực liên kết (FedCM) trên máy tính để bàn cho phép một số Các trường hợp sử dụng Uỷ quyền. Gói này bao gồm API Tiếp tục và Parameters API (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à Tuỳ chỉnh Nhãn tài khoản. 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) tự động cấp yêu cầu SAA 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
Bạn có thể xem bản minh hoạ về API trên Glitch.
API Tiếp tục cho phép Xác nhận mã nhận dạng của IdP (nhà cung cấp danh tính) điểm cuối sang trả về một URL mà FedCM sẽ hiển thị (không bắt buộc) để cho phép người dùng tiếp tục quy trình đăng nhập nhiều bước. Việc này cho phép IdP yêu cầu người dùng cấp quyền của bên phụ thuộc (RP) vượt quá khả năng của giao diện người dùng FedCM hiện tại, 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 giá trị nhận dạng sẽ trả về một mã thông báo cần thiết cho xác thực.
{
"token": "***********"
}
Tuy nhiên, với API Continuation, câu nhận định mã nhận dạng
điểm cuối có thể
trả về thuộc tính continue_on
bao gồm đường dẫn tuyệt đối hoặc tương đối
đường dẫn đến điểm cuối xác nhận giá trị 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ẽ xuất hiện
được mở và điều hướng người dùng đến đường dẫn được chỉ định.
Sau khi người dùng tương tác với trang đó (ví dụ: cấp thêm quyền)
để chia sẻ thông tin bổ sung với RP, trang IdP có thể gọi
IdentityProvider.resolve()
để phân giải phiên bản gốc
Gọi navigator.credentials.get()
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 API người gọi.
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 "chuyển đổi người dùng" hoặc trong trường hợp uỷ quyền), việc giải quyết lệnh gọi sẽ lấy một đối số thứ hai (không bắt buộc) cho phép một số đối số như:
IdentityProvider.resolve(token, {accountId: '1234');
Parameters API (API Tham số)
Thông số API cho phép RP để cung cấp các tham số bổ sung cho xác nhận mã nhận dạng điểm cuối. Thông qua Parameters API (API Tham số), bên bị hạn chế có thể truyền các tham số bổ sung tới IdP để yêu cầu quyền đối với các tài nguyên khác ngoài đăng nhập cơ bản. Người dùng sẽ uỷ quyền các quyền này thông qua một luồng trải nghiệm người dùng do IdP kiểm soát được chạy thông 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 một đối tượng trong
Cuộc 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
dưới dạng '1'
, foo
'BAR'
, ETC
dưới dạng 'MOAR'
và scope
dưới dạng 'calendar.readonly photos.write'
.
Tên này sẽ được dịch thành
param_IDP_SPECIFIC_PARAM=1¶m_foo=BAR¶m_ETC=MOAR¶m_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¶m_IDP_SPECIFIC_PARAM=1¶m_foo=BAR¶m_ETC=MOAR¶m_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 sẽ hữu ích nhất khi họ thay vì khi nhà phát triển cảm thấy rằng đó là cách dễ triển khai nhất. Cho ví dụ: yêu cầu quyền truy cập vào camera khi người dùng sắp chụp một bức ảnh sẽ được ưu tiên xin phép ngay khi người dùng truy cập vào của bạn. 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 cần thiết cho người dùng. Đây được gọi là "uỷ quyền động".
Để yêu cầu uỷ quyền một cách linh hoạt 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
. - Xác nhận mã nhận dạng
điểm cuối
xác nhận người dùng đã đăng nhập và trả lờ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 quyền bổ sung 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ẽ được đã đóng và lệnh gọinavigator.credentials.get()
ban đầu của RP nhận được mã thông báo hoặc mã uỷ quyền có liên quan để 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ông bố phù hợp trong hộp thoại FedCM; trách nhiệm của IdP để thêm các trường được yêu cầu vào mã thông báo được trả về. Xem xét yêu cầu này "hồ sơ cơ bản" trong OpenID Connect so với "phạm vi" trong OAuth.
![Thông báo công bố ở chế độ tiện ích.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/fedcm-126-with-disclosure-widget.jpg?authuser=0000&hl=vi)
![Thông báo công bố ở chế độ nút.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/fedcm-126-with-disclosure-button.jpg?authuser=0000&hl=vi)
Để 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
Cuộc gọi navigator.credentials.get()
. Các trường có thể chứa 'name'
, 'email'
và 'picture'
, nhưng có thể mở rộng để bao gồm thêm giá trị 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 xác nhận mã nhận dạng
điểm cuối
bao gồm tham số fields
do RP chỉ định, với disclosure_text_shown
được đặt thành 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 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 bên bị hạn chế 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, bạn sẽ xử lý vấn đề này bằng thông số tùy chỉnh như đã đề cập ở trên. Chiến lược phát hành đĩa đơ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.](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/fedcm-126-without-disclosure-widget.jpg?authuser=0000&hl=vi)
Trường hợp này xảy ra ngay cả khi phản hồi từ tài khoản
điểm cuối
không chứa mã ứng dụng khách khớp với bên bị hạn chế trong approved_clients
.
Trong trường hợp này, disclosure_text_shown
đã gửi đến xác nhận mã nhận dạng
điểm cuối 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 cho phép IdP (nhà cung cấp danh tính)
để điều chỉnh nhiều tệp cấu hình cho một IdP, bằng cách chỉ định
accounts_endpoint
và login_url
ở các địa điểm nổi tiếng
tệp giống nhau
làm tệp cấu hình.
Nếu accounts_endpoint
và login_url
được thêm vào tệp phổ biến,
provider_urls
sẽ bị bỏ qua để nhà cung cấp danh tính 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 để lùi về phía sau
tương thích.
Tệp phổ biến hỗ trợ nhiều configURLs 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 tiến và lùi với các tệp phổ biến hiện có và phiên bản cũ hơn của các trình duyệt đã được triển khai thử nghiệm.
- Có số lượng tệp cấu hình tuỳ ý, miễn là tất cả đều trỏ đến
cùng
accounts_endpoint
vàlogin_url
. - Không có cơ hội để thêm entropy vào yêu cầu tìm nạp đã được xác thực
được thực hiện cho
accounts_endpoint
vì bạn phải chỉ định thuộc tính này tại ".well-known" cấp độ.
Việc hỗ trợ nhiều configURLs là không bắt buộc và FedCM hiện có các hoạt động triển khai 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 FedCM
IdP cần chú thích về tài khoản sao cho 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. Có thể lọc tương tự bằng cách sử dụng Gợi ý về miền
API và Thông tin đăng nhập
Hint API 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. Tệp này đặc biệt hữu ích khi
nhiều cấu hình URL được sử dụng. Các nhãn tài khoản tuỳ chỉnh là
khác ở chỗ chúng được cung cấp từ máy chủ IdP, chứ không phải từ
RP, như 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. Chiến lược phát hành đĩa đơn
tệp cấu hình của người dùng có nhãn 'consumer'
và 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 configURLs.
{
"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 một tệp phổ biến,
provider_urls
sẽ bị bỏ qua. RP có thể trỏ trực tiếp vào 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
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 thuộc tính accounts
chỉ định 'enterprise'
bằng cách sử dụ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"
}
}
Các tài khoản IdP phổ biến
điểm cuối
(trong ví dụ này, https://idp.example/accounts
) trả về danh sách tài khoản
bao gồm một thuộc tính nhãn được gán 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 là dành cho
người tiêu dùng và hai quảng cáo còn lại 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, bên bị hạn chế có thể chỉ định
'enterprise'
configURL 'https://idp.example/enterprise/fedcm.json'
trong
Cuộc 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ể ký mã tài khoản '4567'
trong năm 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.
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 thử nghiệm theo nguyên gốc FedCM làm tín hiệu tin cậy cho Quyền truy cập vào bộ nhớ . Bằng 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 quyền truy cập vào bộ nhớ bằng Quyền truy cập vào bộ nhớ API.
Điều này rất hữu ích khi iframe được nhúng muốn truy cập 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ị một tài nguyên được cá nhân hóa. 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 với 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 bộ nhớ thông qua iframe được nhúng trên trang web và chỉ có thể lấy được iframe này thông qua lời nhắc cấp quyền.
Với FedCM là tín hiệu tin cậy đối với Quyền truy cập vào bộ nhớ API, Việc kiểm tra quyền đối với API Truy cập bộ nhớ không chỉ chấp nhận việc cấp quyền được đưa ra thông qua lời nhắc truy cập bộ nhớ mà còn là sự cấp quyền do Câu lệnh 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à thì 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, khi yêu cầu cấp quyền sẽ hiển thị một lời nhắc.
Tham gia dùng thử theo nguyên gốc
Bạn có thể dùng thử gói FedCM Tiếp tục API bằng cách bật một Chrome
cờ
chrome://flags#fedcm-authz
trên Chrome 126 trở lên. Bạn cũng có thể thử FedCM
làm tín hiệu tin cậy cho cục bộ Storage Access API 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ử nguồn gốc gói API Tiếp tục FedCM dùng thử, tạo 2 mã thông báo bản dùng thử theo nguyên gốc:
- Đăng ký dùng thử. Nhúng mã thông báo vào IdP (nhà cung cấp danh tính) máy chủ gốc.
- Đă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 Đă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 nút luồng, bật Chế độ nút Nguồn gốc API dùng thử cũng như:
- Đă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 Đăng ký một 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.
Để dùng thử FedCM làm tín hiệu tin cậy cho nguồn gốc của Storage Access API dùng thử:
- Đăng ký bản dùng thử theo nguyên gốc. Nhúng mã thông báo vào IdP (nhà cung cấp danh tính) máy chủ gốc.
Bản dùng thử theo nguyên gốc gói Continuation API (API Tiếp tục) và FedCM là 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 nhà cung cấp danh tính Thư viện JavaScript 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.