sslobodr | d046be8 | 2019-01-16 10:02:22 -0500 | [diff] [blame] | 1 | // 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. |
| 9 | package oauth2 // import "golang.org/x/oauth2" |
| 10 | |
| 11 | import ( |
| 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. |
| 27 | var 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. |
| 37 | func 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). |
| 45 | type 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. |
| 67 | type 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. |
| 76 | type Endpoint struct { |
| 77 | AuthURL string |
| 78 | TokenURL string |
| 79 | } |
| 80 | |
| 81 | var ( |
| 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. |
| 103 | type AuthCodeOption interface { |
| 104 | setValue(url.Values) |
| 105 | } |
| 106 | |
| 107 | type setParam struct{ k, v string } |
| 108 | |
| 109 | func (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. |
| 113 | func 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. |
| 129 | func (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. |
| 168 | func (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. |
| 192 | func (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. |
| 210 | func (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. |
| 218 | func (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. |
| 234 | type 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. |
| 244 | func (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. |
| 267 | type 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. |
| 277 | func (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. |
| 294 | func StaticTokenSource(t *Token) TokenSource { |
| 295 | return staticTokenSource{t} |
| 296 | } |
| 297 | |
| 298 | // staticTokenSource is a TokenSource that always returns the same Token. |
| 299 | type staticTokenSource struct { |
| 300 | t *Token |
| 301 | } |
| 302 | |
| 303 | func (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. |
| 309 | var 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. |
| 321 | func 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. |
| 345 | func 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 | } |