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 GetAccountsCallback = void (AccountInfo[] accounts);
  50   callback InvalidateAuthTokenCallback = void ();
  51   callback LaunchWebAuthFlowCallback = void (optional DOMString responseUrl);
  52
  53   interface Functions {
  54     // Retrieves a list of AccountInfo objects describing the accounts
  55     // present on the profile.<br>
  56     // <code>getAccounts</code> is only supported on dev channel.
  57     static void getAccounts(GetAccountsCallback callback);
  58
  59     // Gets an OAuth2 access token using the client ID and scopes
  60     // specified in the <a
  61     // href="app_identity.html#update_manifest"><code>oauth2</code>
  62     // section of manifest.json</a>.
  63     //
  64     // The Identity API caches access tokens in memory, so it's ok to
  65     // call <code>getAuthToken</code> non-interactively any time a token is
  66     // required. The token cache automatically handles expiration.
  67     //
  68     // For a good user experience it is important interactive token requests are
  69     // initiated by UI in your app explaining what the authorization is for.
  70     // Failing to do this will cause your users to get authorization requests,
  71     // or Chrome sign in screens if they are not signed in, with with no
  72     // context. In particular, do not use <code>getAuthToken</code>
  73     // interactively when your app is first launched.
  74     //
  75     // |details| : Token options.
  76     // |callback| : Called with an OAuth2 access token as specified by the
  77     // manifest, or undefined if there was an error.
  78     static void getAuthToken(optional TokenDetails details,
  79                              GetAuthTokenCallback callback);
  80
  81     // Removes an OAuth2 access token from the Identity API's token cache.
  82     //
  83     // If an access token is discovered to be invalid, it should be
  84     // passed to removeCachedAuthToken to remove it from the
  85     // cache. The app may then retrieve a fresh token with
  86     // <code>getAuthToken</code>.
  87     //
  88     // |details| : Token information.
  89     // |callback| : Called when the token has been removed from the cache.
  90     static void removeCachedAuthToken(
  91         InvalidTokenDetails details, InvalidateAuthTokenCallback callback);
  92
  93     // Starts an auth flow at the specified URL.
  94     //
  95     // This method enables auth flows with non-Google identity
  96     // providers by launching a web view and navigating it to the
  97     // first URL in the provider's auth flow. When the provider
  98     // redirects to a URL matching the pattern
  99     // <code>https://&lt;app-id&gt;.chromiumapp.org/*</code>, the
 100     // window will close, and the final redirect URL will be passed to
 101     // the <var>callback</var> function.
 102     //
 103     // For a good user experience it is important interactive auth flows are
 104     // initiated by UI in your app explaining what the authorization is for.
 105     // Failing to do this will cause your users to get authorization requests
 106     // with no context. In particular, do not launch an interactive auth flow
 107     // when your app is first launched.
 108     //
 109     // |details| : WebAuth flow options.
 110     // |callback| : Called with the URL redirected back to your application.
 111     static void launchWebAuthFlow(WebAuthFlowDetails details,
 112                                   LaunchWebAuthFlowCallback callback);
 113
 114     // Generates a redirect URL to be used in |launchWebAuthFlow|.
 115     //
 116     // The generated URLs match the pattern
 117     // <code>https://&lt;app-id&gt;.chromiumapp.org/*</code>.
 118     //
 119     // |path| : The path appended to the end of the generated URL.
 120     [nocompile] static DOMString getRedirectURL(optional DOMString path);
 121   };
 122
 123   interface Events {
 124     // Fired when signin state changes for an account on the user's profile.
 125     static void onSignInChanged(AccountInfo account, boolean signedIn);
 126   };
 127 };