| # Copyright 2010 Google Inc. All Rights Reserved. |
| # |
| # Licensed under the Apache License, Version 2.0 (the "License"); |
| # you may not use this file except in compliance with the License. |
| # You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, software |
| # distributed under the License is distributed on an "AS IS" BASIS, |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| # See the License for the specific language governing permissions and |
| # limitations under the License. |
| |
| """An OAuth2 client library. |
| |
| This library provides a client implementation of the OAuth2 protocol (see |
| http://code.google.com/apis/accounts/docs/OAuth2.html). |
| |
| **** Experimental API **** |
| |
| This module is experimental and is subject to modification or removal without |
| notice. |
| """ |
| |
| # This implementation is inspired by the implementation in |
| # http://code.google.com/p/google-api-python-client/source/browse/oauth2client/, |
| # with the following main differences: |
| # - This library uses the fancy_urllib monkey patch for urllib to correctly |
| # implement SSL certificate validation. |
| # - This library does not assume that client code is using the httplib2 library |
| # to make HTTP requests. |
| # - This library implements caching of access tokens independent of refresh |
| # tokens (in the python API client oauth2client, there is a single class that |
| # encapsulates both refresh and access tokens). |
| |
| |
| import cgi |
| import datetime |
| import errno |
| from hashlib import sha1 |
| import logging |
| import os |
| import tempfile |
| import threading |
| import urllib |
| import urllib2 |
| import urlparse |
| |
| from boto import cacerts |
| from third_party import fancy_urllib |
| |
| try: |
| import json |
| except ImportError: |
| try: |
| # Try to import from django, should work on App Engine |
| from django.utils import simplejson as json |
| except ImportError: |
| # Try for simplejson |
| import simplejson as json |
| |
| LOG = logging.getLogger('oauth2_client') |
| # Lock used for checking/exchanging refresh token, so multithreaded |
| # operation doesn't attempt concurrent refreshes. |
| token_exchange_lock = threading.Lock() |
| |
| class Error(Exception): |
| """Base exception for the OAuth2 module.""" |
| pass |
| |
| |
| class AccessTokenRefreshError(Error): |
| """Error trying to exchange a refresh token into an access token.""" |
| pass |
| |
| |
| class AuthorizationCodeExchangeError(Error): |
| """Error trying to exchange an authorization code into a refresh token.""" |
| pass |
| |
| |
| class TokenCache(object): |
| """Interface for OAuth2 token caches.""" |
| |
| def PutToken(self, key, value): |
| raise NotImplementedError |
| |
| def GetToken(self, key): |
| raise NotImplementedError |
| |
| |
| class NoopTokenCache(TokenCache): |
| """A stub implementation of TokenCache that does nothing.""" |
| |
| def PutToken(self, key, value): |
| pass |
| |
| def GetToken(self, key): |
| return None |
| |
| |
| class InMemoryTokenCache(TokenCache): |
| """An in-memory token cache. |
| |
| The cache is implemented by a python dict, and inherits the thread-safety |
| properties of dict. |
| """ |
| |
| def __init__(self): |
| super(InMemoryTokenCache, self).__init__() |
| self.cache = dict() |
| |
| def PutToken(self, key, value): |
| LOG.info('InMemoryTokenCache.PutToken: key=%s', key) |
| self.cache[key] = value |
| |
| def GetToken(self, key): |
| value = self.cache.get(key, None) |
| LOG.info('InMemoryTokenCache.GetToken: key=%s%s present', |
| key, ' not' if value is None else '') |
| return value |
| |
| |
| class FileSystemTokenCache(TokenCache): |
| """An implementation of a token cache that persists tokens on disk. |
| |
| Each token object in the cache is stored in serialized form in a separate |
| file. The cache file's name can be configured via a path pattern that is |
| parameterized by the key under which a value is cached and optionally the |
| current processes uid as obtained by os.getuid(). |
| |
| Since file names are generally publicly visible in the system, it is important |
| that the cache key does not leak information about the token's value. If |
| client code computes cache keys from token values, a cryptographically strong |
| one-way function must be used. |
| """ |
| |
| def __init__(self, path_pattern=None): |
| """Creates a FileSystemTokenCache. |
| |
| Args: |
| path_pattern: Optional string argument to specify the path pattern for |
| cache files. The argument should be a path with format placeholders |
| '%(key)s' and optionally '%(uid)s'. If the argument is omitted, the |
| default pattern |
| <tmpdir>/oauth2client-tokencache.%(uid)s.%(key)s |
| is used, where <tmpdir> is replaced with the system temp dir as |
| obtained from tempfile.gettempdir(). |
| """ |
| super(FileSystemTokenCache, self).__init__() |
| self.path_pattern = path_pattern |
| if not path_pattern: |
| self.path_pattern = os.path.join( |
| tempfile.gettempdir(), 'oauth2_client-tokencache.%(uid)s.%(key)s') |
| |
| def CacheFileName(self, key): |
| uid = '_' |
| try: |
| # os.getuid() doesn't seem to work in Windows |
| uid = str(os.getuid()) |
| except: |
| pass |
| return self.path_pattern % {'key': key, 'uid': uid} |
| |
| def PutToken(self, key, value): |
| """Serializes the value to the key's filename. |
| |
| To ensure that written tokens aren't leaked to a different users, we |
| a) unlink an existing cache file, if any (to ensure we don't fall victim |
| to symlink attacks and the like), |
| b) create a new file with O_CREAT | O_EXCL (to ensure nobody is trying to |
| race us) |
| If either of these steps fail, we simply give up (but log a warning). Not |
| caching access tokens is not catastrophic, and failure to create a file |
| can happen for either of the following reasons: |
| - someone is attacking us as above, in which case we want to default to |
| safe operation (not write the token); |
| - another legitimate process is racing us; in this case one of the two |
| will win and write the access token, which is fine; |
| - we don't have permission to remove the old file or write to the |
| specified directory, in which case we can't recover |
| |
| Args: |
| key: the refresh_token hash key to store. |
| value: the access_token value to serialize. |
| """ |
| |
| cache_file = self.CacheFileName(key) |
| LOG.info('FileSystemTokenCache.PutToken: key=%s, cache_file=%s', |
| key, cache_file) |
| try: |
| os.unlink(cache_file) |
| except: |
| # Ignore failure to unlink the file; if the file exists and can't be |
| # unlinked, the subsequent open with O_CREAT | O_EXCL will fail. |
| pass |
| |
| flags = os.O_RDWR | os.O_CREAT | os.O_EXCL |
| |
| # Accommodate Windows; stolen from python2.6/tempfile.py. |
| if hasattr(os, 'O_NOINHERIT'): |
| flags |= os.O_NOINHERIT |
| if hasattr(os, 'O_BINARY'): |
| flags |= os.O_BINARY |
| |
| try: |
| fd = os.open(cache_file, flags, 0600) |
| except (OSError, IOError), e: |
| LOG.warning('FileSystemTokenCache.PutToken: ' |
| 'Failed to create cache file %s: %s', cache_file, e) |
| return |
| f = os.fdopen(fd, 'w+b') |
| f.write(value.Serialize()) |
| f.close() |
| |
| def GetToken(self, key): |
| """Returns a deserialized access token from the key's filename.""" |
| value = None |
| cache_file = self.CacheFileName(key) |
| try: |
| f = open(cache_file) |
| value = AccessToken.UnSerialize(f.read()) |
| f.close() |
| except (IOError, OSError), e: |
| if e.errno != errno.ENOENT: |
| LOG.warning('FileSystemTokenCache.GetToken: ' |
| 'Failed to read cache file %s: %s', cache_file, e) |
| except Exception, e: |
| LOG.warning('FileSystemTokenCache.GetToken: ' |
| 'Failed to read cache file %s (possibly corrupted): %s', |
| cache_file, e) |
| |
| LOG.info('FileSystemTokenCache.GetToken: key=%s%s present (cache_file=%s)', |
| key, ' not' if value is None else '', cache_file) |
| return value |
| |
| |
| class OAuth2Provider(object): |
| """Encapsulates information about an OAuth2 provider.""" |
| |
| def __init__(self, label, authorization_uri, token_uri): |
| """Creates an OAuth2Provider. |
| |
| Args: |
| label: A string identifying this oauth2 provider, e.g. "Google". |
| authorization_uri: The provider's authorization URI. |
| token_uri: The provider's token endpoint URI. |
| """ |
| self.label = label |
| self.authorization_uri = authorization_uri |
| self.token_uri = token_uri |
| |
| |
| class OAuth2Client(object): |
| """An OAuth2 client.""" |
| |
| def __init__(self, provider, client_id, client_secret, |
| url_opener=None, |
| proxy=None, |
| access_token_cache=None, |
| datetime_strategy=datetime.datetime): |
| """Creates an OAuth2Client. |
| |
| Args: |
| provider: The OAuth2Provider provider this client will authenticate |
| against. |
| client_id: The OAuth2 client ID of this client. |
| client_secret: The OAuth2 client secret of this client. |
| url_opener: An optinal urllib2.OpenerDirector to use for making HTTP |
| requests to the OAuth2 provider's token endpoint. The provided |
| url_opener *must* be configured to validate server SSL certificates |
| for requests to https connections, and to correctly handle proxying of |
| https requests. If this argument is omitted or None, a suitable |
| opener based on fancy_urllib is used. |
| proxy: An optional string specifying a HTTP proxy to be used, in the form |
| '<proxy>:<port>'. This option is only effective if the url_opener has |
| been configured with a fancy_urllib.FancyProxyHandler (this is the |
| case for the default url_opener). |
| access_token_cache: An optional instance of a TokenCache. If omitted or |
| None, an InMemoryTokenCache is used. |
| datetime_strategy: datetime module strategy to use. |
| """ |
| self.provider = provider |
| self.client_id = client_id |
| self.client_secret = client_secret |
| # datetime_strategy is used to invoke utcnow() on; it is injected into the |
| # constructor for unit testing purposes. |
| self.datetime_strategy = datetime_strategy |
| self._proxy = proxy |
| |
| self.access_token_cache = access_token_cache or InMemoryTokenCache() |
| |
| self.ca_certs_file = os.path.join( |
| os.path.dirname(os.path.abspath(cacerts.__file__)), 'cacerts.txt') |
| |
| if url_opener is None: |
| # TODO(Google): set user agent? |
| url_opener = urllib2.build_opener( |
| fancy_urllib.FancyProxyHandler(), |
| fancy_urllib.FancyRedirectHandler(), |
| fancy_urllib.FancyHTTPSHandler()) |
| self.url_opener = url_opener |
| |
| def _TokenRequest(self, request): |
| """Make a requst to this client's provider's token endpoint. |
| |
| Args: |
| request: A dict with the request parameteres. |
| Returns: |
| A tuple (response, error) where, |
| - response is the parsed JSON response received from the token endpoint, |
| or None if no parseable response was received, and |
| - error is None if the request succeeded or |
| an Exception if an error occurred. |
| """ |
| |
| body = urllib.urlencode(request) |
| LOG.debug('_TokenRequest request: %s', body) |
| response = None |
| try: |
| request = fancy_urllib.FancyRequest( |
| self.provider.token_uri, data=body) |
| if self._proxy: |
| request.set_proxy(self._proxy, 'http') |
| |
| request.set_ssl_info(ca_certs=self.ca_certs_file) |
| result = self.url_opener.open(request) |
| resp_body = result.read() |
| LOG.debug('_TokenRequest response: %s', resp_body) |
| except urllib2.HTTPError, e: |
| try: |
| response = json.loads(e.read()) |
| except: |
| pass |
| return (response, e) |
| |
| try: |
| response = json.loads(resp_body) |
| except ValueError, e: |
| return (None, e) |
| |
| return (response, None) |
| |
| def GetAccessToken(self, refresh_token): |
| """Given a RefreshToken, obtains a corresponding access token. |
| |
| First, this client's access token cache is checked for an existing, |
| not-yet-expired access token for the provided refresh token. If none is |
| found, the client obtains a fresh access token for the provided refresh |
| token from the OAuth2 provider's token endpoint. |
| |
| Args: |
| refresh_token: The RefreshToken object which to get an access token for. |
| Returns: |
| The cached or freshly obtained AccessToken. |
| Raises: |
| AccessTokenRefreshError if an error occurs. |
| """ |
| # Ensure only one thread at a time attempts to get (and possibly refresh) |
| # the access token. This doesn't prevent concurrent refresh attempts across |
| # multiple gsutil instances, but at least protects against multiple threads |
| # simultaneously attempting to refresh when gsutil -m is used. |
| token_exchange_lock.acquire() |
| try: |
| cache_key = refresh_token.CacheKey() |
| LOG.info('GetAccessToken: checking cache for key %s', cache_key) |
| access_token = self.access_token_cache.GetToken(cache_key) |
| LOG.debug('GetAccessToken: token from cache: %s', access_token) |
| if access_token is None or access_token.ShouldRefresh(): |
| LOG.info('GetAccessToken: fetching fresh access token...') |
| access_token = self.FetchAccessToken(refresh_token) |
| LOG.debug('GetAccessToken: fresh access token: %s', access_token) |
| self.access_token_cache.PutToken(cache_key, access_token) |
| return access_token |
| finally: |
| token_exchange_lock.release() |
| |
| def FetchAccessToken(self, refresh_token): |
| """Fetches an access token from the provider's token endpoint. |
| |
| Given a RefreshToken, fetches an access token from this client's OAuth2 |
| provider's token endpoint. |
| |
| Args: |
| refresh_token: The RefreshToken object which to get an access token for. |
| Returns: |
| The fetched AccessToken. |
| Raises: |
| AccessTokenRefreshError: if an error occurs. |
| """ |
| request = { |
| 'grant_type': 'refresh_token', |
| 'client_id': self.client_id, |
| 'client_secret': self.client_secret, |
| 'refresh_token': refresh_token.refresh_token, |
| } |
| LOG.debug('FetchAccessToken request: %s', request) |
| |
| response, error = self._TokenRequest(request) |
| LOG.debug( |
| 'FetchAccessToken response (error = %s): %s', error, response) |
| |
| if error: |
| oauth2_error = '' |
| if response and response['error']: |
| oauth2_error = '; OAuth2 error: %s' % response['error'] |
| raise AccessTokenRefreshError( |
| 'Failed to exchange refresh token into access token; ' |
| 'request failed: %s%s' % (error, oauth2_error)) |
| |
| if 'access_token' not in response: |
| raise AccessTokenRefreshError( |
| 'Failed to exchange refresh token into access token; response: %s' % |
| response) |
| |
| token_expiry = None |
| if 'expires_in' in response: |
| token_expiry = ( |
| self.datetime_strategy.utcnow() + |
| datetime.timedelta(seconds=int(response['expires_in']))) |
| |
| return AccessToken(response['access_token'], token_expiry, |
| datetime_strategy=self.datetime_strategy) |
| |
| def GetAuthorizationUri(self, redirect_uri, scopes, extra_params=None): |
| """Gets the OAuth2 authorization URI and the specified scope(s). |
| |
| Applications should navigate/redirect the user's user agent to this URI. The |
| user will be shown an approval UI requesting the user to approve access of |
| this client to the requested scopes under the identity of the authenticated |
| end user. |
| |
| The application should expect the user agent to be redirected to the |
| specified redirect_uri after the user's approval/disapproval. |
| |
| Installed applications may use the special redirect_uri |
| 'urn:ietf:wg:oauth:2.0:oob' to indicate that instead of redirecting the |
| browser, the user be shown a confirmation page with a verification code. |
| The application should query the user for this code. |
| |
| Args: |
| redirect_uri: Either the string 'urn:ietf:wg:oauth:2.0:oob' for a |
| non-web-based application, or a URI that handles the callback from the |
| authorization server. |
| scopes: A list of strings specifying the OAuth scopes the application |
| requests access to. |
| extra_params: Optional dictionary of additional parameters to be passed to |
| the OAuth2 authorization URI. |
| Returns: |
| The authorization URI for the specified scopes as a string. |
| """ |
| |
| request = { |
| 'response_type': 'code', |
| 'client_id': self.client_id, |
| 'redirect_uri': redirect_uri, |
| 'scope': ' '.join(scopes), |
| } |
| |
| if extra_params: |
| request.update(extra_params) |
| url_parts = list(urlparse.urlparse(self.provider.authorization_uri)) |
| # 4 is the index of the query part |
| request.update(dict(cgi.parse_qsl(url_parts[4]))) |
| url_parts[4] = urllib.urlencode(request) |
| return urlparse.urlunparse(url_parts) |
| |
| def ExchangeAuthorizationCode(self, code, redirect_uri, scopes): |
| """Exchanges an authorization code for a refresh token. |
| |
| Invokes this client's OAuth2 provider's token endpoint to exchange an |
| authorization code into a refresh token. |
| |
| Args: |
| code: the authrorization code. |
| redirect_uri: Either the string 'urn:ietf:wg:oauth:2.0:oob' for a |
| non-web-based application, or a URI that handles the callback from the |
| authorization server. |
| scopes: A list of strings specifying the OAuth scopes the application |
| requests access to. |
| Returns: |
| A tuple consting of the resulting RefreshToken and AccessToken. |
| Raises: |
| AuthorizationCodeExchangeError: if an error occurs. |
| """ |
| request = { |
| 'grant_type': 'authorization_code', |
| 'client_id': self.client_id, |
| 'client_secret': self.client_secret, |
| 'code': code, |
| 'redirect_uri': redirect_uri, |
| 'scope': ' '.join(scopes), |
| } |
| LOG.debug('ExchangeAuthorizationCode request: %s', request) |
| |
| response, error = self._TokenRequest(request) |
| LOG.debug( |
| 'ExchangeAuthorizationCode response (error = %s): %s', |
| error, response) |
| |
| if error: |
| oauth2_error = '' |
| if response and response['error']: |
| oauth2_error = '; OAuth2 error: %s' % response['error'] |
| raise AuthorizationCodeExchangeError( |
| 'Failed to exchange refresh token into access token; ' |
| 'request failed: %s%s' % (str(error), oauth2_error)) |
| |
| if not 'access_token' in response: |
| raise AuthorizationCodeExchangeError( |
| 'Failed to exchange authorization code into access token; ' |
| 'response: %s' % response) |
| |
| token_expiry = None |
| if 'expires_in' in response: |
| token_expiry = ( |
| self.datetime_strategy.utcnow() + |
| datetime.timedelta(seconds=int(response['expires_in']))) |
| |
| access_token = AccessToken(response['access_token'], token_expiry, |
| datetime_strategy=self.datetime_strategy) |
| |
| refresh_token = None |
| refresh_token_string = response.get('refresh_token', None) |
| |
| token_exchange_lock.acquire() |
| try: |
| if refresh_token_string: |
| refresh_token = RefreshToken(self, refresh_token_string) |
| self.access_token_cache.PutToken(refresh_token.CacheKey(), access_token) |
| finally: |
| token_exchange_lock.release() |
| |
| return (refresh_token, access_token) |
| |
| |
| class AccessToken(object): |
| """Encapsulates an OAuth2 access token.""" |
| |
| def __init__(self, token, expiry, datetime_strategy=datetime.datetime): |
| self.token = token |
| self.expiry = expiry |
| self.datetime_strategy = datetime_strategy |
| |
| @staticmethod |
| def UnSerialize(query): |
| """Creates an AccessToken object from its serialized form.""" |
| |
| def GetValue(d, key): |
| return (d.get(key, [None]))[0] |
| kv = cgi.parse_qs(query) |
| if not kv['token']: |
| return None |
| expiry = None |
| expiry_tuple = GetValue(kv, 'expiry') |
| if expiry_tuple: |
| try: |
| expiry = datetime.datetime( |
| *[int(n) for n in expiry_tuple.split(',')]) |
| except: |
| return None |
| return AccessToken(GetValue(kv, 'token'), expiry) |
| |
| def Serialize(self): |
| """Serializes this object as URI-encoded key-value pairs.""" |
| # There's got to be a better way to serialize a datetime. Unfortunately, |
| # there is no reliable way to convert into a unix epoch. |
| kv = {'token': self.token} |
| if self.expiry: |
| t = self.expiry |
| tupl = (t.year, t.month, t.day, t.hour, t.minute, t.second, t.microsecond) |
| kv['expiry'] = ','.join([str(i) for i in tupl]) |
| return urllib.urlencode(kv) |
| |
| def ShouldRefresh(self, time_delta=300): |
| """Whether the access token needs to be refreshed. |
| |
| Args: |
| time_delta: refresh access token when it expires within time_delta secs. |
| |
| Returns: |
| True if the token is expired or about to expire, False if the |
| token should be expected to work. Note that the token may still |
| be rejected, e.g. if it has been revoked server-side. |
| """ |
| if self.expiry is None: |
| return False |
| return (self.datetime_strategy.utcnow() |
| + datetime.timedelta(seconds=time_delta) > self.expiry) |
| |
| def __eq__(self, other): |
| return self.token == other.token and self.expiry == other.expiry |
| |
| def __ne__(self, other): |
| return not self.__eq__(other) |
| |
| def __str__(self): |
| return 'AccessToken(token=%s, expiry=%sZ)' % (self.token, self.expiry) |
| |
| |
| class RefreshToken(object): |
| """Encapsulates an OAuth2 refresh token.""" |
| |
| def __init__(self, oauth2_client, refresh_token): |
| self.oauth2_client = oauth2_client |
| self.refresh_token = refresh_token |
| |
| def CacheKey(self): |
| """Computes a cache key for this refresh token. |
| |
| The cache key is computed as the SHA1 hash of the token, and as such |
| satisfies the FileSystemTokenCache requirement that cache keys do not leak |
| information about token values. |
| |
| Returns: |
| A hash key for this refresh token. |
| """ |
| h = sha1() |
| h.update(self.refresh_token) |
| return h.hexdigest() |
| |
| def GetAuthorizationHeader(self): |
| """Gets the access token HTTP authorication header value. |
| |
| Returns: |
| The value of an Authorization HTTP header that authenticates |
| requests with an OAuth2 access token based on this refresh token. |
| """ |
| return 'Bearer %s' % self.oauth2_client.GetAccessToken(self).token |
