From d9149b162d9db2f82ac4c28a864518328b18ab8f Mon Sep 17 00:00:00 2001
From: Ignacio Fiorentino <juanifioren@gmail.com>
Date: Fri, 28 Oct 2016 16:56:06 -0300
Subject: [PATCH] Add initial doc for session management.

---
 docs/index.rst                      |  3 ++
 docs/sections/sessionmanagement.rst | 67 +++++++++++++++++++++++++++++
 docs/sections/settings.rst          | 10 ++++-
 3 files changed, 78 insertions(+), 2 deletions(-)
 create mode 100644 docs/sections/sessionmanagement.rst
diff --git a/docs/index.rst b/docs/index.rst
index 2c6a3b3..ce1011b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -5,6 +5,8 @@ This tiny (but powerful!) package can help you providing out of the box all the
 
 Also implements the following specifications:
 
+* `OpenID Connect Discovery 1.0 <https://openid.net/specs/openid-connect-discovery-1_0.html>`_
+* `OpenID Connect Session Management 1.0 <https://openid.net/specs/openid-connect-session-1_0.html>`_
 * `OAuth 2.0 for Native Apps <https://tools.ietf.org/html/draft-ietf-oauth-native-apps-01>`_
 * `Proof Key for Code Exchange by OAuth Public Clients <https://tools.ietf.org/html/rfc7636>`_
 
@@ -30,6 +32,7 @@ Contents:
    sections/userconsent
    sections/oauth2
    sections/accesstokens
+   sections/sessionmanagement
    sections/settings
    sections/examples
    sections/contribute
diff --git a/docs/sections/sessionmanagement.rst b/docs/sections/sessionmanagement.rst
new file mode 100644
index 0000000..ae7f588
--- /dev/null
+++ b/docs/sections/sessionmanagement.rst
@@ -0,0 +1,67 @@
+.. _sessionmanagement:
+
+Session Management
+##################
+
+The `OpenID Connect Session Management 1.0 <https://openid.net/specs/openid-connect-session-1_0.html>`_ specification complements the core specification by defining how to monitor the End-User's login status at the OpenID Provider on an ongoing basis so that the Relying Party can log out an End-User who has logged out of the OpenID Provider.
+
+
+Setup
+=====
+
+Somewhere in your Django ``settings.py``::
+
+    MIDDLEWARE_CLASSES = [
+        ...
+        'oidc_provider.middleware.SessionManagementMiddleware',
+    ]
+
+    OIDC_SESSION_MANAGEMENT_ENABLE = True
+
+Example RP iframe
+=================
+
+::
+
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <meta charset="ISO-8859-1">
+        <title>RP Iframe</title>
+    </head>
+    <body onload="javascript:startChecking()">
+        <iframe id="op-iframe" src="http://localhost:8000/check-session-iframe/" frameborder="0" width="0" height="0"></iframe>
+    </body>
+    <script>
+        var targetOP = "http://localhost:8000";
+
+        window.addEventListener("message", receiveMessage, false);
+
+        function startChecking() {
+                  checkStatus();
+                  setInterval('checkStatus()', 1000*60); // every 60 seconds
+        }
+
+        function checkStatus() {
+                  var clientId = '';
+                  var sessionState = '';
+                  var data = clientId + ' ' + sessionState;
+                  document.getElementById('op-iframe').contentWindow.postMessage(data, targetOP);
+        }
+
+        function receiveMessage(event) {
+            if (event.origin !== targetOP) {
+                // Origin did not come from the OP.
+                return;
+            }
+            if (event.data === 'unchanged') {
+                // User is still logged in to the OP.
+            } else if (event.data === 'changed') {
+                // Perform re-authentication with prompt=none to obtain the current session state at the OP.
+            } else {
+                // Error.
+                console.log('Something goes wrong!');
+            }
+        }
+    </script>
+    </html>
diff --git a/docs/sections/settings.rst b/docs/sections/settings.rst
index b4afc90..3e8385b 100644
--- a/docs/sections/settings.rst
+++ b/docs/sections/settings.rst
@@ -52,7 +52,6 @@ Used to add extra scopes specific for your app. OpenID Connect RP's will use sco
 
 Read more about how to implement it in :ref:`scopesclaims` section.
 
-
 OIDC_IDTOKEN_EXPIRE
 ===================
 
@@ -92,6 +91,13 @@ Default is::
 
         return str(user.id)
 
+OIDC_SESSION_MANAGEMENT_ENABLE
+==============================
+
+OPTIONAL. ``bool``. Enables OpenID Connect Session Management 1.0 in your provider. Read :ref:`scopesclaims` section.
+
+Default is ``False``.
+
 OIDC_SKIP_CONSENT_ALWAYS
 ========================
 
@@ -123,7 +129,7 @@ Expressed in seconds. Default is ``60*60``.
 OIDC_USERINFO
 =============
 
-OPTIONAL. ``str``. A string with the location of your function. Read **Standard Claims** section.
+OPTIONAL. ``str``. A string with the location of your function. Read :ref:`scopesclaims` section.
 
 The function receives a ``claims`` dictionary with all the standard claims and ``user`` instance. Must returns the ``claims`` dict again.
 
