1 files changed, 78 insertions, 0 deletions
diff --git a/docs/oauth2/grants/custom_grant.rst b/docs/oauth2/grants/custom_grant.rst
new file mode 100644
index 0000000..8c4571c
--- /dev/null
+++ b/docs/oauth2/grants/custom_grant.rst
@@ -0,0 +1,78 @@
+=================
+Custom Grant type
+=================
+
+Writing a custom grant type can be useful to implement a specification
+which is in an early draft, or implement a grant provided by a
+specific OAuth2.0 Authorization Server documentation but not provided
+by oauthlib. For information, any grant types with a clear
+specification can be integrated in oauthlib, just make a PR for that !
+See :doc:`how to contribute here </contributing>`.
+
+Please find how to create a new grant and use it in an endpoint:
+
+.. contents:: Tutorial Contents
+    :depth: 3
+
+
+1. Define your Grant Type
+-------------------------
+The heart of your code is done by subclassing
+:py:class:`GrantTypeBase`.  If you want to use it in the Authorize
+endpoint, you will have to implement
+:py:meth:`create_authorization_response`, if you want to use the Token
+endpoint, implement :py:meth:`create_token_response`. You can also
+implement both.
+
+2. Implement the grant
+----------------------
+Inside the method's implementation, you will have to:
+
+* add validations of the request (syntax, parameters, ...)
+* call and orchestrate one or multiple Request Validators calls
+* generate and return HTTP response
+
+You can define new Request Validator methods if needed, or reuse the
+existing ones.
+
+3. Associate it with Endpoints
+------------------------------
+Then, once implemented, you have to instanciate the grant object and
+bind it to your endpoint. Either :py:class:`AuthorizationEndpoint`,
+:py:class:`TokenEndpoint` or both.
+
+4. Example
+----------
+This example shows how to add a simple extension to the `Token endpoint`:
+
+* creation of a new class ``MyCustomGrant``, and implement ``create_token_response``.
+* do basics and custom request validations, then call a custom method
+  of `Request Validator` to extend the interface for the implementor.
+* instanciate the new grant, and bind it with an existing ``Server``.
+
+.. code-block:: python
+
+    grant_name = 'urn:ietf:params:oauth:grant-type:my-custom-grant'
+
+    class MyCustomGrant(GrantTypeBase):
+        def create_token_response(self, request, token_handler):
+            if not request.grant_type == grant_name:
+                raise errors.UnsupportedGrantTypeError(request=request)
+
+            # implement your custom validation checks
+            # ..
+            self.request_validator.your_custom_check(request)
+
+            token = token_handler.create_token(request)
+            return self._get_default_headers(), json.dumps(token), 200
+
+    def setup_oauthlib():
+        my_custom_grant = MyCustomGrant()
+        server = Server(request_validator)
+        server.grant_types[grant_name] = my_custom_grant
+
+
+You can find concrete examples directly in the code source of existing
+grants and existing servers. See Grant Types in
+:py:mod:`oauthlib.oauth2.rfc749.grant_types`, and Servers in
+:py:mod:`oauthlib.oauth2.rfc749.endpoints.pre_configured`