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