blob: 0cd6514352862ca8de8b73e24fca797edf225937 [file] [log] [blame]
// Copyright (c) 2013 The Chromium Authors. All rights reserved.
// 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 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;
};
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 interactive 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.
boolean? interactive;
};
dictionary AccountInfo {
// A unique identifier for the account. This ID will not change
// for the lifetime of the account.
DOMString id;
};
callback GetAuthTokenCallback = void (optional DOMString token);
callback InvalidateAuthTokenCallback = void ();
callback LaunchWebAuthFlowCallback = void (optional DOMString responseUrl);
interface Functions {
// Gets an OAuth2 access token using the client ID and scopes
// specified in the <a
// href="app_identity.html#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> any time a token is
// required. The token cache automatically handles expiration.
//
// |details| : Token options.
// |callback| : Called with an OAuth2 access token as specified by the
// manifest, or undefined if there was an error.
static void getAuthToken(optional TokenDetails details,
GetAuthTokenCallback 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, InvalidateAuthTokenCallback 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.
//
// |details| : WebAuth flow options.
// |callback| : Called with the URL redirected back to your application.
static void launchWebAuthFlow(WebAuthFlowDetails details,
LaunchWebAuthFlowCallback callback);
};
interface Events {
// Fired when signin state changes for an account on the user's profile.
static void onSignInChanged(AccountInfo account, boolean signedIn);
};
};