chrome/common/extensions/api/identity.idl

// 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://&lt;app-id&gt;.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://&lt;app-id&gt;.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);
  };
};