Triển khai giải pháp danh tính bằng FedCM ở phía Nhà cung cấp danh tính

Việc triển khai FedCM bao gồm một số bước cốt lõi cho cả Nhà cung cấp danh tính (IdP)Bên phụ thuộc (RP). Hãy tham khảo tài liệu để tìm hiểu cách triển khai FedCM ở phía RP.

IdPs phải hoàn tất các bước sau để triển khai FedCM:

Tạo tệp well-known

Để ngăn trình theo dõi lợi dụng API, bạn phải phân phát một tệp đã biết từ /.well-known/web-identity của eTLD+1 của IdP.

Tệp đã biết có thể bao gồm các thuộc tính sau:

Thuộc tính Bắt buộc Mô tả
provider_urls bắt buộc Mảng các đường dẫn tệp cấu hình IdP. Bỏ qua (nhưng vẫn bắt buộc) nếu bạn chỉ định accounts_endpointlogin_url.
accounts_endpoint nên dùng, yêu cầu login_url
URL cho điểm cuối tài khoản. Điều này cho phép hỗ trợ nhiều cấu hình, miễn là mỗi tệp cấu hình sử dụng cùng một URL login_urlaccounts_endpoint.

Lưu ý: Thông số này được hỗ trợ từ Chrome 132.
login_url nên dùng, yêu cầu accounts_endpoint URL trang đăng nhập để người dùng đăng nhập vào IdP. Điều này cho phép hỗ trợ nhiều cấu hình, miễn là mỗi tệp cấu hình sử dụng cùng một login_urlaccounts_endpoint.

Lưu ý: thông số này được hỗ trợ kể từ Chrome 132 trở lên.

Ví dụ: nếu các điểm cuối của IdP được phân phát trong https://accounts.idp.example/, thì các điểm cuối đó phải phân phát một tệp well-known tại https://idp.example/.well-known/web-identity cũng như tệp cấu hình IdP. Dưới đây là ví dụ về nội dung tệp phổ biến:

  {
    "provider_urls": ["https://accounts.idp.example/config.json"]
  }

IdP có thể chứa nhiều tệp cấu hình cho một IdP, bằng cách chỉ định accounts_endpointlogin_url trong tệp well-known.
Tính năng này có thể hữu ích trong các trường hợp sau:

  • Một IdP cần hỗ trợ nhiều cấu hình thử nghiệm và cấu hình phát hành.
  • Nhà cung cấp danh tính cần hỗ trợ nhiều cấu hình theo khu vực (ví dụ: eu-idp.exampleus-idp.example).

Để hỗ trợ nhiều cấu hình (ví dụ: để phân biệt giữa môi trường thử nghiệm và môi trường sản xuất), IdP phải chỉ định accounts_endpointlogin_url:

  {
    // This property is required, but will be ignored when IdP supports
    // multiple configs (when `accounts_endpoint` and `login_url` are
    // specified), as long as `accounts_endpoint` and `login_url` in
    // that config file match those in the well-known file.
    "provider_urls": [ "https://idp.example/fedcm.json" ],

    // Specify accounts_endpoint and login_url properties to support
    // multiple config files.
    // Note: The accounts_endpoint and login_url must be identical
    // across all config files. Otherwise,
    // the configurations won't be supported.
    "accounts_endpoint": "https://idp.example/accounts",
    "login_url": "https://idp.example/login"
  }

Tạo tệp cấu hình IdP và điểm cuối

Tệp cấu hình IdP cung cấp danh sách các điểm cuối bắt buộc cho trình duyệt. Nhà cung cấp danh tính (IdP) phải lưu trữ một hoặc nhiều tệp cấu hình, cũng như các điểm cuối và URL bắt buộc. Tất cả phản hồi JSON phải được phân phát bằng loại nội dung application/json.

URL của tệp cấu hình được xác định bằng các giá trị được cung cấp cho lệnh gọi navigator.credentials.get() được thực thi trên RP.

  const credential = await navigator.credentials.get({
    identity: {
      context: 'signup',
      providers: [{
        configURL: 'https://accounts.idp.example/config.json',
        clientId: '********',
        nonce: '******'
      }]
    }
  });
  const { token } = credential;

