リレーリング パーティ側で FedCM を使用して ID ソリューションを実装する

信頼できる当事者（RP）は、サイトで FedCM を有効にするために、次の手順を完了する必要があります。

• FedCM エンドポイントが RP のサイトで許可されていることを確認します。
• FedCM JavaScript API を使用してユーザー認証を開始します。
• メタデータ（プライバシー ポリシーや利用規約の URL など）を ID プロバイダに提供します。
• [省略可] UX モードを選択したり、ログインまたはドメイン ヒントを指定したりして、ユーザー エクスペリエンスをカスタマイズします。また、カスタム パラメータを渡したり、特定のユーザー情報をリクエストしたり、カスタム エラー メッセージを指定したりして、ユーザーの再認証方法を選択することもできます。

IdP の構成とエンドポイントが利用可能になると、RP は navigator.credentials.get() を呼び出して、ユーザーが IdP を使用して RP にログインできるようにリクエストできます。

API を呼び出す前に、ユーザーのブラウザで FedCM を使用可能であることを確認する必要があります。FedCM が使用可能かどうかを確認するには、FedCM 実装に次のコードをラップします。

  if ('IdentityCredential' in window) {
    // If the feature is available, take action
  } else {
    // FedCM is not supported, use a different identity solution
  }

ユーザーが FedCM を使用して RP の IdP にログインできるようにするには、RP が navigator.credentials.get() を呼び出します。次に例を示します。

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

コンテキスト プロパティ

オプションの context プロパティを使用すると、RP は FedCM ダイアログ UI の文字列（「rp.example にログイン…」や「idp.example を使用する…」など）を変更して、事前定義された認証コンテキストに対応できます。context プロパティには次の値を指定できます。

• signin（デフォルト）
• signup
• use

たとえば、context を use に設定すると、次のメッセージが表示されます。

カスタマイズされたコンテキスト メッセージを表示する FedCM ダイアログ。

ブラウザは、アカウント リスト エンドポイントからのレスポンスに approved_clients が存在するかどうかに応じて、登録とログインのユースケースを別々に処理します。ユーザーがすでに RP に登録している場合、ブラウザには開示テキスト「... に続行するには」は表示されません。
providers プロパティには、次のプロパティを持つ IdentityProvider オブジェクトの配列を指定します。

Providers プロパティ

providers プロパティは、次のプロパティを持つ IdentityProvider オブジェクトの配列を受け取ります。

アクティブ モード

FedCM は、さまざまな UX モードの構成をサポートしています。パッシブ モードはデフォルト モードであり、デベロッパーが構成する必要はありません。

アクティブ モードで FedCM を使用するには:

1. お客様のブラウザでこの機能が利用可能かどうかを確認します。
2. ボタンのクリックなどの一時的なユーザー ジェスチャーで API を呼び出す。
3. mode パラメータを API 呼び出しに渡します。

  let supportsFedCmMode = false;
  try {
    navigator.credentials.get({
      identity: Object.defineProperty(
        // Check if this Chrome version supports the Mode API.
        {}, 'mode', {
          get: function () { supportsFedCmMode = true; }
        }
      )
    });
  } catch(e) {}

  if (supportsFedCmMode) {
    // The button mode is supported. Call the API with mode property:
    return await navigator.credentials.get({
      identity: {
        providers: [{
          configURL: 'https://idp.example/config.json',
          clientId: '123',
        }],
        // The 'mode' value defines the UX mode of FedCM.
        // - 'active': Must be initiated by user interaction (e.g., clicking a button).
        // - 'passive': Can be initiated without direct user interaction.
        mode: 'active'
      }
    });
  }

アクティブ モードのカスタム アイコン

アクティブ モードでは、IdP は RP の公式ロゴアイコンを クライアント メタデータ エンドポイント レスポンスに直接含めることができます。RP は、ブランディング データを事前に提供する必要があります。

クロスオリジンの iframe 内から FedCM を呼び出す

親フレームが許可している場合、identity-credentials-get 権限ポリシーを使用して、クロスオリジン iframe 内から FedCM を呼び出すことができます。そのためには、次のように iframe タグに allow="identity-credentials-get" 属性を追加します。

  <iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>

動作はこちらの例で確認できます。

必要に応じて、親フレームが FedCM を呼び出すオリジンを制限する場合は、許可されたオリジンのリストを含む Permissions-Policy ヘッダーを送信します。

  Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")

