README.txt 9.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257
  1. = Django OpenID Authentication Support =
  2. This package provides integration between Django's authentication
  3. system and OpenID authentication. It also includes support for using
  4. a fixed OpenID server endpoint, which can be useful when implementing
  5. single signon systems.
  6. == Basic Installation ==
  7. 0. Install the Jan Rain Python OpenID library. It can be found at:
  8. http://openidenabled.com/python-openid/
  9. It can also be found in most Linux distributions packaged as
  10. "python-openid". You will need version 2.2.0 or later.
  11. 1. If you are using Django 1.6, configure your project to use the
  12. pickle based session serializer:
  13. SESSION_SERIALIZER = 'django.contrib.sessions.serializers.PickleSerializer'
  14. 2. Add 'django_openid_auth' to INSTALLED_APPS for your application.
  15. At a minimum, you'll need the following in there:
  16. INSTALLED_APPS = (
  17. 'django.contrib.auth',
  18. 'django.contrib.contenttypes',
  19. 'django.contrib.sessions',
  20. 'django_openid_auth',
  21. )
  22. 3. Add 'django_auth_openid.auth.OpenIDBackend' to
  23. AUTHENTICATION_BACKENDS. This should be in addition to the
  24. default ModelBackend:
  25. AUTHENTICATION_BACKENDS = (
  26. 'django_openid_auth.auth.OpenIDBackend',
  27. 'django.contrib.auth.backends.ModelBackend',
  28. )
  29. 4. To create users automatically when a new OpenID is used, add the
  30. following to the settings:
  31. OPENID_CREATE_USERS = True
  32. 5. To have user details updated from OpenID Simple Registration or
  33. Attribute Exchange extension data each time they log in, add the
  34. following:
  35. OPENID_UPDATE_DETAILS_FROM_SREG = True
  36. 6. Hook up the login URLs to your application's urlconf with
  37. something like:
  38. urlpatterns = patterns('',
  39. ...
  40. (r'^openid/', include('django_openid_auth.urls')),
  41. ...
  42. )
  43. 7. Configure the LOGIN_URL and LOGIN_REDIRECT_URL appropriately for
  44. your site:
  45. LOGIN_URL = '/openid/login/'
  46. LOGIN_REDIRECT_URL = '/'
  47. This will allow pages that use the standard @login_required
  48. decorator to use the OpenID login page.
  49. 8. Rerun "python manage.py syncdb" to add the UserOpenID table to
  50. your database.
  51. == Configuring Single Sign-On ==
  52. If you only want to accept identities from a single OpenID server and
  53. that server implemnts OpenID 2.0 identifier select mode, add the
  54. following setting to your app:
  55. OPENID_SSO_SERVER_URL = 'server-endpoint-url'
  56. With this setting enabled, the user will not be prompted to enter
  57. their identity URL, and instead an OpenID authentication request will
  58. be started with the given server URL.
  59. As an example, to use Launchpad accounts for SSO, you'd use:
  60. OPENID_SSO_SERVER_URL = 'https://login.launchpad.net/'
  61. == Launchpad Teams Support ==
  62. This library supports the Launchpad Teams OpenID extension. Using
  63. this feature, it is possible to map Launchpad team memberships to
  64. Django group memberships. It can be configured with:
  65. OPENID_SSO_SERVER_URL = 'https://login.launchpad.net/'
  66. OPENID_LAUNCHPAD_TEAMS_MAPPING = {
  67. 'launchpad-team-1': 'django-group-1',
  68. 'launchpad-team-2': 'django-group-2',
  69. }
  70. When a user logs in, they will be added or removed from the relevant
  71. teams listed in the mapping.
  72. If you have already django-groups and want to map these groups automatically,
  73. you can use the OPENID_LAUNCHPAD_TEAMS_MAPPING_AUTO variable in your
  74. settings.py file.
  75. OPENID_LAUNCHPAD_TEAMS_MAPPING_AUTO = True
  76. If you use OPENID_LAUNCHPAD_TEAMS_MAPPING_AUTO, the variable
  77. OPENID_LAUNCHPAD_TEAMS_MAPPING will be ignored.
  78. If you want to exclude some groups from the auto mapping, use
  79. OPENID_LAUNCHPAD_TEAMS_MAPPING_AUTO_BLACKLIST. This variable has only an effect
  80. if OPENID_LAUNCHPAD_TEAMS_MAPPING_AUTO is True.
  81. OPENID_LAUNCHPAD_TEAMS_MAPPING_AUTO_BLACKLIST = ['django-group1', 'django-group2']
  82. If you want to restrict login to a subset of teams, so that only members of
  83. those teams can login, you can use the OPENID_LAUNCHPAD_TEAMS_REQUIRED variable
  84. in your settings.py file.
  85. OPENID_LAUNCHPAD_TEAMS_REQUIRED = ['launchpad-team-1', 'launchpad-team-2']
  86. Some accounts can be whitelisted from this required team restriction. This is
  87. specifically useful for doing testing. In order to whitelist an account from
  88. the required teams restriction you can use the OPENID_EMAIL_WHITELIST_REGEXP_LIST setting.
  89. As an example, the following value
  90. OPENID_EMAIL_WHITELIST_REGEXP_LIST = ['foo(\+[^@]*)?@foo.com']
  91. would whitelist users with the following emails (and other matching the regular
  92. expression) from being in a required team:
  93. foo@foo.com
  94. foo+bar@foo.com
  95. == External redirect domains ==
  96. By default, redirecting back to an external URL after auth is forbidden. To
  97. permit redirection to external URLs on a separate domain, define
  98. ALLOWED_EXTERNAL_OPENID_REDIRECT_DOMAINS in your settings.py file as a list of
  99. permitted domains:
  100. ALLOWED_EXTERNAL_OPENID_REDIRECT_DOMAINS = ['example.com', 'example.org']
  101. and redirects to external URLs on those domains will additionally be permitted.
  102. == Use as /admin (django.admin.contrib) login ==
  103. If you require openid authentication into the admin application, add the
  104. following setting:
  105. OPENID_USE_AS_ADMIN_LOGIN = True
  106. It is worth noting that a user needs to be be marked as a "staff user" to be
  107. able to access the admin interface. A new openid user will not normally be a
  108. "staff user".
  109. The easiest way to resolve this is to use traditional authentication
  110. (OPENID_USE_AS_ADMIN_LOGIN = False) to sign in as your first user with a
  111. password and authorise your openid user to be staff.
  112. == Change Django usernames if the nickname changes on the provider ==
  113. If you want your Django username to change when a user updates the nickname on
  114. their provider, add the following setting:
  115. OPENID_FOLLOW_RENAMES = True
  116. If the new nickname is available as a Django username, the user is renamed.
  117. Otherwise the user will be renamed to nickname+i for an incrementing value of
  118. i until no conflict occurs. If the user has already been renamed to nickname+1
  119. due to a conflict, and the nickname is still not available, the user will keep
  120. their existing username.
  121. == Require a valid nickname ==
  122. If you must have a valid, unique nickname in order to create a user account, add
  123. the following setting:
  124. OPENID_STRICT_USERNAMES = True
  125. This will cause an OpenID login attempt to fail if the provider does not return
  126. a 'nickname' (username) for the user, or if the nickname conflicts with an
  127. existing user with a different openid identity url. However, a
  128. "openid_duplicate_username" signal is also sent to give a project the chance to
  129. resolve a conflict.
  130. Without this setting, logins without a nickname will be given the username
  131. 'openiduser', and upon conflicts with existing username, an incrementing number
  132. will be appended to the username until it is unique.
  133. == Require Physical Multi-Factor Authentication ==
  134. If your users should use a physical multi-factor authentication method, such as
  135. RSA tokens or YubiKey, add the following setting:
  136. OPENID_PHYSICAL_MULTIFACTOR_REQUIRED = True
  137. If the user's OpenID provider supports the PAPE extension and provides the
  138. Physical Multifactor authentication policy, this will cause the OpenID login to
  139. fail if the user does not provide valid physical authentication to the
  140. provider.
  141. == Override Login Failure Handling ==
  142. You can optionally provide your own handler for login failures by adding the
  143. following setting:
  144. OPENID_RENDER_FAILURE = failure_handler_function
  145. Where failure_handler_function is a function reference that will take the
  146. following parameters:
  147. def failure_handler_function(request, message, status=None, template_name=None, exception=None)
  148. This function must return a Django.http.HttpResponse instance.
  149. == Use the user's email for suggested usernames ==
  150. You can optionally strip out non-alphanumeric characters from the user's email
  151. to generate a preferred username, if the server doesn't provide nick
  152. information, by setting the following setting:
  153. OPENID_USE_EMAIL_FOR_USERNAME = True
  154. Otherwise, and by default, if the server omits nick information and a user is
  155. created it'll receive a username 'openiduser' + a number.
  156. Consider also the OPENID_STRICT_USERNAMES setting (see ``Require a valid nickname``)
  157. == Specify Valid Account Verification Schemes ==
  158. When using OpenID Attribute Exchange, the attribute URI
  159. http://ns.login.ubuntu.com/2013/validation/account is included in the request.
  160. OpenID Providers that support this extension can reply with a token
  161. representing what measures they have taken to validate the e-mail address
  162. included in the response. To change the list of schemes acceptable for your
  163. purposes you can change the setting:
  164. OPENID_VALID_VERIFICATION_SCHEMES = {
  165. None: (),
  166. 'http://example.com/': ('token_via_email',),
  167. }
  168. The element with the None key specifies a list of verification schemes that
  169. will be accepted as trusted from OpenID Providers that we haven't explicitly
  170. configured. These are, almost by definition, untrusted, so it is strongly
  171. recommended that this list remain empty. Verified accounts will be granted the
  172. django_openid_auth.account_verified permission, which can be checked using
  173. user.has_perm() and the perms RequestContext attribute in the normal way.
  174. N.B. Users of the South migration framework will need to provide a data
  175. migration to create the permission when upgrading django-openid-auth, due to a
  176. known issue in South. See http://south.aeracode.org/ticket/211 for details.