Improve clarity around howto define a grant.

1 files changed, 41 insertions, 26 deletions

diff --git a/docs/oauth2/grants/custom_grant.rst b/docs/oauth2/grants/custom_grant.rst
index 7408cf6..b47131c 100644
--- a/docs/oauth2/grants/custom_grant.rst
+++ b/docs/oauth2/grants/custom_grant.rst
@@ -7,10 +7,9 @@ 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>`.
+! See :doc:`how to contribute here </contributing>`.
 
-Please find below an example of how to create a new grant and use it
-in an endpoint:
+Please find how to create a new grant and use it in an endpoint:
 
 .. contents:: Tutorial Contents
     :depth: 3
@@ -18,46 +17,62 @@ in an endpoint:
 
 1. Define your Grant Type
 -------------------------
-
 The heart of your code is done by subclassing
-:py:class:`oauthlib.oauth2.rfc6749.grant_types.base.GrantTypeBase`.
-If you want to use it in the Authorize endpoint, you will have to
-implement `create_authorization_response`, if in the Token endpoint,
-implement `create_token_response`.
+: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
 
-2. Associate it with Endpoints
+You can define new Request Validator methods if needed, or reuse the
+existing ones.
+
+3. Associate it with Endpoints
 ------------------------------
-Then, once declared, you have to create an instance of your grant and
-add it to your
-endpoint. I.e. :py:class:`oauthlib.oauth2.rfc6749.endpoints.AuthorizationEndpoint`
-or :py:class:`oauthlib.oauth2.rfc6749.endpoints.TokenEndpoint`. You
-can see concrete examples in
-:py:class:`oauthlib.oauth2.rfc6749.endpoints.pre_configured.Server`
-for examples.
-
-3. Example
+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`:
 
-Sample below shows the creation of a new custom `grant_type` parameter
-and declare it in the `/token` endpoint of your `Server`. Note that
-you can reuse `pre_configured.Server` or use your own class inheriting
-of the `Endpoint` classes you have decided.
+* 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 == 'urn:ietf:params:oauth:grant-type:my-custom-grant':
+            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,
-                                               refresh_token=self.issue_new_refresh_tokens)
+            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["urn:ietf:params:oauth:grant-type:my-custom-grant"] = my_custom_grant
+        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`