このページは Cloud Translation API によって翻訳されました。

FedCM の更新: Continuation API バンドルのオリジントライアルと Storage Access API の自動付与

Eiji Kitamura

Chrome 126 以降、デベロッパーは一部の承認ユースケースを有効にするデスクトップ Federated Credential Management API（FedCM）機能のバンドルのオリジントライアルを開始できます。このバンドルは Continuation API と Parameters API で構成されます。これらの API は、ID プロバイダ（IdP）が提供する権限ダイアログで OAuth 認証フローに似たエクスペリエンスを実現します。このバンドルには、Fields API、複数の configURL、カスタムアカウントラベルなど、その他の変更も含まれています。Chrome 126 以降では、Storage Access API（SAA）のオリジントライアルも導入しています。これは、ユーザーが過去に FedCM を使用して正常にログインした場合に SAA リクエストを自動的に付与するものです。

オリジントライアル: FedCM Continuation API バンドル

FedCM Continuation API バンドルは、複数の FedCM 拡張機能で構成されています。

Continuation API
Parameters API
Fields API
複数の configURL
カスタムアカウントラベル

Continuation API

ユーザーが RP にログインしてから、ボタンモードで承認します。

Glitch で API を使用するデモをご覧いただけます。

Continuation API を使用すると、IdP の ID アサーションエンドポイントは必要に応じて FedCM がレンダリングする URL を返し、ユーザーがマルチステップのログインフローを続行できるようになります。これにより、IdP は、既存の FedCM UI で可能な以上の権限（ユーザーのサーバーサイドリソースへのアクセスなど）をリライングパーティ（RP）に付与するようユーザーにリクエストできます。

通常、ID アサーションエンドポイントは認証に必要なトークンを返します。

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

これに対して Continuation API では、ID アサーションエンドポイントは、ID アサーションエンドポイントへの絶対パスまたは相対パスを含む continue_on プロパティを返すことができます。

{
  // 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 が「ユーザーの切り替え」機能を提供している場合や、委任の場合）、Resolve の呼び出しは、次のようなオプションの 2 番目の引数を取ります。

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

パラメータ API

Parameters API を使用すると、RP は ID アサーションエンドポイントに追加のパラメータを提供できます。Parameters API を使用すると、RP は追加のパラメータを IdP に渡して、基本的なログイン以外のリソースの権限をリクエストできます。ユーザーは、Continuation API を介して開始される IdP 制御の UX フローを通じてこれらの権限を承認します。

API を使用するには、navigator.credentials.get() 呼び出しのオブジェクトとして params プロパティにパラメータを追加します。

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' として含まれています。これは、リクエストの HTTP 本文で param_IDP_SPECIFIC_PARAM=1&param_foo=BAR&param_ETC=MOAR&param_scope=calendar.readonly%20photos.write に変換されます。

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 で次の操作を行うことができます。

IdP が認識できる必須パラメータ（scope など）を使用して navigator.credentials.get() を呼び出します。
ID アサーションエンドポイントは、ユーザーがすでにログインしていることを確認し、continue_on URL を返します。
ブラウザでポップアップウィンドウが開き、IdP の権限ページで、リクエストされたスコープに一致する追加の権限を求めるメッセージが表示されます。
IdP によって IdentityProvider.resolve() を介して認可されると、ウィンドウは閉じ、RP の元の navigator.credentials.get() 呼び出しが関連トークンまたは認証コードを取得し、RP が適切なアクセストークンと交換できるようになります。

フィールド API

Fields API を使用すると、RP が IdP にリクエストするアカウント属性を宣言できます。これにより、ブラウザは FedCM ダイアログに適切な開示 UI をレンダリングできます。返されるトークンにリクエストされたフィールドを含めるのは IdP の責任です。OpenID Connect では「基本的なプロファイル」をリクエストする場合と、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',
});

ID アサーションエンドポイントへの HTTP リクエストには、RP で指定された fields パラメータが含まれます。リピーターでない場合は 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

IdP からの追加データ（カレンダーへのアクセスなど）に RP がアクセスする必要がある場合は、前述のカスタムパラメータを使用して処理する必要があります。IdP は continue_on URL を返して権限をリクエストします。

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 に空の配列を指定した場合、ユーザーエージェントは開示 UI をスキップします。

ウィジェットモードでは開示メッセージは表示されません。ボタンフローでは、開示 UI は完全にスキップされます。 — ウィジェットモードでは開示メッセージが表示されません。ボタンフローでは、開示 UI は完全にスキップされます。

これは、アカウントエンドポイントからのレスポンスに、approved_clients の RP と一致するクライアント ID が含まれていない場合でも同様です。

この場合、ID アサーションエンドポイントに送信される disclosure_text_shown は、HTTP 本文で false になります。

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 は構成ファイルと同じ well-known ファイルで accounts_endpoint と login_url を指定することで、IdP の複数の構成ファイルに対応できます。

accounts_endpoint と login_url が well-known ファイルに追加されると、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 実装は同じままでかまいません。

カスタムアカウントラベル

カスタムアカウントラベルを使用すると、FedCM IdP でアカウントにアノテーションを付けることができ、構成ファイルでラベルを指定して RP がアカウントをフィルタリングできるようになります。Domain Hints API や Login Hint API を使用して navigator.credentials.get() 呼び出しで指定することで同様のフィルタリングを行うこともできますが、カスタムアカウントラベルでは、構成ファイルを指定することでユーザーをフィルタできます。これは、複数の configURL を使用する場合に特に有用です。カスタムアカウントラベルは、ログインやドメインヒントなど、RP からではなく IdP サーバーから提供される点も異なります。

