get() はCredentialsContainer インターフェイスのメソッドで、単一の資格情報で解決するPromise を返します。この認証情報は、ユーザーをウェブサイトに認証するために使用できます。

このメソッドは単一のオプション引数options を受け付けます。これには以下のものを含めることができます。

• mediation プロパティは、ユーザーに操作への参加を求める方法と可否を示します。これは例えば、保存された認証情報を使用して、サイトがユーザーをサイレントにログインさせられるかどうかを制御します。
• signal プロパティは、AbortController を使用して操作をキャンセルすることができます。
• 1 つ以上のプロパティ —password、federated、identity、otp、publicKey — が、リクエストされた資格情報の種類を示します。設定されている場合、これらのプロパティの値には、リクエストされた種類の適切な資格情報を見つけるためにブラウザーが必要とする引数を含みます。

APIは常に単一の資格情報またはnullで履行される。複数の資格情報が利用できる状態で、ユーザーによる選択ができる場合、ブラウザはユーザーに単一の資格情報を選択するよう依頼する。

構文

get()get(options)

引数

options省略可

リクエストに対するオプションが含まれているオブジェクト。以下のプロパティを含むことができます。

mediation省略可

文字列で、クライアントアプリへアクセスするごとにユーザーがログインを要求されるかどうかを示します。値は次のいずれかです。

"conditional"

検出された資格情報は、資格情報をリクエストしているオリジンとともに、モーダルでないダイアログボックスでユーザーに示されます。実際には、このことは資格情報の自動入力（オートフィル）が利用できるということです。この機能の詳細な使用方法については、Sign in with a passkey through form autofill を参照してください。PublicKeyCredential.isConditionalMediationAvailable() も同時に有益な情報を提供します。

"optional"

その操作において、ユーザー介入なしで資格情報を引き渡すことが可能である場合、ユーザー介入なしの自動再認証が可能となります。ユーザー介入が必要な場合、ユーザーエージェントはユーザーに認証を依頼します。この値は、ユーザーがログインダイアログボックスを目にして驚いたり混乱したりしないという合理的な確信が持てる状況を意図しています。例えば、自動的にユーザーがログインしないサイトで、ユーザーが「ログイン/サインアップ」ボタンをクリックした直後などが該当します。

"required"

ユーザーには常に認証が要求されます。この値は、ユーザー認証を強制したい状況、例えば、（クレジットカード決済の確認など）機密性の高い操作実行時やユーザー切り替え時に再認証を要求する場合を意図しています。

"silent"

ユーザーには認証を依頼されません。ユーザーエージェントは、できる限り自動的にユーザーを再認証してログインします。同意が必要な場合、プロミスはnull で履行される。この値は、ウェブアプリ訪問時に、できる限り自動的にユーザーをログインできる場合に自動的にログインするよう意図しており、それができない場合は混乱を招くログインダイアログを表示しないようするためのものです。代わりに、ユーザーが明示的に「ログイン/サインアップ」ボタンをクリックするのを待つことが望ましい場合です。

既定値は"optional" です。

メモ:連合認証 (FedCM API) リクエストにおいて、mediation の値がoptional またはsilent である場合、自動再認証が試行されることがあります。これが発生するか否かは、検証中に IdP のid_assertion_endpoint に送信されるis_auto_selected 引数によって伝えられ、IdentityCredential.isAutoSelected プロパティによって認証依頼者 (RP) に伝えられます。これは、パフォーマンス評価、セキュリティ要件（IdP が自動再認証要求を拒否し、常にユーザーの介入を必要としたい場合）、および一般的な UX（IdP またはRP が自動ログインと非自動ログインの体験に対して異なる UX を表示したい場合）に有益です。

signal省略可

進行中のget() 操作を中止できるAbortSignal オブジェクトインスタンス。中止される操作は、通常通り完了する場合（一般的に操作完了後に中止信号を受信した場合）と、AbortErrorDOMException で拒否されることがあります。

password省略可

このオプションは、ブラウザーに保存されているパスワードをPasswordCredential オブジェクトとして取得するよう依頼します。論理値です。

identity省略可

このオプションは、連合アイデンティティ資格情報 をIdentityCredential オブジェクトとして取得するようブラウザーに依頼します。これには連合資格情報管理 API を使用します。

このオプションの値は、ウェブサイトが使用する特定の ID プロバイダーの詳細が含まれているIdentityCredentialRequestOptions オブジェクトです。

federated省略可

このオプションは、ブラウザーに連合アイデンティティ資格情報 をFederatedCredential オブジェクトとして取得するよう依頼します。このインターフェイスはすでに廃止されており、利用できる場合はidentity オプションの使用を推奨します。

このオプションの値は、次のプロパティが設定されたオブジェクトです。

protocols

リクエストされた資格情報の連合 ID プロバイダーのプロトコルを表す文字列の配列（"openidconnect" など）。

providers

連合 ID プロバイダーを表す文字列の配列（例えば"https://www.facebook.com" や"https://accounts.google.com"）。

otp省略可

このオプションは、ブラウザーにワンタイムパスワード (OTP) をOTPCredential オブジェクトとして取得するよう依頼します。

このオプションの値は文字列の配列であり、文字列値"sms" のみが含まれていることがあります。

publicKey省略可

このオプションは、ブラウザーにウェブ認証 API を使用して署名されたアサーションをPublicKeyCredential として取得するよう要求します。

このオプションの値はPublicKeyCredentialRequestOptions オブジェクトです。

返値

Promise で、以下のいずれかのCredential のサブクラスで解決します。

