chrome.identity

説明

chrome.identity API を使用して OAuth2 アクセス トークンを取得します。

権限

identity

型

AccountInfo

プロパティ

  • id

    文字列

    アカウントの一意の識別子。この ID は、アカウントが存続期間中に変更されることはありません。

AccountStatus

Chrome 84 以降

列挙型

SYNC
メイン アカウントで同期が有効になっていることを指定します。

"ANY"
メイン アカウントが存在することを指定します（存在する場合）。

GetAuthTokenResult

Chrome 105 以降

プロパティ

  • grantedScopes

    文字列 [] 省略可

    拡張機能に付与されている OAuth2 スコープのリスト。

  • token

    文字列（省略可）

    リクエストに関連付けられている特定のトークン。

InvalidTokenDetails

プロパティ

  • token

    文字列

    キャッシュから削除する特定のトークン。

ProfileDetails

Chrome 84 以降

プロパティ

  • accountStatus

    AccountStatus（省略可）

    ProfileUserInfo を返す必要があるプロフィールにログインしているメイン アカウントのステータス。デフォルトは SYNC アカウント ステータスです。

ProfileUserInfo

プロパティ

  • メール

    文字列

    現在のプロファイルにログインしているユーザー アカウントのメールアドレス。ユーザーがログインしていない場合、または identity.email マニフェスト権限が指定されていない場合は空になります。

  • id

    文字列

    アカウントの一意の識別子。この ID は、アカウントが存続期間中に変更されることはありません。ユーザーがログインしていない場合、または（M41 以降で）identity.email マニフェスト権限が指定されていない場合は空になります。

TokenDetails

プロパティ

  • アカウント

    AccountInfo（省略可）

    トークンを返す必要があるアカウント ID。指定しない場合、Chrome プロファイルのアカウント（同期アカウントがある場合は同期アカウント、それ以外の場合は最初の Google ウェブ アカウント）が使用されます。

  • enableGranularPermissions

    ブール値（省略可）

    Chrome 87 以降

    enableGranularPermissions フラグを使用すると、リクエストされた権限を個別に許可または拒否する詳細な権限同意画面を、拡張機能が早期にオプトインできます。

  • インタラクティブ

    ブール値（省略可）

    トークンを取得する際に、ユーザーが Chrome にログインするか、アプリケーションがリクエストしたスコープを承認する必要がある場合があります。インタラクティブ フラグが true の場合、getAuthToken は必要に応じてユーザーにプロンプトを表示します。フラグを false に設定するか省略すると、getAuthToken はプロンプトが必要になるたびに失敗を返します。

  • スコープ

    文字列 [] 省略可

    リクエストする OAuth2 スコープのリスト。

    scopes フィールドが存在する場合、manifest.json で指定されたスコープのリストがオーバーライドされます。

WebAuthFlowDetails

プロパティ

  • abortOnLoadForNonInteractive

    ブール値（省略可）

    Chrome 113 以降

    ページの読み込み後に非インタラクティブ リクエストの launchWebAuthFlow を終了するかどうかを指定します。このパラメータは、インタラクティブフローには影響しません。

    true（デフォルト）に設定すると、ページが読み込まれた直後にフローが終了します。false に設定すると、フローは timeoutMsForNonInteractive に合格した後にのみ終了します。これは、ID プロバイダが JavaScript を使用してページの読み込み後にリダイレクトを実行する場合に便利です。

  • インタラクティブ

    ブール値（省略可）

    インタラクティブ モードで認証フローを起動するかどうか。

    一部の認証フローは直ちに結果の URL にリダイレクトされる場合があるため、launchWebAuthFlow は、最初のナビゲーションが最終ページ URL にリダイレクトするか、表示されるはずのページの読み込みが完了するまで、ウェブビューを非表示にします。

    interactive フラグが true の場合、ページの読み込みが完了するとウィンドウが表示されます。フラグを false にするか省略すると、最初のナビゲーションでフローが完了しなかった場合に launchWebAuthFlow はエラーを返します。

    リダイレクトに JavaScript を使用するフローの場合、abortOnLoadForNonInteractive を false に設定して、timeoutMsForNonInteractive を設定すると、ページで任意のリダイレクトを実行できます。

  • timeoutMsForNonInteractive

    数値（省略可）

    Chrome 113 以降

    launchWebAuthFlow を非インタラクティブ モードで実行できる最大時間（ミリ秒単位）。interactive が false の場合にのみ効果があります。

  • URL

    文字列

    認証フローを開始する URL。

メソッド

clearAllCachedAuthTokens()

<ph type="x-smartling-placeholder"></ph> 約束 Chrome 87 以降 をご覧ください。
chrome.identity.clearAllCachedAuthTokens(
  callback?: function,
)

Identity API の状態をリセットします。

  • トークン キャッシュからすべての OAuth2 アクセス トークンを削除します
  • ユーザーのアカウント設定を削除する
  • すべての認証フローからユーザーの許可を取り消す

