// Copyright 2013 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// Use the <code>chrome.identity</code> API to get OAuth2 access tokens.
namespace identity {
dictionary AccountInfo {
// A unique identifier for the account. This ID will not change
// for the lifetime of the account.
DOMString id;
};
enum AccountStatus {
// Specifies that Sync is enabled for the primary account.
SYNC,
// Specifies the existence of a primary account, if any.
ANY
};
dictionary ProfileDetails {
// A status of the primary account signed into a profile whose
// <code>ProfileUserInfo</code> should be returned. Defaults to
// <code>SYNC</code> account status.
AccountStatus? accountStatus;
};
dictionary ProfileUserInfo {
// An email address for the user account signed into the current
// profile. Empty if the user is not signed in or the
// <code>identity.email</code> manifest permission is not
// specified.
DOMString email;
// A unique identifier for the account. This ID will not change
// for the lifetime of the account. Empty if the user is not
// signed in or (in M41+) the <code>identity.email</code>
// manifest permission is not specified.
DOMString id;
};
dictionary TokenDetails {
// Fetching a token may require the user to sign-in to Chrome, or
// approve the application's requested scopes. If the interactive
// flag is <code>true</code>, <code>getAuthToken</code> will
// prompt the user as necessary. When the flag is
// <code>false</code> or omitted, <code>getAuthToken</code> will
// return failure any time a prompt would be required.
boolean? interactive;
// The account ID whose token should be returned. If not specified, the
// function will use an account from the Chrome profile: the Sync account if
// there is one, or otherwise the first Google web account.
AccountInfo? account;
// A list of OAuth2 scopes to request.
//
// When the <code>scopes</code> field is present, it overrides the
// list of scopes specified in manifest.json.
DOMString[]? scopes;
// The <code>enableGranularPermissions</code> flag allows extensions to
// opt-in early to the granular permissions consent screen, in which
// requested permissions are granted or denied individually.
boolean? enableGranularPermissions;
};
dictionary InvalidTokenDetails {
// The specific token that should be removed from the cache.
DOMString token;
};
dictionary WebAuthFlowDetails {
// The URL that initiates the auth flow.
DOMString url;
// Whether to launch auth flow in interactive mode.
//
// Since some auth flows may immediately redirect to a result URL,
// <code>launchWebAuthFlow</code> hides its web view until the first
// navigation either redirects to the final URL, or finishes loading a page
// meant to be displayed.
//
// If the <code>interactive</code> flag is <code>true</code>, the window
// will be displayed when a page load completes. If the flag is
// <code>false</code> or omitted, <code>launchWebAuthFlow</code> will return
// with an error if the initial navigation does not complete the flow.
//
// For flows that use JavaScript for redirection,
// <code>abortOnLoadForNonInteractive</code> can be set to <code>false</code>
// in combination with setting <code>timeoutMsForNonInteractive</code> to give
// the page a chance to perform any redirects.
boolean? interactive;
// Whether to terminate <code>launchWebAuthFlow</code> for non-interactive
// requests after the page loads. This parameter does not affect interactive
// flows.
//
// When set to <code>true</code> (default) the flow will terminate
// immediately after the page loads. When set to <code>false</code>, the
// flow will only terminate after the
// <code>timeoutMsForNonInteractive</code> passes. This is useful for
// identity providers that use JavaScript to perform redirections after the
// page loads.
boolean? abortOnLoadForNonInteractive;
// The maximum amount of time, in miliseconds,
// <code>launchWebAuthFlow</code> is allowed to run in non-interactive mode
// in total. Only has an effect if <code>interactive</code> is
// <code>false</code>.
long? timeoutMsForNonInteractive;
};
dictionary GetAuthTokenResult {
// The specific token associated with the request.
DOMString? token;
// A list of OAuth2 scopes granted to the extension.
DOMString[]? grantedScopes;
};
callback GetAuthTokenCallback = void (GetAuthTokenResult result);
callback GetAccountsCallback = void (AccountInfo[] accounts);
callback GetProfileUserInfoCallback = void (ProfileUserInfo userInfo);
callback InvalidateAuthTokenCallback = void ();
callback ClearAllCachedAuthTokensCallback = void ();
callback LaunchWebAuthFlowCallback = void (optional DOMString responseUrl);
interface Functions {
// Retrieves a list of AccountInfo objects describing the accounts
// present on the profile.
//
// <code>getAccounts</code> is only supported on dev channel.
static void getAccounts(GetAccountsCallback callback);
// Gets an OAuth2 access token using the client ID and scopes
// specified in the <a
// href="/docs/apps/app_identity#update_manifest"><code>oauth2</code>
// section of manifest.json</a>.
//
// The Identity API caches access tokens in memory, so it's ok to
// call <code>getAuthToken</code> non-interactively any time a token is
// required. The token cache automatically handles expiration.
//
// For a good user experience it is important interactive token requests are
// initiated by UI in your app explaining what the authorization is for.
// Failing to do this will cause your users to get authorization requests,
// or Chrome sign in screens if they are not signed in, with with no
// context. In particular, do not use <code>getAuthToken</code>
// interactively when your app is first launched.
//
// Note: When called with a callback, instead of returning an object this
// function will return the two properties as separate arguments passed to
// the callback.
//
// |details| : Token options.
// |callback| : Called with an OAuth2 access token as specified by the
// manifest, or undefined if there was an error. The
// <code>grantedScopes</code> parameter is populated since Chrome 87. When
// available, this parameter contains the list of granted scopes
// corresponding with the returned token.
static void getAuthToken(
optional TokenDetails details,
optional GetAuthTokenCallback callback);
// Retrieves email address and obfuscated gaia id of the user
// signed into a profile.
//
// Requires the <code>identity.email</code> manifest permission. Otherwise,
// returns an empty result.
//
// This API is different from identity.getAccounts in two
// ways. The information returned is available offline, and it
// only applies to the primary account for the profile.
//
// |details|: Profile options.
// |callback|: Called with the <code>ProfileUserInfo</code> of the primary
// Chrome account, of an empty <code>ProfileUserInfo</code> if the account
// with given <code>details</code> doesn't exist.
static void getProfileUserInfo(
optional ProfileDetails details,
GetProfileUserInfoCallback callback);
// Removes an OAuth2 access token from the Identity API's token cache.
//
// If an access token is discovered to be invalid, it should be
// passed to removeCachedAuthToken to remove it from the
// cache. The app may then retrieve a fresh token with
// <code>getAuthToken</code>.
//
// |details| : Token information.
// |callback| : Called when the token has been removed from the cache.
static void removeCachedAuthToken(
InvalidTokenDetails details,
optional InvalidateAuthTokenCallback callback);
// Resets the state of the Identity API:
// <ul>
// <li>Removes all OAuth2 access tokens from the token cache</li>
// <li>Removes user's account preferences</li>
// <li>De-authorizes the user from all auth flows</li>
// </ul>
//
// |callback| : Called when the state has been cleared.
static void clearAllCachedAuthTokens(
ClearAllCachedAuthTokensCallback callback);
// Starts an auth flow at the specified URL.
//
// This method enables auth flows with non-Google identity
// providers by launching a web view and navigating it to the
// first URL in the provider's auth flow. When the provider
// redirects to a URL matching the pattern
// <code>https://<app-id>.chromiumapp.org/*</code>, the
// window will close, and the final redirect URL will be passed to
// the <var>callback</var> function.
//
// For a good user experience it is important interactive auth flows are
// initiated by UI in your app explaining what the authorization is for.
// Failing to do this will cause your users to get authorization requests
// with no context. In particular, do not launch an interactive auth flow
// when your app is first launched.
//
// |details| : WebAuth flow options.
// |callback| : Called with the URL redirected back to your application.
static void launchWebAuthFlow(
WebAuthFlowDetails details,
LaunchWebAuthFlowCallback callback);
// Generates a redirect URL to be used in |launchWebAuthFlow|.
//
// The generated URLs match the pattern
// <code>https://<app-id>.chromiumapp.org/*</code>.
//
// |path| : The path appended to the end of the generated URL.
[nocompile] static DOMString getRedirectURL(optional DOMString path);
};
interface Events {
// Fired when signin state changes for an account on the user's profile.
static void onSignInChanged(AccountInfo account, boolean signedIn);
};
};
Codebase Browser
chromium