Merge pull request #294 from kitab15/docs-token-introspection

Token Introspection docs (#257)

docs/index.rst

@@ -35,6 +35,7 @@ Contents:
    sections/oauth2
    sections/accesstokens
    sections/sessionmanagement
+   sections/tokenintrospection
    sections/settings
    sections/signals
    sections/examples

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"
+        }