| # Copyright 2015 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. |
| |
| """Utilities for the Flask web framework |
| |
| Provides a Flask extension that makes using OAuth2 web server flow easier. |
| The extension includes views that handle the entire auth flow and a |
| ``@required`` decorator to automatically ensure that user credentials are |
| available. |
| |
| |
| Configuration |
| ============= |
| |
| To configure, you'll need a set of OAuth2 web application credentials from the |
| `Google Developer's Console <https://console.developers.google.com/project/_/\ |
| apiui/credential>`__. |
| |
| .. code-block:: python |
| |
| from oauth2client.contrib.flask_util import UserOAuth2 |
| |
| app = Flask(__name__) |
| |
| app.config['SECRET_KEY'] = 'your-secret-key' |
| |
| app.config['GOOGLE_OAUTH2_CLIENT_SECRETS_FILE'] = 'client_secrets.json' |
| |
| # or, specify the client id and secret separately |
| app.config['GOOGLE_OAUTH2_CLIENT_ID'] = 'your-client-id' |
| app.config['GOOGLE_OAUTH2_CLIENT_SECRET'] = 'your-client-secret' |
| |
| oauth2 = UserOAuth2(app) |
| |
| |
| Usage |
| ===== |
| |
| Once configured, you can use the :meth:`UserOAuth2.required` decorator to |
| ensure that credentials are available within a view. |
| |
| .. code-block:: python |
| :emphasize-lines: 3,7,10 |
| |
| # Note that app.route should be the outermost decorator. |
| @app.route('/needs_credentials') |
| @oauth2.required |
| def example(): |
| # http is authorized with the user's credentials and can be used |
| # to make http calls. |
| http = oauth2.http() |
| |
| # Or, you can access the credentials directly |
| credentials = oauth2.credentials |
| |
| If you want credentials to be optional for a view, you can leave the decorator |
| off and use :meth:`UserOAuth2.has_credentials` to check. |
| |
| .. code-block:: python |
| :emphasize-lines: 3 |
| |
| @app.route('/optional') |
| def optional(): |
| if oauth2.has_credentials(): |
| return 'Credentials found!' |
| else: |
| return 'No credentials!' |
| |
| |
| When credentials are available, you can use :attr:`UserOAuth2.email` and |
| :attr:`UserOAuth2.user_id` to access information from the `ID Token |
| <https://developers.google.com/identity/protocols/OpenIDConnect?hl=en>`__, if |
| available. |
| |
| .. code-block:: python |
| :emphasize-lines: 4 |
| |
| @app.route('/info') |
| @oauth2.required |
| def info(): |
| return "Hello, {} ({})".format(oauth2.email, oauth2.user_id) |
| |
| |
| URLs & Trigging Authorization |
| ============================= |
| |
| The extension will add two new routes to your application: |
| |
| * ``"oauth2.authorize"`` -> ``/oauth2authorize`` |
| * ``"oauth2.callback"`` -> ``/oauth2callback`` |
| |
| When configuring your OAuth2 credentials on the Google Developer's Console, be |
| sure to add ``http[s]://[your-app-url]/oauth2callback`` as an authorized |
| callback url. |
| |
| Typically you don't not need to use these routes directly, just be sure to |
| decorate any views that require credentials with ``@oauth2.required``. If |
| needed, you can trigger authorization at any time by redirecting the user |
| to the URL returned by :meth:`UserOAuth2.authorize_url`. |
| |
| .. code-block:: python |
| :emphasize-lines: 3 |
| |
| @app.route('/login') |
| def login(): |
| return oauth2.authorize_url("/") |
| |
| |
| Incremental Auth |
| ================ |
| |
| This extension also supports `Incremental Auth <https://developers.google.com\ |
| /identity/protocols/OAuth2WebServer?hl=en#incrementalAuth>`__. To enable it, |
| configure the extension with ``include_granted_scopes``. |
| |
| .. code-block:: python |
| |
| oauth2 = UserOAuth2(app, include_granted_scopes=True) |
| |
| Then specify any additional scopes needed on the decorator, for example: |
| |
| .. code-block:: python |
| :emphasize-lines: 2,7 |
| |
| @app.route('/drive') |
| @oauth2.required(scopes=["https://www.googleapis.com/auth/drive"]) |
| def requires_drive(): |
| ... |
| |
| @app.route('/calendar') |
| @oauth2.required(scopes=["https://www.googleapis.com/auth/calendar"]) |
| def requires_calendar(): |
| ... |
| |
| The decorator will ensure that the the user has authorized all specified scopes |
| before allowing them to access the view, and will also ensure that credentials |
| do not lose any previously authorized scopes. |
| |
| |
| Storage |
| ======= |
| |
| By default, the extension uses a Flask session-based storage solution. This |
| means that credentials are only available for the duration of a session. It |
| also means that with Flask's default configuration, the credentials will be |
| visible in the session cookie. It's highly recommended to use database-backed |
| session and to use https whenever handling user credentials. |
| |
| If you need the credentials to be available longer than a user session or |
| available outside of a request context, you will need to implement your own |
| :class:`oauth2client.Storage`. |
| """ |
| |
| from functools import wraps |
| import hashlib |
| import json |
| import os |
| import pickle |
| |
| try: |
| from flask import Blueprint |
| from flask import _app_ctx_stack |
| from flask import current_app |
| from flask import redirect |
| from flask import request |
| from flask import session |
| from flask import url_for |
| except ImportError: # pragma: NO COVER |
| raise ImportError('The flask utilities require flask 0.9 or newer.') |
| |
| import httplib2 |
| import six.moves.http_client as httplib |
| |
| from oauth2client import client |
| from oauth2client import clientsecrets |
| from oauth2client.contrib import dictionary_storage |
| |
| |
| __author__ = 'jonwayne@google.com (Jon Wayne Parrott)' |
| |
| _DEFAULT_SCOPES = ('email',) |
| _CREDENTIALS_KEY = 'google_oauth2_credentials' |
| _FLOW_KEY = 'google_oauth2_flow_{0}' |
| _CSRF_KEY = 'google_oauth2_csrf_token' |
| |
| |
| def _get_flow_for_token(csrf_token): |
| """Retrieves the flow instance associated with a given CSRF token from |
| the Flask session.""" |
| flow_pickle = session.pop( |
| _FLOW_KEY.format(csrf_token), None) |
| |
| if flow_pickle is None: |
| return None |
| else: |
| return pickle.loads(flow_pickle) |
| |
| |
| class UserOAuth2(object): |
| """Flask extension for making OAuth 2.0 easier. |
| |
| Configuration values: |
| |
| * ``GOOGLE_OAUTH2_CLIENT_SECRETS_FILE`` path to a client secrets json |
| file, obtained from the credentials screen in the Google Developers |
| console. |
| * ``GOOGLE_OAUTH2_CLIENT_ID`` the oauth2 credentials' client ID. This |
| is only needed if ``GOOGLE_OAUTH2_CLIENT_SECRETS_FILE`` is not |
| specified. |
| * ``GOOGLE_OAUTH2_CLIENT_SECRET`` the oauth2 credentials' client |
| secret. This is only needed if ``GOOGLE_OAUTH2_CLIENT_SECRETS_FILE`` |
| is not specified. |
| |
| If app is specified, all arguments will be passed along to init_app. |
| |
| If no app is specified, then you should call init_app in your application |
| factory to finish initialization. |
| """ |
| |
| def __init__(self, app=None, *args, **kwargs): |
| self.app = app |
| if app is not None: |
| self.init_app(app, *args, **kwargs) |
| |
| def init_app(self, app, scopes=None, client_secrets_file=None, |
| client_id=None, client_secret=None, authorize_callback=None, |
| storage=None, **kwargs): |
| """Initialize this extension for the given app. |
| |
| Arguments: |
| app: A Flask application. |
| scopes: Optional list of scopes to authorize. |
| client_secrets_file: Path to a file containing client secrets. You |
| can also specify the GOOGLE_OAUTH2_CLIENT_SECRETS_FILE config |
| value. |
| client_id: If not specifying a client secrets file, specify the |
| OAuth2 client id. You can also specify the |
| GOOGLE_OAUTH2_CLIENT_ID config value. You must also provide a |
| client secret. |
| client_secret: The OAuth2 client secret. You can also specify the |
| GOOGLE_OAUTH2_CLIENT_SECRET config value. |
| authorize_callback: A function that is executed after successful |
| user authorization. |
| storage: A oauth2client.client.Storage subclass for storing the |
| credentials. By default, this is a Flask session based storage. |
| kwargs: Any additional args are passed along to the Flow |
| constructor. |
| """ |
| self.app = app |
| self.authorize_callback = authorize_callback |
| self.flow_kwargs = kwargs |
| |
| if storage is None: |
| storage = dictionary_storage.DictionaryStorage( |
| session, key=_CREDENTIALS_KEY) |
| self.storage = storage |
| |
| if scopes is None: |
| scopes = app.config.get('GOOGLE_OAUTH2_SCOPES', _DEFAULT_SCOPES) |
| self.scopes = scopes |
| |
| self._load_config(client_secrets_file, client_id, client_secret) |
| |
| app.register_blueprint(self._create_blueprint()) |
| |
| def _load_config(self, client_secrets_file, client_id, client_secret): |
| """Loads oauth2 configuration in order of priority. |
| |
| Priority: |
| 1. Config passed to the constructor or init_app. |
| 2. Config passed via the GOOGLE_OAUTH2_CLIENT_SECRETS_FILE app |
| config. |
| 3. Config passed via the GOOGLE_OAUTH2_CLIENT_ID and |
| GOOGLE_OAUTH2_CLIENT_SECRET app config. |
| |
| Raises: |
| ValueError if no config could be found. |
| """ |
| if client_id and client_secret: |
| self.client_id, self.client_secret = client_id, client_secret |
| return |
| |
| if client_secrets_file: |
| self._load_client_secrets(client_secrets_file) |
| return |
| |
| if 'GOOGLE_OAUTH2_CLIENT_SECRETS_FILE' in self.app.config: |
| self._load_client_secrets( |
| self.app.config['GOOGLE_OAUTH2_CLIENT_SECRETS_FILE']) |
| return |
| |
| try: |
| self.client_id, self.client_secret = ( |
| self.app.config['GOOGLE_OAUTH2_CLIENT_ID'], |
| self.app.config['GOOGLE_OAUTH2_CLIENT_SECRET']) |
| except KeyError: |
| raise ValueError( |
| 'OAuth2 configuration could not be found. Either specify the ' |
| 'client_secrets_file or client_id and client_secret or set ' |
| 'the app configuration variables ' |
| 'GOOGLE_OAUTH2_CLIENT_SECRETS_FILE or ' |
| 'GOOGLE_OAUTH2_CLIENT_ID and GOOGLE_OAUTH2_CLIENT_SECRET.') |
| |
| def _load_client_secrets(self, filename): |
| """Loads client secrets from the given filename.""" |
| client_type, client_info = clientsecrets.loadfile(filename) |
| if client_type != clientsecrets.TYPE_WEB: |
| raise ValueError( |
| 'The flow specified in {0} is not supported.'.format( |
| client_type)) |
| |
| self.client_id = client_info['client_id'] |
| self.client_secret = client_info['client_secret'] |
| |
| def _make_flow(self, return_url=None, **kwargs): |
| """Creates a Web Server Flow""" |
| # Generate a CSRF token to prevent malicious requests. |
| csrf_token = hashlib.sha256(os.urandom(1024)).hexdigest() |
| |
| session[_CSRF_KEY] = csrf_token |
| |
| state = json.dumps({ |
| 'csrf_token': csrf_token, |
| 'return_url': return_url |
| }) |
| |
| kw = self.flow_kwargs.copy() |
| kw.update(kwargs) |
| |
| extra_scopes = kw.pop('scopes', []) |
| scopes = set(self.scopes).union(set(extra_scopes)) |
| |
| flow = client.OAuth2WebServerFlow( |
| client_id=self.client_id, |
| client_secret=self.client_secret, |
| scope=scopes, |
| state=state, |
| redirect_uri=url_for('oauth2.callback', _external=True), |
| **kw) |
| |
| flow_key = _FLOW_KEY.format(csrf_token) |
| session[flow_key] = pickle.dumps(flow) |
| |
| return flow |
| |
| def _create_blueprint(self): |
| bp = Blueprint('oauth2', __name__) |
| bp.add_url_rule('/oauth2authorize', 'authorize', self.authorize_view) |
| bp.add_url_rule('/oauth2callback', 'callback', self.callback_view) |
| |
| return bp |
| |
| def authorize_view(self): |
| """Flask view that starts the authorization flow. |
| |
| Starts flow by redirecting the user to the OAuth2 provider. |
| """ |
| args = request.args.to_dict() |
| |
| # Scopes will be passed as mutliple args, and to_dict() will only |
| # return one. So, we use getlist() to get all of the scopes. |
| args['scopes'] = request.args.getlist('scopes') |
| |
| return_url = args.pop('return_url', None) |
| if return_url is None: |
| return_url = request.referrer or '/' |
| |
| flow = self._make_flow(return_url=return_url, **args) |
| auth_url = flow.step1_get_authorize_url() |
| |
| return redirect(auth_url) |
| |
| def callback_view(self): |
| """Flask view that handles the user's return from OAuth2 provider. |
| |
| On return, exchanges the authorization code for credentials and stores |
| the credentials. |
| """ |
| if 'error' in request.args: |
| reason = request.args.get( |
| 'error_description', request.args.get('error', '')) |
| return ('Authorization failed: {0}'.format(reason), |
| httplib.BAD_REQUEST) |
| |
| try: |
| encoded_state = request.args['state'] |
| server_csrf = session[_CSRF_KEY] |
| code = request.args['code'] |
| except KeyError: |
| return 'Invalid request', httplib.BAD_REQUEST |
| |
| try: |
| state = json.loads(encoded_state) |
| client_csrf = state['csrf_token'] |
| return_url = state['return_url'] |
| except (ValueError, KeyError): |
| return 'Invalid request state', httplib.BAD_REQUEST |
| |
| if client_csrf != server_csrf: |
| return 'Invalid request state', httplib.BAD_REQUEST |
| |
| flow = _get_flow_for_token(server_csrf) |
| |
| if flow is None: |
| return 'Invalid request state', httplib.BAD_REQUEST |
| |
| # Exchange the auth code for credentials. |
| try: |
| credentials = flow.step2_exchange(code) |
| except client.FlowExchangeError as exchange_error: |
| current_app.logger.exception(exchange_error) |
| content = 'An error occurred: {0}'.format(exchange_error) |
| return content, httplib.BAD_REQUEST |
| |
| # Save the credentials to the storage. |
| self.storage.put(credentials) |
| |
| if self.authorize_callback: |
| self.authorize_callback(credentials) |
| |
| return redirect(return_url) |
| |
| @property |
| def credentials(self): |
| """The credentials for the current user or None if unavailable.""" |
| ctx = _app_ctx_stack.top |
| |
| if not hasattr(ctx, _CREDENTIALS_KEY): |
| ctx.google_oauth2_credentials = self.storage.get() |
| |
| return ctx.google_oauth2_credentials |
| |
| def has_credentials(self): |
| """Returns True if there are valid credentials for the current user.""" |
| if not self.credentials: |
| return False |
| # Is the access token expired? If so, do we have an refresh token? |
| elif (self.credentials.access_token_expired and |
| not self.credentials.refresh_token): |
| return False |
| else: |
| return True |
| |
| @property |
| def email(self): |
| """Returns the user's email address or None if there are no credentials. |
| |
| The email address is provided by the current credentials' id_token. |
| This should not be used as unique identifier as the user can change |
| their email. If you need a unique identifier, use user_id. |
| """ |
| if not self.credentials: |
| return None |
| try: |
| return self.credentials.id_token['email'] |
| except KeyError: |
| current_app.logger.error( |
| 'Invalid id_token {0}'.format(self.credentials.id_token)) |
| |
| @property |
| def user_id(self): |
| """Returns the a unique identifier for the user |
| |
| Returns None if there are no credentials. |
| |
| The id is provided by the current credentials' id_token. |
| """ |
| if not self.credentials: |
| return None |
| try: |
| return self.credentials.id_token['sub'] |
| except KeyError: |
| current_app.logger.error( |
| 'Invalid id_token {0}'.format(self.credentials.id_token)) |
| |
| def authorize_url(self, return_url, **kwargs): |
| """Creates a URL that can be used to start the authorization flow. |
| |
| When the user is directed to the URL, the authorization flow will |
| begin. Once complete, the user will be redirected to the specified |
| return URL. |
| |
| Any kwargs are passed into the flow constructor. |
| """ |
| return url_for('oauth2.authorize', return_url=return_url, **kwargs) |
| |
| def required(self, decorated_function=None, scopes=None, |
| **decorator_kwargs): |
| """Decorator to require OAuth2 credentials for a view. |
| |
| If credentials are not available for the current user, then they will |
| be redirected to the authorization flow. Once complete, the user will |
| be redirected back to the original page. |
| """ |
| |
| def curry_wrapper(wrapped_function): |
| @wraps(wrapped_function) |
| def required_wrapper(*args, **kwargs): |
| return_url = decorator_kwargs.pop('return_url', request.url) |
| |
| requested_scopes = set(self.scopes) |
| if scopes is not None: |
| requested_scopes |= set(scopes) |
| if self.has_credentials(): |
| requested_scopes |= self.credentials.scopes |
| |
| requested_scopes = list(requested_scopes) |
| |
| # Does the user have credentials and does the credentials have |
| # all of the needed scopes? |
| if (self.has_credentials() and |
| self.credentials.has_scopes(requested_scopes)): |
| return wrapped_function(*args, **kwargs) |
| # Otherwise, redirect to authorization |
| else: |
| auth_url = self.authorize_url( |
| return_url, |
| scopes=requested_scopes, |
| **decorator_kwargs) |
| |
| return redirect(auth_url) |
| |
| return required_wrapper |
| |
| if decorated_function: |
| return curry_wrapper(decorated_function) |
| else: |
| return curry_wrapper |
| |
| def http(self, *args, **kwargs): |
| """Returns an authorized http instance. |
| |
| Can only be called if there are valid credentials for the user, such |
| as inside of a view that is decorated with @required. |
| |
| Args: |
| *args: Positional arguments passed to httplib2.Http constructor. |
| **kwargs: Positional arguments passed to httplib2.Http constructor. |
| |
| Raises: |
| ValueError if no credentials are available. |
| """ |
| if not self.credentials: |
| raise ValueError('No credentials available.') |
| return self.credentials.authorize(httplib2.Http(*args, **kwargs)) |