docs/index.rst - airflow-flask-openid-fork - Git at Google

 Flask-OpenID
 ============

 .. module:: flask_openid

 Flask-OpenID is an extension to `Flask`_ that allows you to add `OpenID`_
 based authentication to your website in a matter of minutes.  It depends
 on Flask and `python-openid`_ 2.x.  You can install the requirements from
 PyPI with `easy_install` or `pip` or download them by hand.

 Features
 --------

 - support for OpenID 2.x
 - friendly API
 - perfect integration into Flask
 - basic support for AX and SReg extensions to OpenID that make it possible
   to fetch basic profile information from a user's OpenID provider.

 Installation
 ------------

 Install the extension with one of the following commands::

     $ easy_install Flask-OpenID

 or alternatively if you have `pip` installed::

     $ pip install Flask-OpenID

 How to Use
 ----------

 To integrate Flask-OpenID into your application you need to create an
 instance of the :class:`OpenID` object first::

     from flask.ext.openid import OpenID
     oid = OpenID(app, '/path/to/store', safe_roots=[])

 By default it will use the filesystem as store for information needed by
 OpenID for the authentication process.  You can alternatively implement
 your own store that uses the database or a no-sql server.  For more
 information about that, consult the python-openid documentation.

 The path to the store can also be specified with the
 ``OPENID_FS_STORE_PATH`` configuration variable.

 Alternatively the object can be instantiated without the application in
 which case it can later be registered for an application with the
 :meth:`~OpenID.init_app` method.

 The list of URL roots that are safe to redirect the user to are passed via
 `safe_roots`. Whenever the url root of the ``'next'`` request argument is not in
 this list, the user will get redirected to the app root. All urls that are local
 to the current app are always regared as trusted. This security mechanism
 can be disabled by  leaving `safe_roots` out, but this is not suggested.

 The current logged in user has to be memorized somewhere, we will use the
 ``'openid'`` key in the `session`.  This can be implemented in a
 `before_request` function::

     from flask import g, session

     @app.before_request
     def lookup_current_user():
         g.user = None
         if 'openid' in session:
             openid = session['openid']
             g.user = User.query.filter_by(openid=openid).first()

 This assumes the openid used for a user is stored in the user table
 itself.  As you can see from the example above, we're using SQLAlchemy
 here, but feel free to use a different storage backend.  It's just
 important that you can somehow map from openid URL to user.

 Next you need to define a login handling function.  This function is a
 standard view function that is additionally decorated as
 :meth:`~OpenID.loginhandler`::

     @app.route('/login', methods=['GET', 'POST'])
     @oid.loginhandler
     def login():
         if g.user is not None:
             return redirect(oid.get_next_url())
         if request.method == 'POST':
             openid = request.form.get('openid')
             if openid:
                 return oid.try_login(openid, ask_for=['email', 'nickname'],
                                              ask_for_optional=['fullname'])
         return render_template('login.html', next=oid.get_next_url(),
                                error=oid.fetch_error())

 What's happening inside the login handler is that first we try to figure
 out if the user is already logged in.  In that case we return to where we
 just came from (:meth:`~OpenID.get_next_url` can do that for us).  When
 the data is submitted we get the openid the user entered and try to login
 with that information.  Additionally we ask the openid provider for email,
 nickname and the user's full name, where we declare full name as optional.
 If that information is available, we can use it to simplify the account
 creation process in our application.

 The template also needs the URL we want to return to, because it has to
 forward that information in the form.  If an error happened,
 :meth:`~OpenID.fetch_error` will return that error message for us.

 This is what a login template typically looks like:

 .. sourcecode:: html+jinja

     {% extends "layout.html" %}
     {% block title %}Sign in{% endblock %}
     {% block body %}
       <h2>Sign in</h2>
       <form action="" method=post>
         {% if error %}<p class=error><strong>Error:</strong> {{ error }}</p>{% endif %}
         <p>
           OpenID:
           <input type=text name=openid size=30>
           <input type=submit value="Sign in">
           <input type=hidden name=next value="{{ next }}">
       </form>
     {% endblock %}

 See how `error` and `next` are used.  The name of the form field `next` is
 required, so don't change it.

 Responding to Successful Logins
 -------------------------------

 Next we have to define a function that is called after the login was
 successful.  The responsibility of that function is to remember the user
 that just logged in and to figure out if it's a new user to the system or
 one with an existing profile (if you want to use profiles).

 Such a function is decorated with :meth:`~OpenID.after_login` and must
 remember the user in the session and redirect to the proper page::

     from flask import flash

     @oid.after_login
     def create_or_login(resp):
         session['openid'] = resp.identity_url
         user = User.query.filter_by(openid=resp.identity_url).first()
         if user is not None:
             flash(u'Successfully signed in')
             g.user = user
             return redirect(oid.get_next_url())
         return redirect(url_for('create_profile', next=oid.get_next_url(),
                                 name=resp.fullname or resp.nickname,
                                 email=resp.email))

 The `resp` object passed is a :class:`OpenIDResponse` object with all the
 information you might desire.  As you can see, we memorize the user's
 openid and try to get the user with that OpenID from the database.  If
 that fails we redirect the user to a page to create a new profile and also
 forward the name (or nickname if no name is provided) and the email
 address.  Please keep in mind that an openid provider does not have to
 support these profile information and not every value you ask for will be
 there.  If it's missing it will be `None`.  Again make sure to not lose
 the information about the next URL.

 Creating a Profile
 ------------------

 A typical page to create such a profile might look like this::

     @app.route('/create-profile', methods=['GET', 'POST'])
     def create_profile():
         if g.user is not None or 'openid' not in session:
             return redirect(url_for('index'))
         if request.method == 'POST':
             name = request.form['name']
             email = request.form['email']
             if not name:
                 flash(u'Error: you have to provide a name')
             elif '@' not in email:
                 flash(u'Error: you have to enter a valid email address')
             else:
                 flash(u'Profile successfully created')
                 db_session.add(User(name, email, session['openid']))
                 db_session.commit()
                 return redirect(oid.get_next_url())
         return render_template('create_profile.html', next=oid.get_next_url())

 If you're using the same names for the URL parameters in the step before
 and in this form, you have nice looking and simple templates:

 .. sourcecode:: html+jinja

     {% extends "layout.html" %}
     {% block title %}Create Profile{% endblock %}
     {% block body %}
       <h2>Create Profile</h2>
       <p>
         Hey!  This is the first time you signed in on this website.  In
         order to proceed we need a couple of more information from you:
       <form action="" method=post>
         <dl>
           <dt>Name:
           <dd><input type=text name=name size=30 value="{{ request.values.name }}">
           <dt>E-Mail:
           <dd><input type=text name=email size=30 value="{{ request.values.email }}">
         </dl>
         <p>
           <input type=submit value="Create profile">
           <input type=hidden name=next value="{{ next }}">
       </form>
       <p>
         If you don't want to proceed, you can <a href="{{ url_for('logout')
         }}">sign out</a> again.
     {% endblock %}

 Logging Out
 -----------

 The logout function is very simple, it just has to unset the openid from
 the session and redirect back to where the user was before::

     @app.route('/logout')
     def logout():
         session.pop('openid', None)
         flash(u'You were signed out')
         return redirect(oid.get_next_url())

 Advanced usage
 --------------

 Flask-OpenID can also work with any python-openid extension.
 To use this, pass a list of instantiated request openid.extension.Extension
 objects in the `extensions` field of :meth:`~OpenID.try_login`.
 The responses of these extensions are available during the :meth:`after_login`
 function, as entries in resp.extensions.

 Full Example
 ------------

 To see the full code of that example, you can download the code `from
 github <http://github.com/mitsuhiko/flask-openid>`_.

 Changes
 -------

 1.2
 ```

 -   The safe_roots argument and URL security system was added.

 -   The OpenID extensions system was added.

 1.0
 ```

 -   the OpenID object is not registered to an application which allows
     configuration values to be used and is also consistent with other
     Flask extensions.

 API References
 --------------

 The full API reference:

 .. autoclass:: OpenID
    :members:

 .. autoclass:: OpenIDResponse
    :members:

 .. data:: COMMON_PROVIDERS

    a dictionary of common provider name -> login URL mappings.  This can
    be used to implement "click button to login" functionality.

    Currently contains general purpose entrypoints for the following
    providers: ``google``, ``yahoo``, ``aol``, and ``steam``.

 .. _Flask: http://flask.pocoo.org/
 .. _OpenID: http://openid.net/
 .. _python-openid: http://openidenabled.com/python-openid/
	Flask-OpenID
	============

	.. module:: flask_openid

	Flask-OpenID is an extension to `Flask`_ that allows you to add `OpenID`_
	based authentication to your website in a matter of minutes. It depends
	on Flask and `python-openid`_ 2.x. You can install the requirements from
	PyPI with `easy_install` or `pip` or download them by hand.

	Features
	--------

	- support for OpenID 2.x
	- friendly API
	- perfect integration into Flask
	- basic support for AX and SReg extensions to OpenID that make it possible
	to fetch basic profile information from a user's OpenID provider.

	Installation
	------------

	Install the extension with one of the following commands::

	$ easy_install Flask-OpenID

	or alternatively if you have `pip` installed::

	$ pip install Flask-OpenID

	How to Use
	----------

	To integrate Flask-OpenID into your application you need to create an
	instance of the :class:`OpenID` object first::

	from flask.ext.openid import OpenID
	oid = OpenID(app, '/path/to/store', safe_roots=[])

	By default it will use the filesystem as store for information needed by
	OpenID for the authentication process. You can alternatively implement
	your own store that uses the database or a no-sql server. For more
	information about that, consult the python-openid documentation.

	The path to the store can also be specified with the
	``OPENID_FS_STORE_PATH`` configuration variable.

	Alternatively the object can be instantiated without the application in
	which case it can later be registered for an application with the
	:meth:`~OpenID.init_app` method.

	The list of URL roots that are safe to redirect the user to are passed via
	`safe_roots`. Whenever the url root of the ``'next'`` request argument is not in
	this list, the user will get redirected to the app root. All urls that are local
	to the current app are always regared as trusted. This security mechanism
	can be disabled by leaving `safe_roots` out, but this is not suggested.

	The current logged in user has to be memorized somewhere, we will use the
	``'openid'`` key in the `session`. This can be implemented in a
	`before_request` function::

	from flask import g, session

	@app.before_request
	def lookup_current_user():
	g.user = None
	if 'openid' in session:
	openid = session['openid']
	g.user = User.query.filter_by(openid=openid).first()

	This assumes the openid used for a user is stored in the user table
	itself. As you can see from the example above, we're using SQLAlchemy
	here, but feel free to use a different storage backend. It's just
	important that you can somehow map from openid URL to user.

	Next you need to define a login handling function. This function is a
	standard view function that is additionally decorated as
	:meth:`~OpenID.loginhandler`::

	@app.route('/login', methods=['GET', 'POST'])
	@oid.loginhandler
	def login():
	if g.user is not None:
	return redirect(oid.get_next_url())
	if request.method == 'POST':
	openid = request.form.get('openid')
	if openid:
	return oid.try_login(openid, ask_for=['email', 'nickname'],
	ask_for_optional=['fullname'])
	return render_template('login.html', next=oid.get_next_url(),
	error=oid.fetch_error())

	What's happening inside the login handler is that first we try to figure
	out if the user is already logged in. In that case we return to where we
	just came from (:meth:`~OpenID.get_next_url` can do that for us). When
	the data is submitted we get the openid the user entered and try to login
	with that information. Additionally we ask the openid provider for email,
	nickname and the user's full name, where we declare full name as optional.
	If that information is available, we can use it to simplify the account
	creation process in our application.

	The template also needs the URL we want to return to, because it has to
	forward that information in the form. If an error happened,
	:meth:`~OpenID.fetch_error` will return that error message for us.

	This is what a login template typically looks like:

	.. sourcecode:: html+jinja

	{% extends "layout.html" %}
	{% block title %}Sign in{% endblock %}
	{% block body %}
	<h2>Sign in</h2>
	<form action="" method=post>
	{% if error %}<p class=error><strong>Error:</strong> {{ error }}</p>{% endif %}
	<p>
	OpenID:
	<input type=text name=openid size=30>
	<input type=submit value="Sign in">
	<input type=hidden name=next value="{{ next }}">
	</form>
	{% endblock %}

	See how `error` and `next` are used. The name of the form field `next` is
	required, so don't change it.

	Responding to Successful Logins
	-------------------------------

	Next we have to define a function that is called after the login was
	successful. The responsibility of that function is to remember the user
	that just logged in and to figure out if it's a new user to the system or
	one with an existing profile (if you want to use profiles).

	Such a function is decorated with :meth:`~OpenID.after_login` and must
	remember the user in the session and redirect to the proper page::

	from flask import flash

	@oid.after_login
	def create_or_login(resp):
	session['openid'] = resp.identity_url
	user = User.query.filter_by(openid=resp.identity_url).first()
	if user is not None:
	flash(u'Successfully signed in')
	g.user = user
	return redirect(oid.get_next_url())
	return redirect(url_for('create_profile', next=oid.get_next_url(),
	name=resp.fullname or resp.nickname,
	email=resp.email))

	The `resp` object passed is a :class:`OpenIDResponse` object with all the
	information you might desire. As you can see, we memorize the user's
	openid and try to get the user with that OpenID from the database. If
	that fails we redirect the user to a page to create a new profile and also
	forward the name (or nickname if no name is provided) and the email
	address. Please keep in mind that an openid provider does not have to
	support these profile information and not every value you ask for will be
	there. If it's missing it will be `None`. Again make sure to not lose
	the information about the next URL.

	Creating a Profile
	------------------

	A typical page to create such a profile might look like this::

	@app.route('/create-profile', methods=['GET', 'POST'])
	def create_profile():
	if g.user is not None or 'openid' not in session:
	return redirect(url_for('index'))
	if request.method == 'POST':
	name = request.form['name']
	email = request.form['email']
	if not name:
	flash(u'Error: you have to provide a name')
	elif '@' not in email:
	flash(u'Error: you have to enter a valid email address')
	else:
	flash(u'Profile successfully created')
	db_session.add(User(name, email, session['openid']))
	db_session.commit()
	return redirect(oid.get_next_url())
	return render_template('create_profile.html', next=oid.get_next_url())

	If you're using the same names for the URL parameters in the step before
	and in this form, you have nice looking and simple templates:

	.. sourcecode:: html+jinja

	{% extends "layout.html" %}
	{% block title %}Create Profile{% endblock %}
	{% block body %}
	<h2>Create Profile</h2>
	<p>
	Hey! This is the first time you signed in on this website. In
	order to proceed we need a couple of more information from you:
	<form action="" method=post>
	<dl>
	<dt>Name:
	<dd><input type=text name=name size=30 value="{{ request.values.name }}">
	<dt>E-Mail:
	<dd><input type=text name=email size=30 value="{{ request.values.email }}">
	</dl>
	<p>
	<input type=submit value="Create profile">
	<input type=hidden name=next value="{{ next }}">
	</form>
	<p>
	If you don't want to proceed, you can <a href="{{ url_for('logout')
	}}">sign out</a> again.
	{% endblock %}

	Logging Out
	-----------

	The logout function is very simple, it just has to unset the openid from
	the session and redirect back to where the user was before::

	@app.route('/logout')
	def logout():
	session.pop('openid', None)
	flash(u'You were signed out')
	return redirect(oid.get_next_url())

	Advanced usage
	--------------

	Flask-OpenID can also work with any python-openid extension.
	To use this, pass a list of instantiated request openid.extension.Extension
	objects in the `extensions` field of :meth:`~OpenID.try_login`.
	The responses of these extensions are available during the :meth:`after_login`
	function, as entries in resp.extensions.

	Full Example
	------------

	To see the full code of that example, you can download the code `from
	github <http://github.com/mitsuhiko/flask-openid>`_.

	Changes
	-------

	1.2
	```

	- The safe_roots argument and URL security system was added.

	- The OpenID extensions system was added.

	1.0
	```

	- the OpenID object is not registered to an application which allows
	configuration values to be used and is also consistent with other
	Flask extensions.

	API References
	--------------

	The full API reference:

	.. autoclass:: OpenID
	:members:

	.. autoclass:: OpenIDResponse
	:members:

	.. data:: COMMON_PROVIDERS

	a dictionary of common provider name -> login URL mappings. This can
	be used to implement "click button to login" functionality.

	Currently contains general purpose entrypoints for the following
	providers: ``google``, ``yahoo``, ``aol``, and ``steam``.

	.. _Flask: http://flask.pocoo.org/
	.. _OpenID: http://openid.net/
	.. _python-openid: http://openidenabled.com/python-openid/