Merge pull request #218 from johnpaulett/doc-op-logout-url

Add documentation around OIDC_OP_LOGOUT_URL_METHOD. Fixes #217.

HISTORY.rst

@@ -3,6 +3,14 @@
 History
 -------
 
+0.7.0 (unreleased)
+++++++++++++++++++
+
+Backwards-incompatible changes:
+
+* ``OIDC_OP_LOGOUT_URL_METHOD`` takes a ``request`` parameter now.
+
+
 0.6.0 (2018-03-27)
 ++++++++++++++++++
 

docs/installation.rst

@@ -369,6 +369,33 @@ override the `verify_claims` method. It should return either ``True`` or
    https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
 
 
+Log user out of the OpenID Connect provider
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a user logs out, by default, mozilla-django-oidc will end the current
+Django session.  However, the user may still have an active session with the
+OpenID Connect provider, in which case, the user would likely not be prompted
+to log back in.
+
+Some OpenID Connect providers support a custom (not part of OIDC spec) mechanism
+to end the provider's session.  We can build a function for
+``OIDC_OP_LOGOUT_URL_METHOD`` that will redirect the user to the provider after
+mozilla-django-oidc ends the Django session.
+
+
+.. code-block:: python
+
+   def provider_logout(request):
+       # See your provider's documentation for details on if and how this is
+       # supported
+       redirect_url = 'https://myprovider.com/logout'
+       return redirect_url
+
+
+The ``request.build_absolute_uri`` can be used if the provider requires
+a return-to location.
+
+
 Troubleshooting
 ---------------
 

docs/settings.rst

@@ -181,3 +181,13 @@ of ``mozilla-django-oidc``.
    .. seealso::
 
       https://docs.djangoproject.com/en/1.11/ref/settings/#logout-redirect-url
+
+.. py:attribute:: OIDC_OP_LOGOUT_URL_METHOD
+
+   :default: ``''`` (will use ``LOGOUT_REDIRECT_URL``)
+
+   Function path that returns a URL to redirect the user to after
+   ``auth.logout()`` is called.
+
+   .. versionchanged:: 0.7.0
+      The function must now take a ``request`` parameter.