• PasswordCredential
• IdentityCredential
• FederatedCredential
• OTPCredential
• PublicKeyCredential

get() 呼び出しで条件付き仲介が指定された場合、ブラウザーの UI ダイアログを表示させて、利用可能な自動入力候補からユーザーがログイン用アカウントを選択するまでプロミスを待機中にします。

• ユーザーがブラウザ UI ダイアログの外でジェスチャーを行った場合、そのダイアログはプロミスが解決または拒否されず、ユーザーに表示されるエラー状態を発生させることなく閉じられます。
• ユーザーが資格情報を選択した場合、関連するPublicKeyCredential が呼び出し側に返されます。

単一の資格情報が明確な形で取得できない場合、プロミスはnull で解決されます。

例外

AbortErrorDOMException

このメソッドのsignal オプションに関連付けられたAbortController のabort() メソッドの呼び出しにより、リクエストは中止された。

IdentityCredentialError

IdentityCredential をリクエストされた際、ID アサーションエンドポイントへのリクエストが認証を検証できず、理由に関する情報が含まれているエラーレスポンスで拒否された。

NetworkErrorDOMException

IdentityCredential をリクエストした際、ID プロバイダー (IdP) が 60 秒以内に応答しなかった、提供された資格情報が無効/見つからなかった、またはブラウザーの IdP ログイン状態が"logged-out" に設定されていた（FedCM ログイン状態の詳細についてはログイン状態 API を使用したログイン状態の更新を参照）。後者の場合、 IdP のログイン状態が RP に漏洩することを防ぐため、拒否処理に遅延が生じる可能性があります。

NotAllowedErrorDOMException

以下の状況のいずれかで発生します。

• ユーザーがリクエストを中止した。

• この API の使用が、以下の権限ポリシーのいずれかによってブロックされた。

  • identity-credentials-get
  • publickey-credentials-get
  • otp-credentials

• 呼び出し元のオリジンが不透明オリジンであった。

SecurityErrorDOMException

呼び出し元のドメインが、有効なドメインではない。

例

連合アイデンティティ資格情報を受け取る

認証依頼者は、identity オプション付きでget() を呼び出すことで、アイデンティティ連携を利用して、ユーザーが ID プロバイダー (IdP) 経由で認証依頼者にログインするよう要求できます。典型的なリクエストは次のようになります。

async function signIn() {  const identityCredential = await navigator.credentials.get({    identity: {      providers: [        {          configURL: "https://accounts.idp.example/config.json",          clientId: "********",          nonce: "******",        },      ],    },  });}

詳細については、連合資格情報管理 (FedCM) API を参照してください。この呼び出しにより、FedCM ログインフローで説明されているログインフローが開始されます。

contextおよびloginHint拡張機能を含む同様の呼び出しは、次のようになります。

async function signIn() {  const identityCredential = await navigator.credentials.get({    identity: {      context: "signup",      providers: [        {          configURL: "https://accounts.idp.example/config.json",          clientId: "********",          nonce: "******",          loginHint: "user1@example.com",        },      ],    },  });}

ID プロバイダーがID アサーションエンドポイントへのリクエストを検証できない場合、CredentialsContainer.get() から返されるプロミスが拒否されます。

async function signIn() {  try {    const identityCredential = await navigator.credentials.get({      identity: {        providers: [          {            configURL: "https://accounts.idp.example/config.json",            clientId: "********",            nonce: "******",          },        ],      },    });  } catch (e) {    // Handle the error in some way, for example provide information    // to help the user succeed in a future sign-in attempt    console.error(e);  }}

公開鍵資格情報の取得

以下のスニペットは、 WebAuthn のpublicKey オプションを使用した典型的なget() 呼び出しを示しています。

const publicKey = {  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",};navigator.credentials.get({ publicKey });

get() の呼び出しが成功すると、WebAuthn のcreate() によって事前に作成され、ユーザーの認証に使用された公開鍵認証情報を表すPublicKeyCredential オブジェクトインスタンスで解決するプロミスが返されます。そのPublicKeyCredential.response プロパティには、認証器データ、署名、ユーザーハンドルなど、いくつかの有用な情報へのアクセスを提供するAuthenticatorAssertionResponse オブジェクトが含まれています。

navigator.credentials.get({ publicKey }).then((publicKeyCredential) => {  const response = publicKeyCredential.response;  // Access authenticator data ArrayBuffer  const authenticatorData = response.authenticatorData;  // Access client JSON  const clientJSON = response.clientDataJSON;  // Access signature ArrayBuffer  const signature = response.signature;  // Access userHandle ArrayBuffer  const userHandle = response.userHandle;});

このデータの一部はサーバー上に保存する必要があります。例えば、認証者が資格情報作成に使用された本物の秘密鍵を所有していることを証明するためのsignature や、ユーザーを資格情報、ログイン試行、その他のデータと関連付けるためのuserHandle などです。

全体的なフローの詳細については、ユーザー認証を参照してください。

ワンタイムパスワードの取得

以下のコードは、SMS メッセージが到着した際にブラウザーの許可フローを起動します。許可が与えられた場合、プロミスはOTPCredential オブジェクトで解決されます。含まれるcode 値は、<input> フォーム要素の値として設定され、その後送信されます。

navigator.credentials  .get({    otp: { transport: ["sms"] },    signal: ac.signal,  })  .then((otp) => {    input.value = otp.code;    if (form) form.submit();  })  .catch((err) => {    console.error(err);  });

仕様書

ブラウザーの互換性