例

IdP は、コンシューマ用とエンタープライズ用にそれぞれ 2 つの configURL をサポートしています。コンシューマ構成ファイルには 'consumer' ラベルがあり、エンタープライズ構成ファイルには 'enterprise' ラベルがあります。

このような設定では、well-known ファイルに 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 が well-known ファイルで指定されている場合、provider_urls は無視されます。RP は、navigator.credentials.get() 呼び出しでそれぞれの構成ファイルを直接参照できます。

コンシューマの構成ファイルは https://idp.example/fedcm.json にあり、include を使用して 'consumer' を指定する accounts プロパティが含まれています。

{
  "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 にあります。これには、include を使用して 'enterprise' を指定する accounts プロパティが含まれています。

{
  "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 が割り当てられたラベルプロパティを含むアカウントのリストを返します。以下は、2 つのアカウントを持つユーザーに対するレスポンスの例です。1 つは一般ユーザー向け、もう 1 つはエンタープライズ向けです。

{
 "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' ユーザーにログインを許可する場合、navigator.credentials.get() 呼び出しで 'enterprise' configURL 'https://idp.example/enterprise/fedcm.json' を指定できます。

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

そのため、ユーザーがログインに使用できるのはアカウント ID '4567' のみです。アカウント ID '123' はブラウザによって通知なく非表示になるため、このサイトの IdP でサポートされていないアカウントがユーザーに提供されることはありません。

注:

ラベルは文字列です。labels 配列または include フィールドに文字列以外の値が含まれている場合は無視されます。
configURL でラベルが指定されていない場合、すべてのアカウントが FedCM Account Chooser に表示されます。
アカウントにラベルが指定されていない場合、configURL でもラベルが指定されていない場合にのみ、アカウント選択ツールに表示されます。
ウィジェットフローでリクエストされたラベルに一致するアカウントがない場合（Domain Hint API と同様）、FedCM ダイアログにログインプロンプトが表示され、ユーザーは IdP アカウントにログインできます。ボタンフローでは、ログインポップアップウィンドウが直接開きます。

オリジントライアル: Storage Access API のトラストシグナルとしての FedCM

Chrome 126 では、Storage Access API のトラストシグナルとしての FedCM のオリジントライアルが開始されます。この変更により、FedCM による事前の付与が、Storage Access API によるストレージアクセスリクエストを自動的に承認する正当な理由になります。

これは、埋め込み iframe がパーソナライズされたリソースにアクセスする必要がある場合に役立ちます。たとえば、idp.example が rp.example に埋め込まれていて、パーソナライズされたリソースを表示する必要がある場合です。ブラウザがサードパーティ Cookie へのアクセスを制限している場合、ユーザーが FedCM で idp.example を使用して rp.example にログインしていても、埋め込まれた idp.example iframe はパーソナライズされたリソースをリクエストできません（リクエストにサードパーティ Cookie は含まれないため）。

これを実現するには、idp.example はウェブサイトに埋め込まれた iframe を介してストレージアクセス権限を取得する必要があります。これは、権限プロンプトからのみ取得できます。

FedCM を Storage Access API のトラストシグナルとして使用すると、Storage Access 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 126 以降で Chrome フラグ chrome://flags#fedcm-authz を有効にすると、FedCM Continuation API バンドルをローカルで試すことができます。Chrome 126 以降で #fedcm-with-storage-access-api を有効にして、FedCM を Storage Access API のトラストシグナルとしてローカルで試すこともできます。

これらの機能はオリジントライアルとしても利用できます。オリジントライアルでは、新機能を試して、ユーザビリティ、実用性、有効性に関するフィードバックを提供できます。詳しくは、オリジントライアルのスタートガイドをご覧ください。

FedCM Continuation API バンドルのオリジントライアルを試すには、2 つのオリジントライアルトークンを作成します。

トライアルに登録します。トークンを IdP の送信元に埋め込みます。
サードパーティマッチングのチェックボックスをオンにしてオリジントライアルを登録します。RP にサードパーティのオリジントライアルを登録するの手順に沿って、RP のトークンを埋め込みます。

ボタンフローとともに Continuation API を有効にする場合は、Button Mode API オリジントライアルも有効にします。

サードパーティとしてオリジントライアルに登録する。RP にサードパーティのオリジントライアルを登録するの手順に沿って、RP のトークンを埋め込みます。

Storage Access API オリジントライアルでトラストシグナルとして FedCM を使用するには:

オリジントライアルに登録します。トークンを IdP の送信元に埋め込みます。

Continuation API バンドルのオリジントライアルと、Storage Access API のオリジントライアルのトラストシグナルとしての FedCM は、Chrome 126 以降で利用できます。

RP にサードパーティのオリジントライアルを登録する

オリジントライアルの登録ページに移動します。
[Register] ボタンをクリックし、フォームに記入してトークンをリクエストします。
IdP の生成元を [ウェブ生成元] として入力します。
他のオリジンで JavaScript を使用してトークンを挿入する場合は、[サードパーティマッチング] チェックボックスをオンにします。
[送信] をクリックします。
発行されたトークンをサードパーティのウェブサイトに埋め込みます。

サードパーティのウェブサイトにトークンを埋め込むには、IdP の送信元から提供される IdP の JavaScript ライブラリまたは SDK に次のコードを追加します。

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

TOKEN_GOES_HERE は、独自のトークンに置き換えます。

FedCM の更新: Continuation API バンドルのオリジン トライアルと Storage Access API の自動付与

オリジン トライアル: FedCM Continuation API バンドル