~mhall119/django-openid-auth/provides-784239 : revision 3

1

The <tt class="docutils literal">django_openidconsumer</tt> package contains all of the code needed to set up

2

your Django application as an OpenID consumer. You can use it to allow OpenID

3

users to sign in to your site without having to create a new username and

4

password.

5

6

<h2><a id="overview">Overview</a></h2>

7

The OpenID consumer system consists of:

8

9

<li>Views for you to hook in to your application.</li>

10

<li>Database models implementing the persistence layer of an OpenID consumer.</li>

11

<li>Middleware that makes <tt class="docutils literal">request.openid</tt> and <tt class="docutils literal">request.openids</tt>

12

properties available to your application views.</li>

13

</ul>

14

</div>

15

16

<h2><a id="dependencies">Dependencies</a></h2>

17

<tt class="docutils literal">django_openidconsumer</tt> uses the <a class="reference" href="http://www.openidenabled.com/openid/libraries/python/">python-openid library</a>, which must be

18

installed separately somewhere on the Python path. You should install the 1.2.0

19

“combo” package which includes the <tt class="docutils literal">yadis</tt> and <tt class="docutils literal">urljr</tt> libraries.

20

The package also depends on the availability of Django’s <a class="reference" href="http://www.djangoproject.com/documentation/sessions/">session support</a>.

21

</div>

22

23

<h2><a id="installation">Installation</a></h2>

24

Having ensured that both the <tt class="docutils literal">python-openid</tt> library and the <tt class="docutils literal">django_openidconsumer</tt> package are available on your Python path, you can

25

add OpenID consumer support to an application by doing the following:

26

27

<li>Put <tt class="docutils literal">django_openidconsumer</tt> in your <tt class="docutils literal">INSTALLED_APPS</tt> setting.

28

</li>

29

<li>Run the command <tt class="docutils literal">manage.py syncdb</tt> to create the necessary tables.

30

</li>

31

<li>Add <tt class="docutils literal">django_openidconsumer.middleware.OpenIDMiddleware</tt> to your list

32

of <tt class="docutils literal">MIDDLEWARE_CLASSES</tt>, somewhere after the Session middleware.

33

</li>

34

<li>Add the following views to your urlconf:

35

36

(r'^openid/$', 'django_openidconsumer.views.begin'),

37

(r'^openid/complete/$', 'django_openidconsumer.views.complete'),

38

(r'^openid/signout/$', 'django_openidconsumer.views.signout'),

39

</pre>

40

</li>

41

</ol>

42

You will then be able to browse to <tt class="docutils literal">example.com/openid/</tt> and sign in using

43

an OpenID.

44

</div>

45

46

<h2><a id="using-the-openid-middleware">Using the OpenID middleware</a></h2>

47

With the Middleware installed, your views will have access to the user’s OpenID

48

as the <tt class="docutils literal">request.openid</tt> property. This will be <tt class="docutils literal">None</tt> if the user has not

49

yet authenticated; otherwise it will be a <tt class="docutils literal">django_openidconsumer.util.OpenID</tt>

50

instance.

51

If you want the user’s OpenID as a string, call the <tt class="docutils literal">str()</tt> builtin on the

52

OpenID instance:

53

54

def example_view(request):

55

if request.openid:

56

return HttpResponse("OpenID is %s" % escape(str(request.openid)))

57

else:

58

return HttpResponse("No OpenID")

59

</pre>

60

Users can sign in with more than one OpenID. This is supported by the

61

<tt class="docutils literal">request.openids</tt> property, which is a list of <tt class="docutils literal">OpenID</tt> objects in the order

62

in which they were authenticated. <tt class="docutils literal">request.openid</tt> merely returns the last

63

item in this list.

64

</div>

65

66

<h2><a id="using-simple-registration">Using simple registration</a></h2>

67

Simple registration (or <a class="reference" href="http://openid.net/specs/openid-simple-registration-extension-1_0.html">sreg</a>) is an extension to the OpenID specification

68

that allows you to request extra details about a user from their OpenID

69

provider. It is frequently used to pre-populate registration forms with

70

information such as the user’s name, e-mail address or date of birth.

71

Be aware that not all OpenID providers support sreg, and there is no guarantee

72

that the information you have requested will be returned. Simple registration

73

