From f743e23cc440165f06fef2ec100d10b2b6591e59 Mon Sep 17 00:00:00 2001
From: Christian Bouvier <christian.bouvier.15@gmail.com>
Date: Mon, 8 Oct 2018 01:53:42 -0300
Subject: [PATCH] Token Introspection docs (#257)

Added a new doc page related to Token Introspection Endpoint.
The documentation includes some introduction with links to the related RFCs and examples.
---
 docs/index.rst                       |  1 +
 docs/sections/tokenintrospection.rst | 57 ++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)
 create mode 100644 docs/sections/tokenintrospection.rst

diff --git a/docs/index.rst b/docs/index.rst
index 05edb50..f5d2b57 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -35,6 +35,7 @@ Contents:
    sections/oauth2
    sections/accesstokens
    sections/sessionmanagement
+   sections/tokenintrospection
    sections/settings
    sections/signals
    sections/examples
diff --git a/docs/sections/tokenintrospection.rst b/docs/sections/tokenintrospection.rst
new file mode 100644
index 0000000..db7d989
--- /dev/null
+++ b/docs/sections/tokenintrospection.rst
@@ -0,0 +1,57 @@
+.. _tokenintrospection:
+
+Token Introspection
+##################
+
+The `OAuth 2.0 Authorization Framework <https://tools.ietf.org/html/rfc6749>`_ extends its scope with many other speficications. One of these is the `OAuth 2.0 Token Introspection (RFC 7662) <https://tools.ietf.org/html/rfc7662>`_ which defines a protocol that allows authorized protected resources to query the authorization server to determine the set of metadata for a given token that was presented to them by an OAuth 2.0 client.
+
+Client Setup
+====
+In order to enable this feature, some configurations must be performed in the ``Client``.
+
+- The scope key:``token_introspection`` must be added to the client's scope.
+
+If ``OIDC_INTROSPECTION_VALIDATE_AUDIENCE_SCOPE`` is set to ``True`` then:
+
+- The ``client_id`` must be added to the client's scope.
+
+Introspection Endpoint
+====
+The introspection endpoint ``(/introspect)`` is an OAuth 2.0 endpoint that takes a parameter representing an OAuth 2.0 token and returns a JSON document representing the meta information surrounding the token.
+
+The introspection endpoint its called using an HTTP POST request with parameters sent as *"application/x-www-form-urlencoded"* and **Basic authentication** (``base64(client_id:client_secret``).
+
+Parameters:
+
+* ``token``
+    REQUIRED. The string value of an ``access_token`` previously issued.
+
+Example request::
+
+        curl -X POST \
+        http://localhost:8000/introspect \
+        -H 'Authorization: Basic NDgwNTQ2OmIxOGIyODVmY2E5N2Fm' \
+        -H 'Content-Type: application/x-www-form-urlencoded' \
+        -d token=6dd4b859706944848183d26f2fcb99c6
+
+Example Response::
+
+        {
+            "aud": "480546",
+            "sub": "1",
+            "exp": 1538971676,
+            "iat": 1538971076,
+            "iss": "http://localhost:8000",
+            "active": true,
+            "client_id": "480546"
+        }
+
+Introspection Endpoint Errors
+====
+In case of error, the Introspection Endpoint will return a JSON document with the key ``active: false``
+
+Example Error Response::
+
+        {
+            "active": "false"
+        }