Added access_token as JWT examples, and updated JWT grant section

A confusion between JWT as token and as authentication mechanism was introduced long-time back and I tried to make a bit of clarity to not confuse again the newcomers.

4 files changed, 131 insertions, 11 deletions

diff --git a/docs/oauth2/grants/jwt.rst b/docs/oauth2/grants/jwt.rst
index db65342..2c1c0e2 100644
--- a/docs/oauth2/grants/jwt.rst
+++ b/docs/oauth2/grants/jwt.rst
@@ -1,7 +1,14 @@
-==========
-JWT Tokens
-==========
+==============================================================
+JWT Profile for Client Authentication and Authorization Grants
+==============================================================
 
-Not yet implemented. Track progress in `GitHub issue 50`_.
+If you're looking at JWT Tokens, please see :doc:`Bearer Tokens </oauth2/tokens/bearer>` instead.
 
-.. _`GitHub issue 50`: https://github.com/oauthlib/oauthlib/issues/50
+The JWT Profile `RFC7523`_ implements the `RFC7521`_ abstract assertion
+protocol. It aims to extend the OAuth2 protocol to use JWT as an
+additional authorization grant.
+
+Currently, this is not implemented but all PRs are welcome. See how to :doc:`Contribute </contributing>`.
+
+.. _`RFC7521`: https://tools.ietf.org/html/rfc7521
+.. _`RFC7523`: https://tools.ietf.org/html/rfc7523
diff --git a/docs/oauth2/preconfigured_servers.rst b/docs/oauth2/preconfigured_servers.rst
index 6184c27..e1f629c 100644
--- a/docs/oauth2/preconfigured_servers.rst
+++ b/docs/oauth2/preconfigured_servers.rst
@@ -12,7 +12,8 @@ Construction is simple, only import your validator and you are good to go::
 
     server = WebApplicationServer(your_validator)
 
-If you prefer to construct tokens yourself you may pass a token generator::
+If you prefer to construct tokens yourself you may pass a token generator (see
+ :doc:`Tokens <tokens/tokens>` for more examples like JWT) ::
 
     def your_token_generator(request, refresh_token=False):
         return 'a_custom_token' + request.client_id
@@ -21,6 +22,9 @@ If you prefer to construct tokens yourself you may pass a token generator::
 
 This function is passed the request object and a boolean indicating whether to generate an access token (False) or a refresh token (True).
 
+.. autoclass:: oauthlib.oauth2.Server
+    :members:
+
 .. autoclass:: oauthlib.oauth2.WebApplicationServer
     :members:
 
diff --git a/docs/oauth2/tokens/bearer.rst b/docs/oauth2/tokens/bearer.rst
index 8c6270d..0776db8 100644
--- a/docs/oauth2/tokens/bearer.rst
+++ b/docs/oauth2/tokens/bearer.rst
@@ -2,12 +2,122 @@
 Bearer Tokens
 =============
 
-The most common OAuth 2 token type. It provides very little in terms of security
-and relies heavily upon the ability of the client to keep the token secret.
+The most common OAuth 2 token type.
 
-Bearer tokens are the default setting with all configured endpoints. Generally
+Bearer tokens is the default setting for all configured endpoints. Generally
 you will not need to ever construct a token yourself as the provided servers
 will do so for you.
 
+By default, :doc:`*Server </oauth2/preconfigured_servers>` generate Bearer tokens as
+random strings. However, you can change the default behavior to generate JWT
+instead. All preconfigured servers take as parameters `token_generator` and
+`refresh_token_generator` to fit your needs.
+
+.. contents:: Tutorial Contents
+    :depth: 3
+
+
+1. Generate signed JWT
+----------------------
+
+A function is available to generate signed JWT (with RS256 PEM key) with static
+and dynamic claims.
+
+.. code-block:: python
+
+    from oauthlib.oauth2.rfc6749 import tokens
+    from oauthlib.oauth2 import Server
+
+    private_pem_key = <load_your_key_in_pem_format>
+    validator = <instantiate_your_validator>
+
+    server = Server(
+      your_validator,
+      token_generator=tokens.signed_token_generator(private_pem_key, issuer="foobar")
+    )
+
+
+Note that you can add any custom claims in `RequestValidator` methods by adding them to
+`request.claims` dictionary. Example below:
+
+
+.. code-block:: python
+
+    def validate_client_id(self, client_id, request):
+        (.. your usual checks ..)
+
+        request.claims = {
+            'aud': self.client_id
+        }
+        return True
+
+
+Once completed, the token endpoint will generate access_token in JWT form:
+
+.. code-block:: shell
+
+
+    access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJy(..)&expires_in=120&token_type=Bearer(..)
+
+
+And you will find all claims in its decoded form:
+
+
+.. code-block:: javascript
+
+    {
+      "aud": "<client_id>",
+      "iss": "foobar",
+      "scope": "profile calendar",
+      "exp": 12345,
+    }
+
+
+2. Define your own implementation (text, JWT, JWE, ...)
+----------------------------------------------------------------
+
+Sometime you may want to generate custom `access_token` with a reference from a
+database (as text) or use a HASH signature in JWT or use JWE (encrypted content).
+
+Also, note that you can declare the generate function in your instanciated
+validator to benefit of the `self` variables.
+
+See the example below:
+
+.. code-block:: python
+
+    class YourValidator(RequestValidator):
+        def __init__(self, secret, issuer):
+            self.secret = secret
+            self.issuer = issuer
+
+        def generate_access_token(self, request):
+            token = jwt.encode({
+                "ref": str(libuuid.uuid4()),
+                "aud": request.client_id,
+                "iss": self.issuer,
+                "exp": now + datetime.timedelta(seconds=request.expires_in)
+            }, self.secret, algorithm='HS256').decode()
+            return token
+
+
+Then associate it to your `Server`:
+
+.. code-block:: python
+
+    validator = YourValidator(secret="<your_secret>", issuer="<your_issuer_id>")
+
+    server = Server(
+        your_validator,
+        token_generator=validator.generate_access_token
+    )
+
+
+3. BearerToken API
+------------------
+
+If none of the :doc:`/oauth2/preconfigured_servers` fit your needs, you can
+declare your own Endpoints and use the `BearerToken` API as below.
+
 .. autoclass:: oauthlib.oauth2.BearerToken
     :members:
diff --git a/docs/oauth2/tokens/tokens.rst b/docs/oauth2/tokens/tokens.rst
index f341509..4e19e7e 100644
--- a/docs/oauth2/tokens/tokens.rst
+++ b/docs/oauth2/tokens/tokens.rst
@@ -3,8 +3,7 @@ Tokens
 ======
 
 The main token type of OAuth 2 is Bearer tokens and that is what OAuthLib
-currently supports. Other tokens, such as JWT, SAML and possibly MAC (if the
-spec matures) can easily be added (and will be in due time).
+currently supports. Other tokens, such as SAML and MAC can easily be added.
 
 The purpose of a token is to authorize access to protected resources to a client
 (i.e. your G+ feed).