chrome/common/extensions/api/identity.idl

   1 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use the <code>chrome.identity</code> API to get OAuth2 access tokens.
   6 namespace identity {
   7
   8   dictionary TokenDetails {
   9     // Fetching a token may require the user to sign-in to Chrome, or
  10     // approve the application's requested scopes. If the interactive
  11     // flag is <code>true</code>, <code>getAuthToken</code> will
  12     // prompt the user as necessary. When the flag is
  13     // <code>false</code> or omitted, <code>getAuthToken</code> will
  14     // return failure any time a prompt would be required.
  15     boolean? interactive;
  16   };
  17
  18   dictionary InvalidTokenDetails {
  19     // The specific token that should be removed from the cache.
  20     DOMString token;
  21   };
  22
  23   dictionary WebAuthFlowDetails {
  24     // The URL that initiates the auth flow.
  25     DOMString url;
  26
  27     // Whether to launch auth flow in interactive mode.
  28     //
  29     // Since some auth flows may immediately redirect to a result URL,
  30     // <code>launchWebAuthFlow</code> hides its web view until the
  31     // first navigation either redirects to the final URL, or finishes
  32     // loading a page meant to be displayed.
  33     //
  34     // If the interactive flag is <code>true</code>, the window will
  35     // be displayed when a page load completes. If the flag is
  36     // <code>false</code> or omitted, <code>launchWebAuthFlow</code>
  37     // will return with an error if the initial navigation does not
  38     // complete the flow.
  39     boolean? interactive;
  40   };
  41
  42   dictionary AccountInfo {
  43     // A unique identifier for the account. This ID will not change
  44     // for the lifetime of the account.
  45     DOMString id;
  46   };
  47
  48   callback GetAuthTokenCallback = void (optional DOMString token);
  49   callback InvalidateAuthTokenCallback = void ();
  50   callback LaunchWebAuthFlowCallback = void (optional DOMString responseUrl);
  51
  52   interface Functions {
  53     // Gets an OAuth2 access token using the client ID and scopes
  54     // specified in the <a
  55     // href="app_identity.html#update_manifest"><code>oauth2</code>
  56     // section of manifest.json</a>.
  57     //
  58     // The Identity API caches access tokens in memory, so it's ok to
  59     // call <code>getAuthToken</code> any time a token is
  60     // required. The token cache automatically handles expiration.
  61     //
  62     // |details| : Token options.
  63     // |callback| : Called with an OAuth2 access token as specified by the
  64     // manifest, or undefined if there was an error.
  65     static void getAuthToken(optional TokenDetails details,
  66                              GetAuthTokenCallback callback);
  67
  68     // Removes an OAuth2 access token from the Identity API's token cache.
  69     //
  70     // If an access token is discovered to be invalid, it should be
  71     // passed to removeCachedAuthToken to remove it from the
  72     // cache. The app may then retrieve a fresh token with
  73     // <code>getAuthToken</code>.
  74     //
  75     // |details| : Token information.
  76     // |callback| : Called when the token has been removed from the cache.
  77     static void removeCachedAuthToken(
  78         InvalidTokenDetails details, InvalidateAuthTokenCallback callback);
  79
  80     // Starts an auth flow at the specified URL.
  81     //
  82     // This method enables auth flows with non-Google identity
  83     // providers by launching a web view and navigating it to the
  84     // first URL in the provider's auth flow. When the provider
  85     // redirects to a URL matching the pattern
  86     // <code>https://&lt;app-id&gt;.chromiumapp.org/*</code>, the
  87     // window will close, and the final redirect URL will be passed to
  88     // the <var>callback</var> function.
  89     //
  90     // |details| : WebAuth flow options.
  91     // |callback| : Called with the URL redirected back to your application.
  92     static void launchWebAuthFlow(WebAuthFlowDetails details,
  93                                   LaunchWebAuthFlowCallback callback);
  94
  95     // Generates a redirect URL to be used in |launchWebAuthFlow|.
  96     //
  97     // The generated URLs match the pattern
  98     // <code>https://&lt;app-id&gt;.chromiumapp.org/*</code>.
  99     //
 100     // |path| : The path appended to the end of the generated URL.
 101     [nocompile] static DOMString getRedirectURL(optional DOMString path);
 102   };
 103
 104   interface Events {
 105     // Fired when signin state changes for an account on the user's profile.
 106     static void onSignInChanged(AccountInfo account, boolean signedIn);
 107   };
 108 };