パラメータ

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    () => void

戻り値

  • 約束 <void>

    Chrome 106 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getAccounts()

<ph type="x-smartling-placeholder"></ph> 約束 Dev チャンネル をご覧ください。
chrome.identity.getAccounts(
  callback?: function,
)

プロフィールに存在するアカウントを表す AccountInfo オブジェクトのリストを取得します。

getAccounts は Dev チャンネルでのみサポートされています。

パラメータ

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (accounts: AccountInfo[]) => void

戻り値

  • Promise&lt;AccountInfo[]&gt;

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getAuthToken()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.identity.getAuthToken(
  details?: TokenDetails,
  callback?: function,
)

manifest.json の oauth2 セクションで指定されたクライアント ID とスコープを使用して、OAuth2 アクセス トークンを取得します。

Identity API はアクセス トークンをメモリにキャッシュするため、トークンが必要なときはいつでも、非対話形式で getAuthToken を呼び出しても問題ありません。トークン キャッシュは有効期限を自動的に処理します。

優れたユーザー エクスペリエンスを実現するには、アプリの UI からインタラクティブなトークン リクエストを開始して、認可の目的を説明することが重要です。この認証を行わないと、ユーザーがログインしていない場合は、承認リクエストや Chrome のログイン画面が表示され、コンテキストも示されません。特に、アプリの初回起動時に getAuthToken をインタラクティブに使用しないでください。

注: コールバックで呼び出した場合、この関数はオブジェクトを返すのではなく、コールバックに渡される個別の引数として 2 つのプロパティを返します。

パラメータ

  • 詳細

    TokenDetails 省略可

    トークンのオプション。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (result: GetAuthTokenResult) => void

戻り値

  • Promise&lt;GetAuthTokenResult&gt;

    Chrome 105 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getProfileUserInfo()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.identity.getProfileUserInfo(
  details?: ProfileDetails,
  callback?: function,
)

プロファイルにログインしているユーザーのメールアドレスと難読化された GAIA ID を取得します。

identity.email マニフェスト権限が必要です。それ以外の場合は、空の結果を返します。

この API は identity.getAccounts と 2 つの点で異なります。返された情報はオフラインで利用できます。また、この情報はプロファイルのメイン アカウントにのみ適用されます。

パラメータ

  • 詳細

    ProfileDetails 省略可

    Chrome 84 以降

    プロファイルのオプション。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (userInfo: ProfileUserInfo) => void

戻り値

  • Promise&lt;ProfileUserInfo&gt;

    Chrome 106 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

getRedirectURL()

chrome.identity.getRedirectURL(
  path?: string,
)

launchWebAuthFlow で使用するリダイレクト URL を生成します。

生成された URL はパターン https://<app-id>.chromiumapp.org/* に一致します。

パラメータ

  • パス

    文字列（省略可）

    生成された URL の末尾に付加されるパス。

戻り値

  • 文字列

launchWebAuthFlow()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.identity.launchWebAuthFlow(
  details: WebAuthFlowDetails,
  callback?: function,
)

指定された URL で認証フローを開始します。

この方法では、ウェブビューを起動してプロバイダの認証フローの最初の URL に移動することで、Google 以外の ID プロバイダによる認証フローが可能になります。プロバイダがパターン https://<app-id>.chromiumapp.org/* に一致する URL にリダイレクトすると、ウィンドウが閉じ、最終リダイレクト URL が callback 関数に渡されます。

優れたユーザー エクスペリエンスを実現するには、アプリ内の UI によってインタラクティブな認証フローを開始して、認可の目的を説明することが重要です。このようにしないと、ユーザーがコンテキストのない認可リクエストを受け取ることになります。特に、アプリの初回起動時にインタラクティブな認証フローを開始しないでください。

パラメータ

  • WebAuth フローのオプション。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (responseUrl?: string) => void

    • responseUrl

      文字列（省略可）

戻り値

  • Promise<文字列 |未定義>

    Chrome 106 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

removeCachedAuthToken()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.identity.removeCachedAuthToken(
  details: InvalidTokenDetails,
  callback?: function,
)

Identity API のトークン キャッシュから OAuth2 アクセス トークンを削除します。

アクセス トークンが無効であることが判明した場合は、そのトークンを removeCachedAuthToken に渡してキャッシュから削除する必要があります。その後、アプリは getAuthToken を使用して新しいトークンを取得できます。

パラメータ

  • トークン情報。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    () => void

戻り値

  • 約束 <void>

    Chrome 106 以降

    Promise は Manifest V3 以降でのみサポートされています。他のプラットフォームではコールバックを使用する必要があります。

イベント

onSignInChanged

chrome.identity.onSignInChanged.addListener(
  callback: function,
)

ユーザーのプロフィールでアカウントのログイン状態が変更されたときに呼び出されます。

パラメータ

  • callback

    関数

    callback パラメータは次のようになります。 

    (account: AccountInfo, signedIn: boolean) => void