#94 rewrite RefreshIDToken middleware to use prompt=none (#127)

Rewrite RefreshIDToken middleware to use authentication endpoint with prompt=None.

In addition:

* this moves the middleware and friends into the mozilla_django_oidc Python module
* adds a OIDC_EXEMPT_URLS setting
* makes the middleware more flexible for subclassing to augment the behavior
* adds debug logging to make it easier to verify the middleware is set up correctly
  and working
* adds some rough troubleshooting docs

Author: willkg

docs/installation.rst

@@ -185,39 +185,26 @@ However, even if that account was disabled, the user's account and session on
 your site will continue. In this way, a user can quit his/her job, lose access to
 his/her corporate account, but continue to use your website.
 
-To handle this scenario, your website needs to know if the user's ID token with
+To handle this scenario, your website needs to know if the user's id token with
 the OIDC provider is still valid. You need to use the
-:py:class:`mozilla_django_oidc.contrib.auth0.middleware.RefreshIDToken` middleware.
+:py:class:`mozilla_django_oidc.middleware.RefreshIDToken` middleware.
 
 To add it to your site, put it in the settings::
 
     MIDDLEWARE_CLASSES = [
         # middleware involving session and autheentication must come first
         # ...
-        'mozilla_django_oidc.contrib.auth0.middleware.RefreshIDToken',
+        'mozilla_django_oidc.middleware.RefreshIDToken',
         # ...
     ]
 
 
-The ``RefreshIDToken`` middleware will check that the id token is still valid
-with the OIDC provider every ``settings.OIDC_RENEW_ID_TOKEN_EXPIRY_SECONDS``
-which defaults to 15 minutes.
+The ``RefreshIDToken`` middleware will check to see if the user's id token has
+expired and if so, redirect to the OIDC provider's authentication endpoint
+for a silent re-auth. That will redirect back to the page the user was going to.
 
-You also need to set ``OIDC_STORE_ACCESS_TOKEN``::
-
-    OIDC_STORE_ACCESS_TOKEN = True
-
-
-This stores the token that the middleware renews.
-
-You also need to set the domain for your Auth0 SSO::
-
-    OIDC_OP_DOMAIN = "<domain for OP>"
-
-
-.. note::
-   Currently, this is implemented using an Auth0-specific API endpoint. That
-   will change soon.
+The length of time it takes for an id token to expire is set in
+``settings.OIDC_RENEW_ID_TOKEN_EXPIRY_SECONDS`` which defaults to 15 minutes.
 
 
 Connecting OIDC user identities to Django users
@@ -352,3 +339,25 @@ setting::
 
 You might want to do this if you want to control user creation because your
 system requires additional process to allow people to use it.
