google_apis/gaia/gaia_oauth_client.h

   1 // Copyright (c) 2012 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 #ifndef GOOGLE_APIS_GAIA_GAIA_OAUTH_CLIENT_H_
   6 #define GOOGLE_APIS_GAIA_GAIA_OAUTH_CLIENT_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/memory/ref_counted.h"
  12 #include "base/memory/scoped_ptr.h"
  13 #include "base/values.h"
  14
  15 namespace net {
  16 class URLRequestContextGetter;
  17 }
  18
  19 // A helper class to get and refresh OAuth2 refresh and access tokens.
  20 // Also exposes utility methods for fetching user email and token information.
  21 //
  22 // Supports one request at a time; for parallel requests, create multiple
  23 // instances.
  24 namespace gaia {
  25
  26 struct OAuthClientInfo {
  27   std::string client_id;
  28   std::string client_secret;
  29   std::string redirect_uri;
  30 };
  31
  32 class GaiaOAuthClient {
  33  public:
  34   const static int kUrlFetcherId;
  35
  36   class Delegate {
  37    public:
  38     // Invoked on a successful response to the GetTokensFromAuthCode request.
  39     virtual void OnGetTokensResponse(const std::string& refresh_token,
  40                                      const std::string& access_token,
  41                                      int expires_in_seconds) {}
  42     // Invoked on a successful response to the RefreshToken request.
  43     virtual void OnRefreshTokenResponse(const std::string& access_token,
  44                                         int expires_in_seconds) {}
  45     // Invoked on a successful response to the GetUserInfo request.
  46     virtual void OnGetUserEmailResponse(const std::string& user_email) {}
  47     // Invoked on a successful response to the GetUserId request.
  48     virtual void OnGetUserIdResponse(const std::string& user_id) {}
  49     // Invoked on a successful response to the GetUserInfo request.
  50     virtual void OnGetUserInfoResponse(
  51         scoped_ptr<base::DictionaryValue> user_info) {}
  52     // Invoked on a successful response to the GetTokenInfo request.
  53     virtual void OnGetTokenInfoResponse(
  54         scoped_ptr<base::DictionaryValue> token_info) {}
  55     // Invoked when there is an OAuth error with one of the requests.
  56     virtual void OnOAuthError() = 0;
  57     // Invoked when there is a network error or upon receiving an invalid
  58     // response. This is invoked when the maximum number of retries have been
  59     // exhausted. If max_retries is -1, this is never invoked.
  60     virtual void OnNetworkError(int response_code) = 0;
  61
  62    protected:
  63     virtual ~Delegate() {}
  64   };
  65
  66   GaiaOAuthClient(net::URLRequestContextGetter* context_getter);
  67   ~GaiaOAuthClient();
  68
  69   // In the below methods, |max_retries| specifies the maximum number of times
  70   // we should retry on a network error in invalid response. This does not
  71   // apply in the case of an OAuth error (i.e. there was something wrong with
  72   // the input arguments). Setting |max_retries| to -1 implies infinite retries.
  73
  74   // Given an OAuth2 authorization code, fetch the long-lived refresh token
  75   // and a valid access token. After the access token expires, RefreshToken()
  76   // can be used to fetch a fresh access token. See |max_retries| docs above.
  77   void GetTokensFromAuthCode(const OAuthClientInfo& oauth_client_info,
  78                              const std::string& auth_code,
  79                              int max_retries,
  80                              Delegate* delegate);
  81
  82   // Given a valid refresh token (usually fetched via
  83   // |GetTokensFromAuthCode()|), fetch a fresh access token that can be used
  84   // to authenticate an API call. If |scopes| is non-empty, then fetch an
  85   // access token for those specific scopes (assuming the refresh token has the
  86   // appropriate permissions). See |max_retries| docs above.
  87   void RefreshToken(const OAuthClientInfo& oauth_client_info,
  88                     const std::string& refresh_token,
  89                     const std::vector<std::string>& scopes,
  90                     int max_retries,
  91                     Delegate* delegate);
  92
  93   // Call the userinfo API, returning the user email address associated
  94   // with the given access token. The provided access token must have
  95   // https://www.googleapis.com/auth/userinfo.email as one of its scopes.
  96   // See |max_retries| docs above.
  97   void GetUserEmail(const std::string& oauth_access_token,
  98                     int max_retries,
  99                     Delegate* delegate);
 100
 101   // Call the userinfo API, returning the user gaia ID associated
 102   // with the given access token. The provided access token must have
 103   // https://www.googleapis.com/auth/userinfo as one of its scopes.
 104   // See |max_retries| docs above.
 105   void GetUserId(const std::string& oauth_access_token,
 106                  int max_retries,
 107                  Delegate* delegate);
 108
 109   // Call the userinfo API, returning all the user info associated
 110   // with the given access token. The provided access token must have
 111   // https://www.googleapis.com/auth/userinfo.profile in its scopes.  If
 112   // email addresses are also to be retrieved, then
 113   // https://www.googleapis.com/auth/userinfo.email must also be specified.
 114   // See |max_retries| docs above.
 115   void GetUserInfo(const std::string& oauth_access_token,
 116                    int max_retries,
 117                    Delegate* delegate);
 118
 119   // Call the tokeninfo API, returning a dictionary of response values. The
 120   // provided access token may have any scope, and basic results will be
 121   // returned: issued_to, audience, scope, expires_in, access_type. In
 122   // addition, if the https://www.googleapis.com/auth/userinfo.email scope is
 123   // present, the email and verified_email fields will be returned. If the
 124   // https://www.googleapis.com/auth/userinfo.profile scope is present, the
 125   // user_id field will be returned. See |max_retries| docs above.
 126   void GetTokenInfo(const std::string& oauth_access_token,
 127                     int max_retries,
 128                     Delegate* delegate);
 129
 130   // Call the tokeninfo API for given |token_handle|, returning a dictionary of
 131   // response values. Basic results will be returned via
 132   // |OnGetTokenInfoResponse| call: audience, expires_in, user_id. See
 133   // |max_retries| docs above.
 134   void GetTokenHandleInfo(const std::string& token_handle,
 135                           int max_retries,
 136                           Delegate* delegate);
 137
 138  private:
 139   // The guts of the implementation live in this class.
 140   class Core;
 141   scoped_refptr<Core> core_;
 142   DISALLOW_COPY_AND_ASSIGN(GaiaOAuthClient);
 143 };
 144 }
 145
 146 #endif  // GOOGLE_APIS_GAIA_GAIA_OAUTH_CLIENT_H_