権限ポリシーの仕組みについて詳しくは、権限ポリシーによるブラウザ機能の制御をご覧ください。

Login Hint API

RP はログイン ヒントを使用して、ユーザーがログインするアカウントを推奨できます。これは、以前に使用したアカウントがわからないユーザーの再認証に役立ちます。

RP は、次のコードサンプルに示すように、アカウント リスト エンドポイントから取得した login_hints 値のいずれかを使用して loginHint プロパティで navigator.credentials.get() を呼び出すことで、特定のアカウントを選択的に表示できます。

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: '123',
        // Accounts endpoint can specify a 'login_hints' array for an account.
        // When RP specifies a 'exampleHint' value, only those accounts will be
        // shown to the user whose 'login_hints' array contains the 'exampleHint'
        // value
        loginHint : 'exampleHint'
      }]
    }
  });

loginHint に一致するアカウントがない場合、FedCM ダイアログにログイン プロンプトが表示されます。これにより、ユーザーは RP からリクエストされたヒントに一致する IdP アカウントにログインできます。ユーザーがプロンプトをタップすると、構成ファイルで指定されたログイン URL を含むポップアップ ウィンドウが開きます。リンクには、ログイン ヒントとドメイン ヒントのクエリ パラメータが追加されます。

Domain Hint API

RP は、特定のドメインに関連付けられているアカウントのみを選択して表示できます。これは、企業ドメインに制限されている RP に役立ちます。

特定のドメイン アカウントのみを表示するには、次のコードサンプルに示すように、アカウント リスト エンドポイントから取得した domain_hints 値のいずれかを使用して、domainHint プロパティで navigator.credentials.get() を呼び出す必要があります。

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/manifest.json',
        clientId: 'abc',
        // Accounts endpoint can specify a 'domain_hints' array for an account.
        // When RP specifies a '@domain.example' value, only those accounts will be
        // shown to the user whose 'domain_hints' array contains the
        // '@domain.example' value
        domainHint : '@domain.example'
      }]
    }
  });

domainHint に一致するアカウントがない場合、FedCM ダイアログにログイン プロンプトが表示されます。これにより、ユーザーは RP からリクエストされたヒントに一致する IdP アカウントにログインできます。ユーザーがプロンプトをタップすると、構成ファイルで指定されたログイン URL を含むポップアップ ウィンドウが開きます。リンクには、ログイン ヒントとドメイン ヒントのクエリ パラメータが追加されます。

カスタム パラメータ

カスタム パラメータ機能を使用すると、RP はID アサーション エンドポイントに追加の Key-Value パラメータを指定できます。Parameters API を使用すると、RP は IdP に追加のパラメータを渡して、基本的なログイン以外のリソースの権限をリクエストできます。追加のパラメータを渡すことは、次のような場合に役立ちます。

• RP は、請求先住所やカレンダーへのアクセスなど、IdP が持つ追加の権限を動的にリクエストする必要があります。ユーザーは、「このまま続行」機能を使用して開始される IdP が管理する UX フローを通じてこれらの権限を承認できます。IdP は、この情報を共有します。

API を使用するには、RP は 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'
        }
      },
    }
  });

ブラウザは、これを IdP への POST リクエストに変換し、パラメータを 1 つの URL エンコードされた JSON シリアル化オブジェクトとして指定します。

  // The assertion endpoint is drawn from the config file
  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

  // params are translated into urlencoded version of `{"IDP_SPECIFIC_PARAM":"1","foo":"bar"}`
  account_id=123&client_id=client1234&params=%22%7B%5C%22IDP_SPECIFIC_PARAM%5C%22%3A1%2C%5C%22foo%5C%22%3A%5C%22BAR%5C%22%7D%22.

RP に追加の権限が必要な場合は、IdP がリダイレクト リンクを提供できます。たとえば、node.js では次のようになります。

  if (rpRequestsPermissions) {
    // Response with a URL if the RP requests additional permissions
    return res.json({
      continue_on: '/example-redirect',
    });
  }

フィールド

RP は、IdP から共有してもらう必要があるユーザー情報（名前、メールアドレス、プロフィール写真の組み合わせ）を指定できます。リクエストされた情報は、FedCM ダイアログの情報開示 UI に表示されます。ユーザーがログインを選択すると、idp.example がリクエストされた情報を rp.example と共有することを通知するメッセージが表示されます。