RP sẽ chuyển URL của tệp cấu hình đến lệnh gọi API FedCM để cho phép người dùng đăng nhập:

  // Executed on RP's side:
  const credential = await navigator.credentials.get({
    identity: {
      context: 'signup',
      providers: [{
        // To allow users to sign in with an IdP using FedCM, RP specifies the IdP's config file URL:
        configURL: 'https://accounts.idp.example/fedcm.json',
        clientId: '********',
  });
  const { token } = credential;

Trình duyệt sẽ tìm nạp tệp cấu hình bằng yêu cầu GET mà không có tiêu đề Origin hoặc tiêu đề Referer. Yêu cầu không có cookie và không theo lệnh chuyển hướng. Điều này giúp ngăn IdP biết được ai đã đưa ra yêu cầu và RP nào đang cố gắng kết nối. Ví dụ:

  GET /config.json HTTP/1.1
  Host: accounts.idp.example
  Accept: application/json
  Sec-Fetch-Dest: webidentity

IdP phải triển khai một điểm cuối cấu hình phản hồi bằng JSON. Tệp JSON bao gồm các thuộc tính sau:

Thuộc tính Mô tả
accounts_endpoint (bắt buộc) URL cho điểm cuối tài khoản.
accounts.include (không bắt buộc) Chuỗi nhãn tài khoản tuỳ chỉnh, xác định những tài khoản sẽ được trả về khi sử dụng tệp cấu hình này, ví dụ: "accounts": {"include": "developer"}.
Nhà cung cấp danh tính có thể triển khai tính năng gắn nhãn tuỳ chỉnh cho tài khoản như sau:

Ví dụ: một IdP triển khai tệp cấu hình "https://idp.example/developer-config.json" với "accounts": {"include": "developer"} được chỉ định. IdP cũng đánh dấu một số tài khoản bằng nhãn "developer" bằng cách sử dụng tham số labels trong điểm cuối tài khoản. Khi một RP gọi navigator.credentials.get() với tệp cấu hình "https://idp.example/developer-config.json" được chỉ định, hệ thống sẽ chỉ trả về những tài khoản có nhãn "developer".

Lưu ý: Nhãn tài khoản tuỳ chỉnh được hỗ trợ từ Chrome 132.
client_metadata_endpoint (không bắt buộc) URL của điểm cuối siêu dữ liệu ứng dụng.
id_assertion_endpoint (bắt buộc) URL cho điểm cuối xác nhận mã nhận dạng.
disconnect (không bắt buộc) URL cho điểm cuối ngắt kết nối.
login_url (bắt buộc) URL trang đăng nhập để người dùng đăng nhập vào IdP.
branding (không bắt buộc) Đối tượng chứa nhiều tuỳ chọn thương hiệu.
branding.background_color (không bắt buộc) Tuỳ chọn xây dựng thương hiệu giúp đặt màu nền của nút "Tiếp tục dưới tư cách...". Sử dụng cú pháp CSS có liên quan, cụ thể là hex-color, hsl(), rgb() hoặc named-color.
branding.color (không bắt buộc) Tuỳ chọn xây dựng thương hiệu giúp đặt màu văn bản của nút "Tiếp tục dưới tư cách...". Sử dụng cú pháp CSS có liên quan, cụ thể là hex-color, hsl(), rgb() hoặc named-color.
branding.icons (không bắt buộc) Mảng các đối tượng biểu tượng. Các biểu tượng này xuất hiện trong hộp thoại đăng nhập. Đối tượng biểu tượng có hai tham số:
  • url (bắt buộc): URL của hình ảnh biểu tượng. Tính năng này không hỗ trợ hình ảnh SVG.
  • size (không bắt buộc): Kích thước biểu tượng, ứng dụng giả định là hình vuông và độ phân giải đơn. Số này phải lớn hơn hoặc bằng 25px ở chế độ thụ động và lớn hơn hoặc bằng 40px ở chế độ chủ động.
modes Đối tượng chứa thông số kỹ thuật về cách hiển thị giao diện người dùng FedCM ở các chế độ khác nhau:
  • active
  • passive
modes.active Đối tượng chứa các thuộc tính cho phép tuỳ chỉnh hành vi của FedCM ở một chế độ cụ thể. Cả modes.activemodes.passive đều có thể chứa tham số sau:
  • supports_use_other_account: boolean chỉ định xem người dùng có thể đăng nhập bằng một tài khoản khác với tài khoản mà họ đang đăng nhập hay không (nếu IdP hỗ trợ nhiều tài khoản).

Lưu ý: Tính năng Sử dụng tài khoản khác và chế độ đang hoạt động được hỗ trợ từ Chrome 132.
modes.passive

Dưới đây là ví dụ về nội dung phản hồi của IdP:

  {
    "accounts_endpoint": "/accounts.example",
    "client_metadata_endpoint": "/client_metadata.example",
    "id_assertion_endpoint": "/assertion.example",
    "disconnect_endpoint": "/disconnect.example",
    "login_url": "/login",
    // When RPs use this config file, only those accounts will be
    //returned that include `developer` label in the accounts endpoint.
    "accounts": {"include": "developer"},
    "modes": {
        "active": {
          "supports_use_other_account": true,
        }
    },
    "branding": {
      "background_color": "green",
      "color": "#FFEEAA",
      "icons": [{
        "url": "https://idp.example/icon.ico",
        "size": 25
      }]
    }
  }

Sau khi tìm nạp tệp cấu hình, trình duyệt sẽ gửi các yêu cầu tiếp theo đến điểm cuối của IdP:

Điểm cuối của IdP
Các điểm cuối của IdP

Sử dụng tài khoản khác

Người dùng có thể chuyển sang một tài khoản khác với tài khoản mà họ đang đăng nhập, nếu IdP hỗ trợ nhiều tài khoản hoặc thay thế tài khoản hiện có.

Để cho phép người dùng chọn các tài khoản khác, IdP phải chỉ định tính năng này trong tệp cấu hình:

  {
    "accounts_endpoint" : "/accounts.example",
    "modes": {
      "active": {
        // Allow the user to choose other account (false by default)
        "supports_use_other_account": true
      }
      // "passive" mode can be configured separately
    }
  }

Điểm cuối tài khoản

Điểm cuối tài khoản của IdP trả về danh sách tài khoản mà người dùng đã đăng nhập vào IdP. Nếu IdP hỗ trợ nhiều tài khoản, thì điểm cuối này sẽ trả về tất cả tài khoản đã đăng nhập.

Trình duyệt gửi một yêu cầu GET có cookie với SameSite=None, nhưng không có tham số client_id, tiêu đề Origin hoặc tiêu đề Referer. Điều này giúp ngăn IdP tìm hiểu được RP mà người dùng đang cố gắng đăng nhập. Ví dụ:

  GET /accounts.example HTTP/1.1
  Host: accounts.idp.example
  Accept: application/json
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

Sau khi nhận được yêu cầu, máy chủ phải:

  1. Xác minh rằng yêu cầu chứa tiêu đề HTTP Sec-Fetch-Dest: webidentity.
  2. So khớp cookie phiên với mã nhận dạng của các tài khoản đã đăng nhập.
  3. Phản hồi bằng danh sách tài khoản.

Trình duyệt dự kiến phản hồi JSON sẽ bao gồm một thuộc tính accounts với một mảng thông tin tài khoản có các thuộc tính sau:

Thuộc tính Mô tả
id (bắt buộc) Mã nhận dạng duy nhất của người dùng.
name (bắt buộc) Họ và tên của người dùng.
email (bắt buộc) Địa chỉ email của người dùng.
given_name (không bắt buộc) Tên của người dùng.
picture (không bắt buộc) URL của hình đại diện của người dùng.
approved_clients (không bắt buộc) Một mảng gồm các mã ứng dụng RP mà người dùng đã đăng ký.
login_hints (không bắt buộc) Một mảng gồm tất cả các loại bộ lọc có thể có mà IdP hỗ trợ để chỉ định một tài khoản. RP có thể gọi navigator.credentials.get() bằng thuộc tính loginHint để hiển thị có chọn lọc tài khoản đã chỉ định.
domain_hints (không bắt buộc) Một mảng gồm tất cả các miền mà tài khoản được liên kết. RP có thể gọi navigator.credentials.get() bằng thuộc tính domainHint để lọc tài khoản.
labels (không bắt buộc) Mảng chuỗi Nhãn tài khoản tuỳ chỉnh mà một tài khoản được liên kết.
IdP có thể triển khai tính năng gắn nhãn tuỳ chỉnh cho tài khoản như sau:
  • Chỉ định nhãn tài khoản trong điểm cuối tài khoản (bằng cách sử dụng tham số labels này).
  • Tạo tệp cấu hình cho từng nhãn cụ thể.

Ví dụ: một IdP triển khai tệp cấu hình https://idp.example/developer-config.json với "accounts": {"include": "developer"} được chỉ định. IdP cũng đánh dấu một số tài khoản bằng nhãn "developer" bằng cách sử dụng tham số labels trong điểm cuối tài khoản. Khi một RP gọi navigator.credentials.get() với tệp cấu hình https://idp.example/developer-config.json được chỉ định, hệ thống sẽ chỉ trả về những tài khoản có nhãn "developer".

Nhãn tài khoản tuỳ chỉnh khác với gợi ý đăng nhập và gợi ý miền ở chỗ các nhãn này do máy chủ IdP duy trì hoàn toàn và RP chỉ chỉ định tệp cấu hình cần sử dụng.

Lưu ý: Nhãn tài khoản tuỳ chỉnh được hỗ trợ từ Chrome 132.

Ví dụ về nội dung phản hồi:

  {
    "accounts": [{
      "id": "1234",
      "given_name": "John",
      "name": "John Doe",
      "email": "john_doe@idp.example",
      "picture": "https://idp.example/profile/123",
      // Ids of those RPs where this account can be used
      "approved_clients": ["123", "456", "789"],
      // This account has 'login_hints`. When an RP calls `navigator.credentials.get()`
      // with a `loginHint` value specified, for example, `exampleHint`, only those
      // accounts will be shown to the user whose 'login_hints' array contains the `exampleHint`.
      "login_hints": ["demo1", "exampleHint"],
      // This account is labelled. IdP can implement a specific config file for a
      // label, for example, `https://idp.example/developer-config.json`. Like that
      // RPs can filter out accounts by calling `navigator.credentials.get()` with
      // `https://idp.example/developer-config.json` config file.
      "labels": ["hr", "developer"]
    }, {
      "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"],
      "domain_hints": ["@domain.example"]
    }]
  }

Nếu người dùng chưa đăng nhập, hãy phản hồi bằng HTTP 401 (Không được phép).

Danh sách tài khoản được trả về sẽ do trình duyệt sử dụng và sẽ không có sẵn cho RP.

Điểm cuối xác nhận giấy tờ tuỳ thân

Điểm cuối xác nhận danh tính của IdP trả về một xác nhận cho người dùng đã đăng nhập. Khi người dùng đăng nhập vào trang web RP bằng lệnh gọi navigator.credentials.get(), trình duyệt sẽ gửi yêu cầu POST có cookie với SameSite=None và loại nội dung là application/x-www-form-urlencoded đến điểm cuối này cùng với thông tin sau:

Thuộc tính Mô tả
client_id (bắt buộc) Giá trị nhận dạng ứng dụng của RP.
account_id (bắt buộc) Mã nhận dạng duy nhất của người dùng đăng nhập.
disclosure_text_shown Kết quả là một chuỗi "true" hoặc "false" (thay vì một boolean). Kết quả là "false" trong các trường hợp sau:
  • Nếu văn bản thông tin công bố không xuất hiện vì mã ứng dụng của RP có trong danh sách thuộc tính approved_clients của phản hồi từ điểm cuối tài khoản.
  • Nếu văn bản thông tin công bố không xuất hiện vì trình duyệt đã quan sát thấy một khoảnh khắc đăng ký trong quá khứ khi không có approved_clients.
  • Nếu tham số fields không bao gồm một hoặc nhiều trong số ba trường ("tên", "email" và "ảnh"), ví dụ: fields=[ ] hoặc fields=['name', 'picture']. Điều này cần thiết để tương thích ngược với các phương thức triển khai IdP cũ, trong đó chuỗi thông tin công bố phải luôn bao gồm cả ba trường.
is_auto_selected Nếu tự động xác thực lại được thực hiện trên RP, is_auto_selected sẽ cho biết "true". Nếu không, "false". Điều này sẽ giúp hỗ trợ thêm nhiều tính năng liên quan đến bảo mật. Ví dụ: một số người dùng có thể thích cấp độ bảo mật cao hơn, yêu cầu người dùng phải tham gia xác thực một cách rõ ràng. Nếu nhận được yêu cầu mã thông báo mà không có tính năng dàn xếp như vậy, thì IdP có thể xử lý yêu cầu theo cách khác. Ví dụ: trả về một mã lỗi để RP có thể gọi lại API FedCM bằng mediation: required.
fields (không bắt buộc) Mảng các chuỗi chỉ định thông tin người dùng ("tên", "email", "ảnh") mà RP cần IdP chia sẻ với họ.
Trình duyệt sẽ gửi fields, disclosure_text_showndisclosure_shown_for liệt kê các trường được chỉ định trong yêu cầu POST, như trong ví dụ sau.

Lưu ý: Thông số Trường được hỗ trợ từ Chrome 132.
params (không bắt buộc) Bất kỳ đối tượng JSON hợp lệ nào cho phép chỉ định các tham số khoá-giá trị tuỳ chỉnh bổ sung, ví dụ:
  • scope: Giá trị chuỗi chứa các quyền bổ sung mà RP cần yêu cầu, ví dụ: "drive.readonly calendar.readonly"
  • nonce: Chuỗi ngẫu nhiên do RP cung cấp để đảm bảo phản hồi được đưa ra cho yêu cầu cụ thể này. Ngăn chặn các cuộc tấn công phát lại.
  • Các thông số khoá-giá trị tuỳ chỉnh khác.
Khi trình duyệt gửi yêu cầu POST, giá trị params sẽ được chuyển đổi tuần tự thành JSON rồi mã hoá theo tỷ lệ phần trăm.

Lưu ý: Chrome 132 trở lên hỗ trợ Parameters API.

Ví dụ về tiêu đề HTTP:

  POST /assertion.example HTTP/1.1
  Host: accounts.idp.example
  Origin: https://rp.example/
  Content-Type: application/x-www-form-urlencoded
  Cookie: 0x23223
  Sec-Fetch-Dest: webidentity

  // disclosure_text_shown is set to 'false', as the 'name' field value is missing in 'fields' array
  // params value is serialized to JSON and then percent-encoded.
  account_id=123&client_id=client1234&disclosure_text_shown=false&is_auto_selected=true&params=%22%7B%5C%22nonce%5C%22%3A%5C%22nonce-value%5C%22%7D%22.%0D%0A4&disclosure_text_shown=true&fields=email,picture&disclosure_shown_for=email,picture

Sau khi nhận được yêu cầu, máy chủ phải:

  1. Trả lời yêu cầu bằng CORS (Chia sẻ tài nguyên trên nhiều nguồn gốc).
  2. Xác minh rằng yêu cầu chứa tiêu đề HTTP Sec-Fetch-Dest: webidentity.
  3. So khớp tiêu đề Origin với nguồn gốc RP do client_id xác định. Từ chối nếu không khớp.
  4. So khớp account_id với mã nhận dạng của tài khoản đã đăng nhập. Từ chối nếu không khớp.
  5. Phản hồi bằng mã thông báo. Nếu yêu cầu bị từ chối, hãy phản hồi bằng phản hồi lỗi.

IdP có thể quyết định cách phát hành mã thông báo. Nhìn chung, mã thông báo này được ký bằng thông tin như mã tài khoản, mã ứng dụng, nguồn gốc của tổ chức phát hành và số chỉ dùng một lần để RP có thể xác minh mã thông báo là thật.

Trình duyệt dự kiến phản hồi JSON sẽ bao gồm thuộc tính sau:

Thuộc tính Mô tả
token Mã thông báo là một chuỗi chứa các thông báo xác nhận về việc xác thực.
continue_on URL chuyển hướng cho phép luồng đăng nhập nhiều bước.

Mã thông báo được trả về được trình duyệt chuyển đến RP để RP có thể xác thực.

  {
    // IdP can respond with a token to authenticate the user
    "token": "***********"
  }

Tính năng Tiếp tục

IdP có thể cung cấp URL chuyển hướng trong phản hồi điểm cuối xác nhận danh tính để cho phép quy trình đăng nhập nhiều bước. Điều này rất hữu ích khi IdP cần yêu cầu thêm thông tin hoặc quyền, ví dụ:

  • Quyền truy cập vào tài nguyên phía máy chủ của người dùng.
  • Xác minh rằng thông tin liên hệ là mới nhất.
  • Chế độ kiểm soát của cha mẹ.

Điểm cuối xác nhận 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 tương đối đến điểm cuối xác nhận mã 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 popup window:
    "continue_on": "https://idp.example/continue_on_url"
  }

Nếu phản hồi chứa tham số continue_on, một cửa sổ bật lên mới sẽ mở ra và điều hướng người dùng đến đường dẫn đã chỉ định. Sau khi người dùng tương tác với trang continue_on, IdP sẽ gọi IdentityProvider.resolve() với mã thông báo được truyền dưới dạng đối số để có thể phân giải lời hứa từ lệnh gọi navigator.credentials.get() ban đầu:

  document.getElementById('example-button').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 đóng cửa sổ bật lên và trả về mã thông báo cho lệnh gọi API. Lệnh gọi IdentityProvider.resolve() một lần là cách duy nhất để cửa sổ mẹ (RP) và cửa sổ bật lên (IdP) giao tiếp.
Nếu người dùng từ chối yêu cầu, thì IdP có thể đóng cửa sổ bằng cách gọi IdentityProvider.close().

  IdentityProvider.close();

Continuation API yêu cầu sự tương tác rõ ràng của người dùng (lượt nhấp) để hoạt động. Dưới đây là cách hoạt động của Continuation API với các chế độ cách thức dàn xếp khác nhau:

  • chế độ thụ động:
    • mediation: 'optional' (mặc định): API Tiếp tục sẽ chỉ hoạt động với một cử chỉ của người dùng, chẳng hạn như nhấp vào một nút trên trang hoặc trên giao diện người dùng FedCM. Khi tính năng tự động xác thực lại được kích hoạt mà không có cử chỉ của người dùng, cửa sổ bật lên sẽ không mở ra và lời hứa sẽ bị từ chối.
    • mediation: 'required': Luôn yêu cầu người dùng tương tác, vì vậy, Continuation API luôn hoạt động.
  • chế độ đang hoạt động:
    • Người dùng luôn phải kích hoạt. Continuation API tương thích.

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 hàm "sử dụng tài khoản khác" hoặc trong 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 nội dung như:

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

Trả về phản hồi lỗi

id_assertion_endpoint cũng có thể trả về một phản hồi "lỗi", trong đó có hai trường không bắt buộc:

  • code: IdP có thể chọn một trong các lỗi đã biết trong danh sách lỗi được chỉ định của OAuth 2.0 (invalid_request, unauthorized_client, access_denied, server_errortemporarily_unavailable) hoặc sử dụng bất kỳ chuỗi tuỳ ý nào. Nếu là trường hợp sau, Chrome sẽ hiển thị giao diện người dùng lỗi bằng thông báo lỗi chung và chuyển mã đến RP.
  • url: Xác định một trang web mà con người có thể đọc được, trong đó có thông tin về lỗi để cung cấp thêm thông tin về lỗi cho người dùng. Trường này rất hữu ích cho người dùng vì trình duyệt không thể cung cấp thông báo lỗi đa dạng thức trong giao diện người dùng tích hợp. Ví dụ: đường liên kết đến các bước tiếp theo hoặc thông tin liên hệ với dịch vụ khách hàng. Nếu muốn tìm hiểu thêm về thông tin chi tiết về lỗi và cách khắc phục, người dùng có thể truy cập vào trang được cung cấp từ giao diện người dùng của trình duyệt để biết thêm thông tin. URL phải thuộc cùng một trang web với configURL của Nhà cung cấp dịch vụ nhận dạng (IdP).
  // id_assertion_endpoint response
  {
    "error" : {
      "code": "access_denied",
      "url" : "https://idp.example/error?type=access_denied"
    }
  }

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

Với Nhãn tài khoản tuỳ chỉnh, IdP có thể chú thích tài khoản người dùng bằng nhãn và RP có thể chọn chỉ tìm nạp tài khoản có nhãn cụ thể bằng cách chỉ định configURL cho nhãn cụ thể đó. Điều này có thể hữu ích khi một RP cần lọc ra các tài khoản theo tiêu chí cụ thể, chẳng hạn như chỉ hiển thị các tài khoản theo vai trò cụ thể như "developer" hoặc "hr".

Bạn có thể lọc tương tự bằng cách sử dụng các tính năng Gợi ý về miềnGợi ý đăng nhập, bằng cách chỉ định các tính năng đó trong lệnh gọi navigator.credentials.get(). Tuy nhiên, 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 configURL. Nhãn tài khoản tuỳ chỉnh cũng khác ở chỗ chúng được cung cấp từ máy chủ IdP, thay vì từ RP, chẳng hạn như gợi ý đăng nhập hoặc miền.

Hãy xem xét một IdP muốn phân biệt giữa tài khoản "developer""hr". Để đạt được điều này, IdP cần hỗ trợ hai configURL tương ứng cho "developer""hr":

  • Tệp cấu hình dành cho nhà phát triển https://idp.example/developer/fedcm.json có nhãn "developer" và tệp cấu hình dành cho doanh nghiệp https://idp.example/hr/fedcm.json có nhãn "hr" như sau:
  // The developer config file at `https://idp.example/developer/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "accounts": {
      // Account label
      "include": "developer"
    }
  }
  // The hr config file at `https://idp.example/hr/fedcm.json`
  {
    "accounts_endpoint": "https://idp.example/accounts",
    "client_metadata_endpoint": "/client_metadata",
    "login_url": "https://idp.example/login",
    "id_assertion_endpoint": "/assertion",
    "accounts": {
      // Account label
      "include": "hr"
    }
  }
  • Với chế độ thiết lập như vậy, tệp đã biết phải bao gồm accounts_endpointlogin_url để cho phép nhiều configURL:
  {
    "provider_urls": [ "https://idp.example/fedcm.json" ],
    "accounts_endpoint": "https://idp.example/accounts",
    "login_url": "https://idp.example/login"
  }
  • Điểm cuối tài khoản IdP phổ biến (trong ví dụ này là https://idp.example/accounts) trả về danh sách tài khoản bao gồm một thuộc tính labels có nhãn được chỉ định trong một mảng cho mỗi tài khoản:
  {
  "accounts": [{
    "id": "123",
    "given_name": "John",
    "name": "John Doe",
    "email": "john_doe@idp.example",
    "picture": "https://idp.example/profile/123",
    "labels": ["developer"]
    }], [{
    "id": "4567",
    "given_name": "Jane",
    "name": "Jane Doe",
    "email": "jane_doe@idp.example",
    "picture": "https://idp.example/profile/4567",
    "labels": ["hr"]
    }]
  }

Khi muốn cho phép người dùng "hr" đăng nhập, RP có thể chỉ định https://idp.example/hr/fedcm.json configURL trong lệnh gọi navigator.credentials.get():

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

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

  • Nhãn là 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 chỉ định nhãn nào trong configURL, tất cả tài khoản sẽ được hiển thị trong bộ chọn tài khoản FedCM.
  • Nếu không chỉ định nhãn cho một tài khoản, thì tài khoản đó sẽ chỉ xuất hiện trong bộ 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 ở chế độ thụ động (tương tự như tính năng Gợi ý miền), 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 chế độ đang hoạt động, cửa sổ bật lên đăng nhập sẽ được mở trực tiếp.

Ngắt kết nối điểm cuối

Bằng cách gọi IdentityCredential.disconnect(), trình duyệt sẽ gửi một yêu cầu POST trên nhiều nguồn gốc bằng cookie với SameSite=None và loại nội dung là application/x-www-form-urlencoded đến điểm cuối ngắt kết nối này với thông tin sau:

Thuộc tính Mô tả
account_hint Gợi ý cho tài khoản IdP.
client_id Giá trị nhận dạng ứng dụng của RP.
  POST /disconnect.example 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

Sau khi nhận được yêu cầu, máy chủ phải:

  1. Trả lời yêu cầu bằng CORS (Chia sẻ tài nguyên trên nhiều nguồn gốc).
  2. Xác minh rằng yêu cầu chứa tiêu đề HTTP Sec-Fetch-Dest: webidentity.
  3. So khớp tiêu đề Origin với nguồn gốc RP do client_id xác định. Từ chối nếu không khớp.
  4. So khớp account_hint với mã nhận dạng của các tài khoản đã đăng nhập.
  5. Ngắt kết nối tài khoản người dùng khỏi RP.
  6. Phản hồi trình duyệt bằng thông tin tài khoản người dùng đã xác định ở định dạng JSON.

Gói dữ liệu JSON phản hồi mẫu có dạng như sau:

  {
    "account_id": "account456"
  }

Thay vào đó, nếu IdP muốn trình duyệt ngắt kết nối tất cả tài khoản liên kết với RP, hãy truyền một chuỗi không khớp với mã tài khoản nào, ví dụ: "*".

Điểm cuối siêu dữ liệu ứng dụng

Điểm cuối siêu dữ liệu ứng dụng của IdP trả về siêu dữ liệu của bên phụ thuộc, chẳng hạn như chính sách quyền riêng tư, điều khoản dịch vụ và biểu tượng biểu trưng của RP. RP phải cung cấp trước đường liên kết đến chính sách quyền riêng tư và điều khoản dịch vụ của họ cho IdP. Các đường liên kết này sẽ xuất hiện trong hộp thoại đăng nhập khi người dùng chưa đăng ký trên RP với IdP.

Trình duyệt gửi yêu cầu GET bằng client_id navigator.credentials.get mà không cần cookie. Ví dụ:

  GET /client_metadata.example?client_id=1234 HTTP/1.1
  Host: accounts.idp.example
  Origin: https://rp.example/
  Accept: application/json
  Sec-Fetch-Dest: webidentity

Sau khi nhận được yêu cầu, máy chủ phải:

  1. Xác định RP cho client_id.
  2. Trả lời bằng siêu dữ liệu ứng dụng.

Các thuộc tính cho điểm cuối siêu dữ liệu của ứng dụng bao gồm:

Thuộc tính Mô tả
privacy_policy_url (không bắt buộc) URL chính sách quyền riêng tư của RP.
terms_of_service_url (không bắt buộc) URL của điều khoản dịch vụ của RP.
icons (không bắt buộc) Mảng đối tượng, chẳng hạn như [{ "url": "https://rp.example/rp-icon.ico", "size": 40}]

Trình duyệt dự kiến một phản hồi JSON từ điểm cuối:

  {
    "privacy_policy_url": "https://rp.example/privacy_policy.html",
    "terms_of_service_url": "https://rp.example/terms_of_service.html",
    "icons": [{
          "url": "https://rp.example/rp-icon.ico",
          "size": 40
      }]
  }

Trình duyệt sẽ sử dụng siêu dữ liệu ứng dụng được trả về và RP sẽ không có quyền truy cập vào siêu dữ liệu đó.

URL đăng nhập

Điểm cuối này dùng để cho phép người dùng đăng nhập vào IdP.

Với API Trạng thái đăng nhập, IdP phải thông báo trạng thái đăng nhập của người dùng cho trình duyệt. Tuy nhiên, trạng thái có thể không đồng bộ, chẳng hạn như khi phiên hoạt động hết hạn. Trong trường hợp như vậy, trình duyệt có thể cho phép người dùng đăng nhập vào IdP một cách linh động thông qua URL trang đăng nhập được chỉ định bằng login_url của tệp cấu hình idp.

Hộp thoại FedCM hiển thị thông báo đề xuất đăng nhập, như trong hình sau.

A
Hộp thoại FedCM đề xuất đăng nhập vào IdP.

Khi người dùng nhấp vào nút Tiếp tục, trình duyệt sẽ mở một cửa sổ bật lên cho trang đăng nhập của IdP.

Hộp thoại FedCM mẫu.
Một hộp thoại mẫu xuất hiện sau khi nhấp vào nút đăng nhập vào IdP.

Hộp thoại này là một cửa sổ trình duyệt thông thường có cookie của bên thứ nhất. Mọi điều xảy ra trong hộp thoại đều tuỳ thuộc vào IdP và không có tay điều khiển cửa sổ nào để tạo yêu cầu giao tiếp nhiều nguồn gốc đến trang RP. Sau khi người dùng đăng nhập, IdP phải:

  • Gửi tiêu đề Set-Login: logged-in hoặc gọi API navigator.login.setStatus("logged-in") để thông báo cho trình duyệt rằng người dùng đã đăng nhập.
  • Gọi IdentityProvider.close() để đóng hộp thoại.
Người dùng đăng nhập vào một RP sau khi đăng nhập vào IdP bằng FedCM.

Thông báo cho trình duyệt về trạng thái đăng nhập của người dùng

API Trạng thái đăng nhập là một cơ chế trong đó một trang web, đặc biệt là một IdP, thông báo cho trình duyệt về trạng thái đăng nhập của người dùng trên IdP. Với API này, trình duyệt có thể giảm các yêu cầu không cần thiết đến IdP và giảm thiểu các cuộc tấn công theo thời gian tiềm ẩn.

Các IdP có thể báo hiệu trạng thái đăng nhập của người dùng cho trình duyệt bằng cách gửi tiêu đề HTTP hoặc bằng cách gọi API JavaScript khi người dùng đăng nhập vào IdP hoặc khi người dùng đăng xuất khỏi tất cả tài khoản IdP của họ. Đối với mỗi IdP (được xác định bằng URL cấu hình của IdP đó), trình duyệt sẽ giữ một biến ba trạng thái đại diện cho trạng thái đăng nhập với các giá trị có thể có:

  • logged-in
  • logged-out
  • unknown (mặc định)
Trạng thái đăng nhập Nội dung mô tả
logged-in Khi trạng thái đăng nhập của người dùng được đặt thành logged-in, RP gọi FedCM sẽ gửi yêu cầu đến điểm cuối tài khoản của IdP và hiển thị các tài khoản có sẵn cho người dùng trong hộp thoại FedCM.
logged-out Khi trạng thái đăng nhập của người dùng là logged-out, lệnh gọi FedCM sẽ không thành công mà không tạo yêu cầu đến điểm cuối tài khoản của IdP.
unknown (mặc định) Trạng thái unknown được đặt trước khi IdP gửi tín hiệu bằng API Trạng thái đăng nhập. Khi trạng thái là unknown, trình duyệt sẽ gửi yêu cầu đến điểm cuối tài khoản của IdP và cập nhật trạng thái dựa trên phản hồi từ điểm cuối tài khoản.

Để báo hiệu rằng người dùng đã đăng nhập, hãy gửi tiêu đề HTTP Set-Login: logged-in trong một thao tác điều hướng cấp cao nhất hoặc yêu cầu tài nguyên phụ trên cùng một trang web tại nguồn gốc của IdP:

  Set-Login: logged-in

Ngoài ra, hãy gọi phương thức JavaScript navigator.login.setStatus('logged-in') từ nguồn gốc của IdP trong một thao tác điều hướng cấp cao nhất:

  navigator.login.setStatus('logged-in')

Trạng thái đăng nhập của người dùng sẽ được đặt thành logged-in.

Để báo hiệu rằng người dùng đã đăng xuất khỏi tất cả tài khoản của họ, hãy gửi tiêu đề HTTP Set-Login: logged-out trong một thao tác điều hướng cấp cao nhất hoặc yêu cầu tài nguyên phụ trên cùng một trang web tại nguồn của IdP:

  Set-Login: logged-out

Ngoài ra, hãy gọi API JavaScript navigator.login.setStatus('logged-out') từ nguồn gốc của IdP trong một thao tác điều hướng cấp cao nhất:

  navigator.login.setStatus('logged-out')

Trạng thái đăng nhập của người dùng sẽ được đặt thành logged-out.

Trạng thái unknown được đặt trước khi IdP gửi tín hiệu bằng API Trạng thái đăng nhập. Trình duyệt gửi yêu cầu đến điểm cuối tài khoản của IdP và cập nhật trạng thái dựa trên phản hồi từ điểm cuối tài khoản:

  • Nếu điểm cuối trả về danh sách các tài khoản đang hoạt động, hãy cập nhật trạng thái thành logged-in và mở hộp thoại FedCM để hiển thị các tài khoản đó.
  • Nếu điểm cuối không trả về tài khoản nào, hãy cập nhật trạng thái thành logged-out và không thực hiện được lệnh gọi FedCM.

Cho phép người dùng đăng nhập thông qua quy trình đăng nhập động

Mặc dù IdP liên tục thông báo trạng thái đăng nhập của người dùng cho trình duyệt, nhưng trạng thái này có thể không đồng bộ, chẳng hạn như khi phiên hết hạn. Trình duyệt cố gắng gửi yêu cầu thông tin xác thực đến điểm cuối tài khoản khi trạng thái đăng nhập là logged-in, nhưng máy chủ không trả về tài khoản nào vì phiên không còn hoạt động. Trong trường hợp như vậy, trình duyệt có thể tự động cho phép người dùng đăng nhập vào IdP thông qua một cửa sổ bật lên.

Next steps

Implement FedCM for your RPs and distribute the JavaScript SDK. Keep RPs up-to-date by eliminating the need for self-implementation.
Learn how to setup your enviromnemt and debug your implementation.