should be used as a convenience for your users rather than as a required step in

74

your authentication process.

75

Available simple registration fields are <tt class="docutils literal">nickname</tt>, <tt class="docutils literal">email</tt>, <tt class="docutils literal">fullname</tt>,

76

<tt class="docutils literal">dob</tt>, <tt class="docutils literal">gender</tt>, <tt class="docutils literal">postcode</tt>, <tt class="docutils literal">country</tt>, <tt class="docutils literal">language</tt> and <tt class="docutils literal">timezone</tt>.

77

Full details are available in the <a class="reference" href="http://openid.net/specs/openid-simple-registration-extension-1_0.html">spec</a>.

78

To request this information, pass the fields that you wish to retrieve as an

79

additional <tt class="docutils literal">sreg</tt> argument to the <tt class="docutils literal">django_openidconsumer.views.begin</tt> view:

80

81

(r'^openid/$', 'django_openidconsumer.views.begin', {

82

'sreg': 'email,nickname'

83

}),

84

</pre>

85

Any simple registration fields that are returned will be available in a

86

dictionary as the <tt class="docutils literal">sreg</tt> property of the OpenID object:

87

88

def example_sreg(request):

89

if request.openid and request.openid.sreg.has_key('email'):

90

return HttpResponse("Your e-mail address is: %s" % escape(

91

request.openid.sreg['email']

92

))

93

else:

94

return HttpResponse("No e-mail address")

95

</pre>

96

</div>

97

98

<h2><a id="customisation">Customisation</a></h2>

99

<tt class="docutils literal">django_openidconsumer</tt> uses two templates:

100

101

<dt><tt class="docutils literal">openid_signin.html</tt></dt>

102

<dd>The form presented to the user when they sign in.</dd>

103

<dt><tt class="docutils literal">openid_failure.html</tt></dt>

104

<dd>The template used to display an error message when something goes wrong.</dd>

105

</dl>

106

You can over-ride the default templates by creating templates of the same name

107

and placing them somewhere on your template path. You can find the example

108

templates in the <tt class="docutils literal">django_openidconsumer/templates</tt> directory.

109

The OpenID specification strongly recommends that any OpenID registration form

110

has a <tt class="docutils literal">name</tt> attribute of <tt class="docutils literal">openid_url</tt> to aid browser autocompletion, and

111

displays the <a class="reference" href="http://openid.net/login-bg.gif">OpenID logo</a> inline in the form field using the following CSS:

112

113

input.openid {

114

background: url(/path/to/login-bg.gif) no-repeat;

115

background-position: 0 50%;

116

padding-left: 16px;

117

}

118

</pre>

119

By default, the package expects the <tt class="docutils literal">django_openidconsumer.views.complete</tt>

120

view to be located at <tt class="docutils literal">/openid/complete/</tt>. This is the view that the OpenID

121

provider will redirect the user to after they have authenticated. If you want to

122

put it somewhere else you can either pass an extra <tt class="docutils literal">redirect_to</tt> argument to

123

<tt class="docutils literal">django_openidconsumer.views.begin</tt> or add an <tt class="docutils literal">OPENID_REDIRECT_TO</tt> setting

124

to <tt class="docutils literal">settings.py</tt>.

125

You can pass a <tt class="docutils literal">?next=</tt> query string argument containing a relative URL to

126

the <tt class="docutils literal">begin</tt> view to control where the user will be redirected to having

127

returned to your site. You can also set the default redirection location

128

using the <tt class="docutils literal">OPENID_REDIRECT_NEXT</tt> setting; if you do set set a default the user

129

will be redirected to your homepage.

130

</div>

131

132

<h2><a id="i-names">i-names</a></h2>

133

<a class="reference" href="http://www.inames.net/">i-names</a> are part of the OpenID 2.0 specification, which is currently being

134

developed. They are supported by the python-openid library, and hence are also

135

supported by <tt class="docutils literal">django_openidconsumer</tt>. You can tell if an OpenID is an i-name

136

by checking the <tt class="docutils literal">request.openid.is_iname</tt> property.

137

If you wish to disable i-name support, you can do so by adding the following to

138

your <tt class="docutils literal">settings.py</tt>:

139

140

OPENID_DISALLOW_INAMES = True

141

</pre>

142

</div>