フィールド機能を使用するには、RP は navigator.credentials.get() 呼び出しに fields 配列を追加する必要があります。フィールドには、name、email、picture の任意の組み合わせを含めることができます。今後、この値を拡張して、より多くの値を含める予定です。fields を含むリクエストは次のようになります。

  let { token } = await navigator.credentials.get({
    identity: {
      providers: [{
        // RP requests the IdP to share only user email and profile picture
        fields: [ 'email', 'picture'],
        clientId: '1234',
        configURL: 'https://idp.example/fedcm.json',

      },
    }
  });

ブラウザは、RP が指定した fields パラメータと、ブラウザがユーザーに開示したフィールドを disclosure_shown_for パラメータに含む、ID アサーション エンドポイントへの HTTP リクエストに自動的に変換します。下位互換性を確保するため、開示テキストが表示され、リクエストされたフィールドに 'name'、'email'、'picture' の3 つのフィールドすべてが含まれている場合、ブラウザは disclosure_text_shown=true も送信します。

  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

  // The RP only requested to share email and picture. The browser will send `disclosure_text_shown=false`, as the 'name' field value is missing
  account_id=123&client_id=client1234&disclosure_text_shown=false&fields=email,picture&disclosure_shown_for=email,picture

fields が空の配列の場合、ユーザー エージェントは開示 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

エラー メッセージを表示する

クライアントが認証されていない場合や、サーバーが一時的に使用できない場合など、正当な理由で IdP がトークンを発行できないことがあります。IdP が「error」レスポンスを返した場合、RP はそれをキャッチできます。Chrome は、IdP から提供されたエラー情報を含むブラウザ UI を表示して、ユーザーに通知できます。

  try {
    const cred = await navigator.credentials.get({
      identity: {
        providers: [
          {
            configURL: 'https://idp.example/manifest.json',
            clientId: '1234',
          },
        ],
      }
    });
  } catch (e) {
    const code = e.code;
    const url = e.url;
  }

初回認証後にユーザーを自動的に再認証する

FedCM の自動再認証（略称「auto-reauthn」）を使用すると、ユーザーは FedCM を使用して初回認証後に再びアクセスしたときに、自動的に再認証できます。ここでの「最初の認証」とは、ユーザーが同じブラウザ インスタンスで FedCM のログイン ダイアログの [Continue as...] ボタンを初めてタップして、アカウントを作成するか、RP のウェブサイトにログインすることを意味します。

明示的なユーザー エクスペリエンスは、ユーザーがトラッキングを防止するために連携アカウントを作成する前に行うことは理にかなっています（これは FedCM の主な目標の一つです）。しかし、ユーザーが一度行った後で再度行うことは、不必要に煩雑です。ユーザーが RP と IdP 間の通信を許可する権限を付与した後で、すでに承認済みの事項について、ユーザーに再度明示的に確認を求めることにプライバシーやセキュリティ上のメリットはありません。

自動再認証では、navigator.credentials.get() を呼び出すときに mediation に指定したオプションに応じてブラウザの動作が変更されます。

  const cred = await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: 'https://idp.example/fedcm.json',
        clientId: '1234',
      }],
    },
    mediation: 'optional', // this is the default
  });

  // `isAutoSelected` is `true` if auto-reauthn was performed.
  const isAutoSelected = cred.isAutoSelected;

mediation は 認証情報管理 API のプロパティであり、PasswordCredential や FederatedCredential と同じように動作します。また、PublicKeyCredential でも部分的にサポートされています。このプロパティには、次の 4 つの値を指定できます。

• 'optional'（デフォルト）: 可能であれば自動再認証、可能でない場合仲裁が必要です。ログインページでこのオプションを選択することをおすすめします。
• 'required': 続行するには常にメディエーションを必要とします（UI の [続行] ボタンをクリックするなど）。ユーザーが認証が必要なたびに明示的に権限を付与することが想定される場合は、このオプションを選択します。
• 'silent': 可能であれば自動再認証を行い、できない場合は仲裁を必要とせずにサイレント エラーを返します。このオプションは、専用のログインページ以外のページで、ユーザーのログインを維持したい場合に選択することをおすすめします。たとえば、配送ウェブサイトの商品ページやニュース ウェブサイトの記事ページなどです。
• 'conditional': WebAuthn に使用されます。現在のところ、FedCM では使用できません。

