<p>The <ttclass="docutils literal"><spanclass="pre">django_openidconsumer</span></tt> package contains all of the code needed to set up
your Django application as an OpenID consumer. You can use it to allow OpenID
users to sign in to your site without having to create a new username and
password.</p>
<divclass="section">
<h2><aid="overview">Overview</a></h2>
<p>The OpenID consumer system consists of:</p>
<ulclass="simple">
<li>Views for you to hook in to your application.</li>
<li>Database models implementing the persistence layer of an OpenID consumer.</li>
<li>Middleware that makes <ttclass="docutils literal"><spanclass="pre">request.openid</span></tt> and <ttclass="docutils literal"><spanclass="pre">request.openids</span></tt>
properties available to your application views.</li>
</ul>
</div>
<divclass="section">
<h2><aid="dependencies">Dependencies</a></h2>
<p><ttclass="docutils literal"><spanclass="pre">django_openidconsumer</span></tt> uses the <aclass="reference"href="http://www.openidenabled.com/openid/libraries/python/">python-openid library</a>, which must be
installed separately somewhere on the Python path. You should install the 1.2.0
“combo” package which includes the <ttclass="docutils literal"><spanclass="pre">yadis</span></tt> and <ttclass="docutils literal"><spanclass="pre">urljr</span></tt> libraries.</p>
<p>The package also depends on the availability of Django’s <aclass="reference"href="http://www.djangoproject.com/documentation/sessions/">session support</a>.</p>
</div>
<divclass="section">
<h2><aid="installation">Installation</a></h2>
<p>Having ensured that both the <ttclass="docutils literal"><spanclass="pre">python-openid</span></tt> library and the <ttclass="docutils literal"><spanclass="pre">django_openidconsumer</span></tt> package are available on your Python path, you can
add OpenID consumer support to an application by doing the following:</p>
<olclass="arabic">
<li><pclass="first">Put <ttclass="docutils literal"><spanclass="pre">django_openidconsumer</span></tt> in your <ttclass="docutils literal"><spanclass="pre">INSTALLED_APPS</span></tt> setting.</p>
</li>
<li><pclass="first">Run the command <ttclass="docutils literal"><spanclass="pre">manage.py</span><spanclass="pre">syncdb</span></tt> to create the necessary tables.</p>
</li>
<li><pclass="first">Add <ttclass="docutils literal"><spanclass="pre">django_openidconsumer.middleware.OpenIDMiddleware</span></tt> to your list
of <ttclass="docutils literal"><spanclass="pre">MIDDLEWARE_CLASSES</span></tt>, somewhere after the Session middleware.</p>
</li>
<li><pclass="first">Add the following views to your urlconf:</p>
<p>You will then be able to browse to <ttclass="docutils literal"><spanclass="pre">example.com/openid/</span></tt> and sign in using
an OpenID.</p>
</div>
<divclass="section">
<h2><aid="using-the-openid-middleware">Using the OpenID middleware</a></h2>
<p>With the Middleware installed, your views will have access to the user’s OpenID
as the <ttclass="docutils literal"><spanclass="pre">request.openid</span></tt> property. This will be <ttclass="docutils literal"><spanclass="pre">None</span></tt> if the user has not
yet authenticated; otherwise it will be a <ttclass="docutils literal"><spanclass="pre">django_openidconsumer.util.OpenID</span></tt>
instance.</p>
<p>If you want the user’s OpenID as a string, call the <ttclass="docutils literal"><spanclass="pre">str()</span></tt> builtin on the
OpenID instance:</p>
<preclass="literal-block">
def example_view(request):
if request.openid:
return HttpResponse("OpenID is %s" % escape(str(request.openid)))
else:
return HttpResponse("No OpenID")
</pre>
<p>Users can sign in with more than one OpenID. This is supported by the
<ttclass="docutils literal"><spanclass="pre">request.openids</span></tt> property, which is a list of <ttclass="docutils literal"><spanclass="pre">OpenID</span></tt> objects in the order
in which they were authenticated. <ttclass="docutils literal"><spanclass="pre">request.openid</span></tt> merely returns the last
<p>Simple registration (or <aclass="reference"href="http://openid.net/specs/openid-simple-registration-extension-1_0.html">sreg</a>) is an extension to the OpenID specification
that allows you to request extra details about a user from their OpenID
provider. It is frequently used to pre-populate registration forms with
information such as the user’s name, e-mail address or date of birth.</p>
<p>Be aware that not all OpenID providers support sreg, and there is no guarantee
that the information you have requested will be returned. Simple registration
should be used as a convenience for your users rather than as a required step in
Full details are available in the <aclass="reference"href="http://openid.net/specs/openid-simple-registration-extension-1_0.html">spec</a>.</p>
<p>To request this information, pass the fields that you wish to retrieve as an
additional <ttclass="docutils literal"><spanclass="pre">sreg</span></tt> argument to the <ttclass="docutils literal"><spanclass="pre">django_openidconsumer.views.begin</span></tt> view:</p>
<dd>The template used to display an error message when something goes wrong.</dd>
</dl>
<p>You can over-ride the default templates by creating templates of the same name
and placing them somewhere on your template path. You can find the example
templates in the <ttclass="docutils literal"><spanclass="pre">django_openidconsumer/templates</span></tt> directory.</p>
<p>The OpenID specification strongly recommends that any OpenID registration form
has a <ttclass="docutils literal"><spanclass="pre">name</span></tt> attribute of <ttclass="docutils literal"><spanclass="pre">openid_url</span></tt> to aid browser autocompletion, and
displays the <aclass="reference"href="http://openid.net/login-bg.gif">OpenID logo</a> inline in the form field using the following CSS:</p>
<preclass="literal-block">
input.openid {
background: url(/path/to/login-bg.gif) no-repeat;
background-position: 0 50%;
padding-left: 16px;
}
</pre>
<p>By default, the package expects the <ttclass="docutils literal"><spanclass="pre">django_openidconsumer.views.complete</span></tt>
view to be located at <ttclass="docutils literal"><spanclass="pre">/openid/complete/</span></tt>. This is the view that the OpenID
provider will redirect the user to after they have authenticated. If you want to
put it somewhere else you can either pass an extra <ttclass="docutils literal"><spanclass="pre">redirect_to</span></tt> argument to
<ttclass="docutils literal"><spanclass="pre">django_openidconsumer.views.begin</span></tt> or add an <ttclass="docutils literal"><spanclass="pre">OPENID_REDIRECT_TO</span></tt> setting
to <ttclass="docutils literal"><spanclass="pre">settings.py</span></tt>.</p>
<p>You can pass a <ttclass="docutils literal"><spanclass="pre">?next=</span></tt> query string argument containing a relative URL to
the <ttclass="docutils literal"><spanclass="pre">begin</span></tt> view to control where the user will be redirected to having
returned to your site. You can also set the default redirection location
using the <ttclass="docutils literal"><spanclass="pre">OPENID_REDIRECT_NEXT</span></tt> setting; if you do set set a default the user
will be redirected to your homepage.</p>
</div>
<divclass="section">
<h2><aid="i-names">i-names</a></h2>
<p><aclass="reference"href="http://www.inames.net/">i-names</a> are part of the OpenID 2.0 specification, which is currently being
developed. They are supported by the python-openid library, and hence are also
supported by <ttclass="docutils literal"><spanclass="pre">django_openidconsumer</span></tt>. You can tell if an OpenID is an i-name
by checking the <ttclass="docutils literal"><spanclass="pre">request.openid.is_iname</span></tt> property.</p>
<p>If you wish to disable i-name support, you can do so by adding the following to
your <ttclass="docutils literal"><spanclass="pre">settings.py</span></tt>:</p>