+
+
+Troubleshooting
+---------------
+
+mozilla-django-oidc logs using the ``mozilla_django_oidc`` logger. Enable that
+logger in settings to see logging messages to help you debug:
+
+.. code-block:: python
+
+   LOGGING = {
+       ...
+       'loggers': {
+           'mozilla_django_oidc': {
+               'handlers': ['console'],
+               'level': 'DEBUG'
+           },
+       ...
+   }
+
+
+Make sure to use the appropriate handler for your app.

docs/settings.rst

@@ -72,6 +72,14 @@ of ``mozilla-django-oidc``.
 
    Controls whether the OpenID Connect client verifies the SSL certificate of the OP responses
 
+.. py:attribute:: OIDC_EXEMPT_URLS
+
+   :default: ``[]``
+
+   This is a list of url paths or Django view names. This plus the
+   mozilla-django-oidc urls are exempted from the id token renewal by the
+   ``RenewIDToken`` middleware.
+
 .. py:attribute:: OIDC_CREATE_USER
 
    :default: ``True``

mozilla_django_oidc/contrib/__init__.py

@@ -0,0 +1,127 @@
+import logging
+import time
+try:
+    from urllib import urlencode
+except ImportError:
+    from urllib.parse import urlencode
+
+import django
+from django.core.urlresolvers import reverse
+from django.http import HttpResponseRedirect
+from django.utils.crypto import get_random_string
+
+from mozilla_django_oidc.utils import absolutify, import_from_settings, is_authenticated
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+# Django 1.10 makes changes to how middleware work. In Django 1.10+, we want to
+# use the mixin so that our middleware works as is.
+if django.VERSION >= (1, 10):
+    from django.utils.deprecation import MiddlewareMixin
+else:
+    class MiddlewareMixin(object):
+        pass
+
+
+# FIXME(willkg): This doesn't appear to be used anywhere.
+def logout_url():
+    """Log out the user from Auth0."""
+    url = 'https://' + import_from_settings('OIDC_OP_DOMAIN') + '/v2/logout'
+    url += '?' + urlencode({
+        'returnTo': import_from_settings('LOGOUT_REDIRECT_URL', '/'),
+        'client_id': import_from_settings('OIDC_RP_CLIENT_ID')
+    })
+    return url
+
+
+class RefreshIDToken(MiddlewareMixin):
+    """Renews id_tokens after expiry seconds
+
+    For users authenticated with an id_token, we need to check that it's still
+    valid after a specific amount of time and if not, force them to
+    re-authenticate silently.
+
+    """
+    def get_exempt_urls(self):
+        """Generate and return a set of url paths to exempt from RefreshIDToken
+
+        This takes the value of ``settings.OIDC_EXEMPT_URLS`` and appends three
+        urls that mozilla-django-oidc uses. These values can be view names or
+        absolute url paths.
+
+        :returns: list of url paths (for example "/oidc/callback/")
+
+        """
+        exempt_urls = list(import_from_settings('OIDC_EXEMPT_URLS', []))
+        exempt_urls.extend([
+            'oidc_authentication_init',
+            'oidc_authentication_callback',
+            'oidc_logout',
+        ])
+
+        return [
+            url if url.startswith('/') else reverse(url)
+            for url in exempt_urls
+        ]
+
+    def is_refreshable_url(self, request):
+        """Takes a request and returns whether it triggers a refresh examination
+
+        :arg HttpRequest request:
+
+        :returns: boolean
+
+        """
+        exempt_urls = self.get_exempt_urls()
+
+        return (
+            request.method == 'GET' and
+            is_authenticated(request.user) and
+            request.path not in exempt_urls and
+            not request.is_ajax()
+        )
+
+    def process_request(self, request):
+        if not self.is_refreshable_url(request):
+            LOGGER.debug('request is not refreshable')
+            return
+
+        expiration = request.session.get('oidc_id_token_expiration', 0)
+        now = time.time()
+        if expiration > now:
+            # The id_token is still valid, so we don't have to do anything.
+            LOGGER.debug('id token is still valid (%s > %s)', expiration, now)
+            return
+
+        LOGGER.debug('id token has expired')
+        # The id_token has expired, so we have to re-authenticate silently.
+        auth_url = import_from_settings('OIDC_OP_AUTHORIZATION_ENDPOINT')
+        client_id = import_from_settings('OIDC_RP_CLIENT_ID')
+        state = get_random_string(import_from_settings('OIDC_STATE_SIZE', 32))
+
+        # Build the parameters as if we were doing a real auth handoff, except
+        # we also include prompt=none.
+        params = {
+            'response_type': 'code',
+            'client_id': client_id,
+            'redirect_uri': absolutify(reverse('oidc_authentication_callback')),
+            'state': state,
+            'scope': 'openid',
+            'prompt': 'none',
+        }
+
+        if import_from_settings('OIDC_USE_NONCE', True):
+            nonce = get_random_string(import_from_settings('OIDC_NONCE_SIZE', 32))
+            params.update({
+                'nonce': nonce
+            })
+            request.session['oidc_nonce'] = nonce
+
+        request.session['oidc_state'] = state
+        request.session['oidc_login_next'] = request.get_full_path()
+
+        query = urlencode(params)
+        redirect_url = '{url}?{query}'.format(url=auth_url, query=query)
+        return HttpResponseRedirect(redirect_url)

mozilla_django_oidc/contrib/auth0/__init__.py

@@ -1,3 +1,4 @@
+import time
 try:
     from urllib import urlencode
 except ImportError:
@@ -37,6 +38,12 @@ def login_failure(self):
 
     def login_success(self):
         auth.login(self.request, self.user)
+
+        # Figure out when this id_token will expire. This is ignored unless you're
+        # using the RenewIDToken middleware.
+        expiration_interval = import_from_settings('OIDC_RENEW_ID_TOKEN_EXPIRY_SECONDS', 60 * 15)
+        self.request.session['oidc_id_token_expiration'] = time.time() + expiration_interval
+
         return HttpResponseRedirect(self.success_url)
 
     def get(self, request):