この呼び出しでは、次の条件で自動再認証が行われます。

• FedCM を使用できます。たとえば、ユーザーが FedCM をグローバルに無効にしていないか、設定で RP に対して無効にしていない場合です。
• ユーザーは、このブラウザでウェブサイトにログインするために、FedCM API で 1 つのアカウントのみを使用しました。
• ユーザーがそのアカウントで IdP にログインしている。
• 過去 10 分以内に自動再認証が行われていない。
• RP が前回のログイン後に navigator.credentials.preventSilentAccess() を呼び出していない。

これらの条件が満たされると、FedCM navigator.credentials.get() が呼び出されるとすぐに、ユーザーの自動再認証が試行されます。

mediation: optional の場合、ブラウザにのみ知られている理由により、自動再認証が利用できない場合があります。RP は、isAutoSelected プロパティを調べて、自動再認証が実行されているかどうかを確認できます。

これは、API のパフォーマンスを評価し、それに応じて UX を改善するのに役立ちます。また、利用できない場合は、明示的なユーザー メディエーション（mediation: required を含むフロー）でログインするよう求めるメッセージが表示されることがあります。

preventSilentAccess() でメディエーションを適用する

ログアウト直後にユーザーの再認証を自動的に行うと、ユーザー エクスペリエンスが損なわれます。そのため、FedCM では、この動作を防ぐために、自動再認証後に 10 分間の無効期間があります。つまり、ユーザーが 10 分以内に再度ログインしない限り、自動再認証は 10 分ごとに最大 1 回実行されます。RP は、ユーザーが RP から明示的にログアウトしたときに（ログアウト ボタンをクリックするなど）、自動再認証を無効にするようブラウザに明示的にリクエストするために navigator.credentials.preventSilentAccess() を呼び出す必要があります。

  function signout() {
    navigator.credentials.preventSilentAccess();
    location.href = '/signout';
  }

ユーザーは設定で自動再認証をオプトアウトできます

ユーザーは、設定メニューから自動再認証をオプトアウトできます。

• パソコン版 Chrome で、[chrome://password-manager/settings] > [自動的にログイン] に移動します。
• Android Chrome で、[設定] > [パスワード マネージャー] > 右上にある歯車アイコン > [自動ログイン] を開きます。

切り替えボタンを無効にすると、ユーザーは自動再認証動作を完全にオプトアウトできます。この設定は、ユーザーが Chrome インスタンスで Google アカウントにログインしていて、同期が有効になっている場合に、デバイス間で保存および同期されます。

IdP と RP の接続を解除する

ユーザーが FedCM を介して IdP を使用して RP にログインしたことがある場合、その関係は、接続済みアカウントのリストとしてローカルでブラウザに記憶されます。RP は、IdentityCredential.disconnect() 関数を呼び出して切断を開始する場合があります。この関数は、最上位の RP フレームから呼び出すことができます。RP は、configURL、IdP で使用する clientId、IdP の接続を切断するための accountHint を渡す必要があります。アカウントのヒントは、アカウントを識別できる限り任意の文字列にできます。たとえば、アカウントリスト エンドポイントが提供するアカウント ID と必ずしも一致しないメールアドレスやユーザー ID などです。

  // Disconnect an IdP account 'account456' from the RP 'https://idp.com/'. This is invoked on the RP domain.
  IdentityCredential.disconnect({
    configURL: 'https://idp.com/config.json',
    clientId: 'rp123',
    accountHint: 'account456'
  });

IdentityCredential.disconnect() は Promise を返します。このプロミスは、次の理由で例外をスローすることがあります。

• ユーザーが FedCM 経由で IdP を使用して RP にログインしていない。
• API が FedCM 権限ポリシーのない iframe 内から呼び出されている。
• configURL が無効であるか、切断エンドポイントがありません。
• コンテンツ セキュリティ ポリシー（CSP）チェックが失敗します。
• 保留中の切断リクエストがあります。
• ユーザーがブラウザの設定で FedCM を無効にしている。

IdP の切断エンドポイントがレスポンスを返すと、ブラウザで RP と IdP の接続が切断され、Promise が解決されます。接続解除されたアカウントの ID は、接続解除エンドポイントからのレスポンスで指定されます。

次のステップ