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 AccountInfo {
   9     // A unique identifier for the account. This ID will not change
  10     // for the lifetime of the account.
  11     DOMString id;
  12   };
  13
  14   dictionary ProfileUserInfo {
  15     // An email address for the user account signed into the current
  16     // profile. Empty if the user is not signed in or the
  17     // <code>identity.email</code> manifest permission is not
  18     // specified.
  19     DOMString email;
  20
  21     // A unique identifier for the account. This ID will not change
  22     // for the lifetime of the account. Empty if the user is not
  23     // signed in or (in M41+) the <code>identity.email</code>
  24     // manifest permission is not specified.
  25     DOMString id;
  26   };
  27
  28   dictionary TokenDetails {
  29     // Fetching a token may require the user to sign-in to Chrome, or
  30     // approve the application's requested scopes. If the interactive
  31     // flag is <code>true</code>, <code>getAuthToken</code> will
  32     // prompt the user as necessary. When the flag is
  33     // <code>false</code> or omitted, <code>getAuthToken</code> will
  34     // return failure any time a prompt would be required.
  35     boolean? interactive;
  36
  37     // The account ID whose token should be returned. If not
  38     // specified, the primary account for the profile will be used.
  39     //
  40     // <code>account</code> is only supported when the
  41     // "enable-new-profile-management" flag is set.
  42     AccountInfo? account;
  43
  44     // A list of OAuth2 scopes to request.
  45     //
  46     // When the <code>scopes</code> field is present, it overrides the
  47     // list of scopes specified in manifest.json.
  48     DOMString[]? scopes;
  49   };
  50
  51   dictionary InvalidTokenDetails {
  52     // The specific token that should be removed from the cache.
  53     DOMString token;
  54   };
  55
  56   dictionary WebAuthFlowDetails {
  57     // The URL that initiates the auth flow.
  58     DOMString url;
  59
  60     // Whether to launch auth flow in interactive mode.
  61     //
  62     // Since some auth flows may immediately redirect to a result URL,
  63     // <code>launchWebAuthFlow</code> hides its web view until the
  64     // first navigation either redirects to the final URL, or finishes
  65     // loading a page meant to be displayed.
  66     //
  67     // If the interactive flag is <code>true</code>, the window will
  68     // be displayed when a page load completes. If the flag is
  69     // <code>false</code> or omitted, <code>launchWebAuthFlow</code>
  70     // will return with an error if the initial navigation does not
  71     // complete the flow.
  72     boolean? interactive;
  73   };
  74
  75   callback GetAuthTokenCallback = void (optional DOMString token);
  76   callback GetAccountsCallback = void (AccountInfo[] accounts);
  77   callback GetProfileUserInfoCallback = void (ProfileUserInfo userInfo);
  78   callback InvalidateAuthTokenCallback = void ();
  79   callback LaunchWebAuthFlowCallback = void (optional DOMString responseUrl);
  80
  81   interface Functions {
  82     // Retrieves a list of AccountInfo objects describing the accounts
  83     // present on the profile.
  84     //
  85     // <code>getAccounts</code> is only supported on dev channel.
  86     static void getAccounts(GetAccountsCallback callback);
  87
  88     // Gets an OAuth2 access token using the client ID and scopes
  89     // specified in the <a
  90     // href="app_identity.html#update_manifest"><code>oauth2</code>
  91     // section of manifest.json</a>.
  92     //
  93     // The Identity API caches access tokens in memory, so it's ok to
  94     // call <code>getAuthToken</code> non-interactively any time a token is
  95     // required. The token cache automatically handles expiration.
  96     //
  97     // For a good user experience it is important interactive token requests are
  98     // initiated by UI in your app explaining what the authorization is for.
  99     // Failing to do this will cause your users to get authorization requests,
 100     // or Chrome sign in screens if they are not signed in, with with no
 101     // context. In particular, do not use <code>getAuthToken</code>
 102     // interactively when your app is first launched.
 103     //
 104     // |details| : Token options.
 105     // |callback| : Called with an OAuth2 access token as specified by the
 106     // manifest, or undefined if there was an error.
 107     static void getAuthToken(optional TokenDetails details,
 108                              optional GetAuthTokenCallback callback);
 109
 110     // Retrieves email address and obfuscated gaia id of the user
 111     // signed into a profile.
 112     //
 113     // This API is different from identity.getAccounts in two
 114     // ways. The information returned is available offline, and it
 115     // only applies to the primary account for the profile.
 116     static void getProfileUserInfo(GetProfileUserInfoCallback callback);
 117
 118     // Removes an OAuth2 access token from the Identity API's token cache.
 119     //
 120     // If an access token is discovered to be invalid, it should be
 121     // passed to removeCachedAuthToken to remove it from the
 122     // cache. The app may then retrieve a fresh token with
 123     // <code>getAuthToken</code>.
 124     //
 125     // |details| : Token information.
 126     // |callback| : Called when the token has been removed from the cache.
 127     static void removeCachedAuthToken(
 128         InvalidTokenDetails details,
 129         optional InvalidateAuthTokenCallback callback);
 130
 131     // Starts an auth flow at the specified URL.
 132     //
 133     // This method enables auth flows with non-Google identity
 134     // providers by launching a web view and navigating it to the
 135     // first URL in the provider's auth flow. When the provider
 136     // redirects to a URL matching the pattern
 137     // <code>https://&lt;app-id&gt;.chromiumapp.org/*</code>, the
 138     // window will close, and the final redirect URL will be passed to
 139     // the <var>callback</var> function.
 140     //
 141     // For a good user experience it is important interactive auth flows are
 142     // initiated by UI in your app explaining what the authorization is for.
 143     // Failing to do this will cause your users to get authorization requests
 144     // with no context. In particular, do not launch an interactive auth flow
 145     // when your app is first launched.
 146     //
 147     // |details| : WebAuth flow options.
 148     // |callback| : Called with the URL redirected back to your application.
 149     static void launchWebAuthFlow(WebAuthFlowDetails details,
 150                                   LaunchWebAuthFlowCallback callback);
 151
 152     // Generates a redirect URL to be used in |launchWebAuthFlow|.
 153     //
 154     // The generated URLs match the pattern
 155     // <code>https://&lt;app-id&gt;.chromiumapp.org/*</code>.
 156     //
 157     // |path| : The path appended to the end of the generated URL.
 158     [nocompile] static DOMString getRedirectURL(optional DOMString path);
 159   };
 160
 161   interface Events {
 162     // Fired when signin state changes for an account on the user's profile.
 163     static void onSignInChanged(AccountInfo account, boolean signedIn);
 164   };
 165 };