PublicKeyCredential: parseRequestOptionsFromJSON() 静的メソッド

構文

PublicKeyCredential.parseRequestOptionsFromJSON(options)

引数

options

PublicKeyCredentialRequestOptions インスタンスと同じ構造を持つオブジェクトですが、バッファーのプロパティの代わりに base64url でエンコードされた文字列が使用されているものです。

返値

PublicKeyCredentialRequestOptions インスタンスです。

例外

EncodingError DOMException

options オブジェクトのどの部分も PublicKeyCredentialCreationOptions インスタンスに変換できない場合。

SecurityError DOMException

RP のドメインが有効ではありません。

解説

（登録済みの）ユーザーの認証を行うウェブ認証プロセスでは、認証依頼者のサーバーが、既存の資格情報を探すために必要なウェブアプリ情報を送信します。この情報には、ユーザーの ID、認証依頼者、および「チャレンジ」に関する詳細が含まれ、必要に応じて資格情報の検索先も指定されます。例えば、ローカルの組み込み認証器や、USB、BLE などを介した外部の認証器などです。といった具合に。

ウェブアプリは、navigator.credentials.get() を、サーバーから提供されたデータ含むを PublicKeyCredentialRequestOptions インスタンスを引数として渡して呼び出すことで、この情報を認証器に渡して資格情報を探します。

仕様書では、資格情報のリクエストに必要な情報の送信方法については定義されていません。 便利な手法として、サーバーが、その構造を反映しつつ、challenge や user.id などのバッファープロパティを base64url 文字列としてエンコード方式でエンコードした、PublicKeyCredentialRequestOptions インスタンスの JSON 形式の表現に情報をカプセル化する方法があります。 このオブジェクトは、JSON 文字列にシリアライズしてウェブアプリに送信し、そこでシリアライズ解除後、PublicKeyCredentialRequestOptions インスタンスに parseRequestOptionsFromJSON() で変換することができます。

例

すでに登録済みのユーザーを認証する際、認証依頼者のサーバーは、リクエストされた資格情報、認証依頼者、およびチャレンジに関する情報をウェブアプリに提供します。 下記コードでは、上記の options 引数で説明されている形式で、この情報を定義しています。

const requestCredentialOptionsJSON = {
  challenge: new Uint8Array([139, 66, 181, 87, 7, 203 /* … */]),
  rpId: "acme.com",
  allowCredentials: [
    {
      type: "public-key",
      id: new Uint8Array([64, 66, 25, 78, 168, 226, 174 /* … */]),
    },
  ],
  userVerification: "required",
};

このオブジェクトは JSON データ型のみを使用しているため、JSON.stringify() を使用して JSON にシリアライズし、ウェブアプリに送信することができます。

JSON.stringify(requestCredentialOptionsJSON);

このウェブアプリは、JSON 文字列を createCredentialOptionsJSON オブジェクト（図示なし）にシリアライズ解除することができます。 parseCreationOptionsFromJSON() メソッドは、そのオブジェクトを navigator.credentials.create() で使用できる形式に変換するために使用されます。

// オプションを get() で使用される形式に変換
const publicKey = PublicKeyCredential.parseRequestOptionsFromJSON(
  requestCredentialOptionsJSON, // JSON 形式の表現
);

navigator.credentials
  .get({ publicKey })
  .then((returnedCredentialInfo) => {
    // 返された資格情報をここで処理
  })
  .catch((err) => {
    console.error(err);
  });

仕様書

ブラウザーの互換性

関連情報

• ウェブ認証 API
• PublicKeyCredential.parseCreationOptionsFromJSON()