blob: 3de63315b8cec48c802e43e32aa3614588bde72e [file] [log] [blame]
sslobodrd046be82019-01-16 10:02:22 -05001// Copyright 2014 The Go Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style
3// license that can be found in the LICENSE file.
4
5// Package oauth2 provides support for making
6// OAuth2 authorized and authenticated HTTP requests,
7// as specified in RFC 6749.
8// It can additionally grant authorization with Bearer JWT.
9package oauth2 // import "golang.org/x/oauth2"
10
11import (
12 "bytes"
13 "context"
14 "errors"
15 "net/http"
16 "net/url"
17 "strings"
18 "sync"
19
20 "golang.org/x/oauth2/internal"
21)
22
23// NoContext is the default context you should supply if not using
24// your own context.Context (see https://golang.org/x/net/context).
25//
26// Deprecated: Use context.Background() or context.TODO() instead.
27var NoContext = context.TODO()
28
29// RegisterBrokenAuthHeaderProvider registers an OAuth2 server
30// identified by the tokenURL prefix as an OAuth2 implementation
31// which doesn't support the HTTP Basic authentication
32// scheme to authenticate with the authorization server.
33// Once a server is registered, credentials (client_id and client_secret)
34// will be passed as parameters in the request body rather than being present
35// in the Authorization header.
36// See https://code.google.com/p/goauth2/issues/detail?id=31 for background.
37func RegisterBrokenAuthHeaderProvider(tokenURL string) {
38 internal.RegisterBrokenAuthHeaderProvider(tokenURL)
39}
40
41// Config describes a typical 3-legged OAuth2 flow, with both the
42// client application information and the server's endpoint URLs.
43// For the client credentials 2-legged OAuth2 flow, see the clientcredentials
44// package (https://golang.org/x/oauth2/clientcredentials).
45type Config struct {
46 // ClientID is the application's ID.
47 ClientID string
48
49 // ClientSecret is the application's secret.
50 ClientSecret string
51
52 // Endpoint contains the resource server's token endpoint
53 // URLs. These are constants specific to each server and are
54 // often available via site-specific packages, such as
55 // google.Endpoint or github.Endpoint.
56 Endpoint Endpoint
57
58 // RedirectURL is the URL to redirect users going through
59 // the OAuth flow, after the resource owner's URLs.
60 RedirectURL string
61
62 // Scope specifies optional requested permissions.
63 Scopes []string
64}
65
66// A TokenSource is anything that can return a token.
67type TokenSource interface {
68 // Token returns a token or an error.
69 // Token must be safe for concurrent use by multiple goroutines.
70 // The returned Token must not be modified.
71 Token() (*Token, error)
72}
73
74// Endpoint contains the OAuth 2.0 provider's authorization and token
75// endpoint URLs.
76type Endpoint struct {
77 AuthURL string
78 TokenURL string
79}
80
81var (
82 // AccessTypeOnline and AccessTypeOffline are options passed
83 // to the Options.AuthCodeURL method. They modify the
84 // "access_type" field that gets sent in the URL returned by
85 // AuthCodeURL.
86 //
87 // Online is the default if neither is specified. If your
88 // application needs to refresh access tokens when the user
89 // is not present at the browser, then use offline. This will
90 // result in your application obtaining a refresh token the
91 // first time your application exchanges an authorization
92 // code for a user.
93 AccessTypeOnline AuthCodeOption = SetAuthURLParam("access_type", "online")
94 AccessTypeOffline AuthCodeOption = SetAuthURLParam("access_type", "offline")
95
96 // ApprovalForce forces the users to view the consent dialog
97 // and confirm the permissions request at the URL returned
98 // from AuthCodeURL, even if they've already done so.
99 ApprovalForce AuthCodeOption = SetAuthURLParam("approval_prompt", "force")
100)
101
102// An AuthCodeOption is passed to Config.AuthCodeURL.
103type AuthCodeOption interface {
104 setValue(url.Values)
105}
106
107type setParam struct{ k, v string }
108
109func (p setParam) setValue(m url.Values) { m.Set(p.k, p.v) }
110
111// SetAuthURLParam builds an AuthCodeOption which passes key/value parameters
112// to a provider's authorization endpoint.
113func SetAuthURLParam(key, value string) AuthCodeOption {
114 return setParam{key, value}
115}
116
117// AuthCodeURL returns a URL to OAuth 2.0 provider's consent page
118// that asks for permissions for the required scopes explicitly.
119//
120// State is a token to protect the user from CSRF attacks. You must
121// always provide a non-empty string and validate that it matches the
122// the state query parameter on your redirect callback.
123// See http://tools.ietf.org/html/rfc6749#section-10.12 for more info.
124//
125// Opts may include AccessTypeOnline or AccessTypeOffline, as well
126// as ApprovalForce.
127// It can also be used to pass the PKCE challange.
128// See https://www.oauth.com/oauth2-servers/pkce/ for more info.
129func (c *Config) AuthCodeURL(state string, opts ...AuthCodeOption) string {
130 var buf bytes.Buffer
131 buf.WriteString(c.Endpoint.AuthURL)
132 v := url.Values{
133 "response_type": {"code"},
134 "client_id": {c.ClientID},
135 }
136 if c.RedirectURL != "" {
137 v.Set("redirect_uri", c.RedirectURL)
138 }
139 if len(c.Scopes) > 0 {
140 v.Set("scope", strings.Join(c.Scopes, " "))
141 }
142 if state != "" {
143 // TODO(light): Docs say never to omit state; don't allow empty.
144 v.Set("state", state)
145 }
146 for _, opt := range opts {
147 opt.setValue(v)
148 }
149 if strings.Contains(c.Endpoint.AuthURL, "?") {
150 buf.WriteByte('&')
151 } else {
152 buf.WriteByte('?')
153 }
154 buf.WriteString(v.Encode())
155 return buf.String()
156}
157
158// PasswordCredentialsToken converts a resource owner username and password
159// pair into a token.
160//
161// Per the RFC, this grant type should only be used "when there is a high
162// degree of trust between the resource owner and the client (e.g., the client
163// is part of the device operating system or a highly privileged application),
164// and when other authorization grant types are not available."
165// See https://tools.ietf.org/html/rfc6749#section-4.3 for more info.
166//
167// The provided context optionally controls which HTTP client is used. See the HTTPClient variable.
168func (c *Config) PasswordCredentialsToken(ctx context.Context, username, password string) (*Token, error) {
169 v := url.Values{
170 "grant_type": {"password"},
171 "username": {username},
172 "password": {password},
173 }
174 if len(c.Scopes) > 0 {
175 v.Set("scope", strings.Join(c.Scopes, " "))
176 }
177 return retrieveToken(ctx, c, v)
178}
179
180// Exchange converts an authorization code into a token.
181//
182// It is used after a resource provider redirects the user back
183// to the Redirect URI (the URL obtained from AuthCodeURL).
184//
185// The provided context optionally controls which HTTP client is used. See the HTTPClient variable.
186//
187// The code will be in the *http.Request.FormValue("code"). Before
188// calling Exchange, be sure to validate FormValue("state").
189//
190// Opts may include the PKCE verifier code if previously used in AuthCodeURL.
191// See https://www.oauth.com/oauth2-servers/pkce/ for more info.
192func (c *Config) Exchange(ctx context.Context, code string, opts ...AuthCodeOption) (*Token, error) {
193 v := url.Values{
194 "grant_type": {"authorization_code"},
195 "code": {code},
196 }
197 if c.RedirectURL != "" {
198 v.Set("redirect_uri", c.RedirectURL)
199 }
200 for _, opt := range opts {
201 opt.setValue(v)
202 }
203 return retrieveToken(ctx, c, v)
204}
205
206// Client returns an HTTP client using the provided token.
207// The token will auto-refresh as necessary. The underlying
208// HTTP transport will be obtained using the provided context.
209// The returned client and its Transport should not be modified.
210func (c *Config) Client(ctx context.Context, t *Token) *http.Client {
211 return NewClient(ctx, c.TokenSource(ctx, t))
212}
213
214// TokenSource returns a TokenSource that returns t until t expires,
215// automatically refreshing it as necessary using the provided context.
216//
217// Most users will use Config.Client instead.
218func (c *Config) TokenSource(ctx context.Context, t *Token) TokenSource {
219 tkr := &tokenRefresher{
220 ctx: ctx,
221 conf: c,
222 }
223 if t != nil {
224 tkr.refreshToken = t.RefreshToken
225 }
226 return &reuseTokenSource{
227 t: t,
228 new: tkr,
229 }
230}
231
232// tokenRefresher is a TokenSource that makes "grant_type"=="refresh_token"
233// HTTP requests to renew a token using a RefreshToken.
234type tokenRefresher struct {
235 ctx context.Context // used to get HTTP requests
236 conf *Config
237 refreshToken string
238}
239
240// WARNING: Token is not safe for concurrent access, as it
241// updates the tokenRefresher's refreshToken field.
242// Within this package, it is used by reuseTokenSource which
243// synchronizes calls to this method with its own mutex.
244func (tf *tokenRefresher) Token() (*Token, error) {
245 if tf.refreshToken == "" {
246 return nil, errors.New("oauth2: token expired and refresh token is not set")
247 }
248
249 tk, err := retrieveToken(tf.ctx, tf.conf, url.Values{
250 "grant_type": {"refresh_token"},
251 "refresh_token": {tf.refreshToken},
252 })
253
254 if err != nil {
255 return nil, err
256 }
257 if tf.refreshToken != tk.RefreshToken {
258 tf.refreshToken = tk.RefreshToken
259 }
260 return tk, err
261}
262
263// reuseTokenSource is a TokenSource that holds a single token in memory
264// and validates its expiry before each call to retrieve it with
265// Token. If it's expired, it will be auto-refreshed using the
266// new TokenSource.
267type reuseTokenSource struct {
268 new TokenSource // called when t is expired.
269
270 mu sync.Mutex // guards t
271 t *Token
272}
273
274// Token returns the current token if it's still valid, else will
275// refresh the current token (using r.Context for HTTP client
276// information) and return the new one.
277func (s *reuseTokenSource) Token() (*Token, error) {
278 s.mu.Lock()
279 defer s.mu.Unlock()
280 if s.t.Valid() {
281 return s.t, nil
282 }
283 t, err := s.new.Token()
284 if err != nil {
285 return nil, err
286 }
287 s.t = t
288 return t, nil
289}
290
291// StaticTokenSource returns a TokenSource that always returns the same token.
292// Because the provided token t is never refreshed, StaticTokenSource is only
293// useful for tokens that never expire.
294func StaticTokenSource(t *Token) TokenSource {
295 return staticTokenSource{t}
296}
297
298// staticTokenSource is a TokenSource that always returns the same Token.
299type staticTokenSource struct {
300 t *Token
301}
302
303func (s staticTokenSource) Token() (*Token, error) {
304 return s.t, nil
305}
306
307// HTTPClient is the context key to use with golang.org/x/net/context's
308// WithValue function to associate an *http.Client value with a context.
309var HTTPClient internal.ContextKey
310
311// NewClient creates an *http.Client from a Context and TokenSource.
312// The returned client is not valid beyond the lifetime of the context.
313//
314// Note that if a custom *http.Client is provided via the Context it
315// is used only for token acquisition and is not used to configure the
316// *http.Client returned from NewClient.
317//
318// As a special case, if src is nil, a non-OAuth2 client is returned
319// using the provided context. This exists to support related OAuth2
320// packages.
321func NewClient(ctx context.Context, src TokenSource) *http.Client {
322 if src == nil {
323 return internal.ContextClient(ctx)
324 }
325 return &http.Client{
326 Transport: &Transport{
327 Base: internal.ContextClient(ctx).Transport,
328 Source: ReuseTokenSource(nil, src),
329 },
330 }
331}
332
333// ReuseTokenSource returns a TokenSource which repeatedly returns the
334// same token as long as it's valid, starting with t.
335// When its cached token is invalid, a new token is obtained from src.
336//
337// ReuseTokenSource is typically used to reuse tokens from a cache
338// (such as a file on disk) between runs of a program, rather than
339// obtaining new tokens unnecessarily.
340//
341// The initial token t may be nil, in which case the TokenSource is
342// wrapped in a caching version if it isn't one already. This also
343// means it's always safe to wrap ReuseTokenSource around any other
344// TokenSource without adverse effects.
345func ReuseTokenSource(t *Token, src TokenSource) TokenSource {
346 // Don't wrap a reuseTokenSource in itself. That would work,
347 // but cause an unnecessary number of mutex operations.
348 // Just build the equivalent one.
349 if rt, ok := src.(*reuseTokenSource); ok {
350 if t == nil {
351 // Just use it directly.
352 return rt
353 }
354 src = rt.new
355 }
356 return &reuseTokenSource{
357 t: t,
358 new: src,
359 }
360}