3 files changed, 60 insertions, 6 deletions
diff --git a/docs/oauth2/endpoints/endpoints.rst b/docs/oauth2/endpoints/endpoints.rst
index 98599e8..8068ec4 100644
--- a/docs/oauth2/endpoints/endpoints.rst
+++ b/docs/oauth2/endpoints/endpoints.rst
@@ -16,8 +16,8 @@ client attempts to access the user resources on their behalf.
     authorization
     introspect
     token
-    resource
     revocation
+    resource
 
 There are three main endpoints, the authorization endpoint which mainly
 handles user authorization, the token endpoint which provides tokens and the
diff --git a/docs/oauth2/oidc/id_tokens.rst b/docs/oauth2/oidc/id_tokens.rst
index 5d6aa91..999cfa7 100644
--- a/docs/oauth2/oidc/id_tokens.rst
+++ b/docs/oauth2/oidc/id_tokens.rst
@@ -5,7 +5,9 @@ The creation of `ID Tokens`_ is ultimately done not by OAuthLib but by your ``Re
 content is dependent on your implementation of users, their attributes, any claims you may wish to support, as well as the
 details of how you model the notion of a Client Application.  As such OAuthLib simply calls your validator's ``get_id_token``
 method at the appropriate times during the authorization flow, depending on the grant type requested (Authorization Code, Implicit,
-Hybrid, etc.)
+Hybrid, etc.).
+
+See examples below.
 
 .. _`ID Tokens`: http://openid.net/specs/openid-connect-core-1_0.html#IDToken
 
@@ -13,4 +15,35 @@ Hybrid, etc.)
    :members: get_id_token
 
 
+JWT/JWS example with pyjwt library
+----------------------------------
+
+An example below using Cryptography library to load the private key and PyJWT to sign the JWT.
+Note that the claims list in the "data" dict must be set accordingly to the auth request.
+
+You can switch to jwcrypto library if you want to return JWE instead.
+
+.. code-block:: python
+
+  class MyValidator(RequestValidator):
+    def __init__(self, **kwargs):
+        with open(path.join(path.dirname(path.realpath(__file__)), "./id_rsa"), 'rb') as fd:
+            from cryptography.hazmat.backends import default_backend
+            from cryptography.hazmat.primitives import serialization
+            self.private_pem = serialization.load_pem_private_key(
+                fd.read(),
+                password=None,
+                backend=default_backend()
+            )
+
+        super().__init__(self, **kwargs)
+
+    def get_id_token(self, token, token_handler, request):
+        import jwt
+
+        data = {"nonce": request.nonce} if request.nonce is not None else {}
+
+        for claim_key in request.claims:
+            data[claim_key] = request.userattributes[claim_key]  # this must be set in another callback
 
+        return jwt.encode(data, self.private_pem, 'RS256')
diff --git a/docs/oauth2/oidc/validator.rst b/docs/oauth2/oidc/validator.rst
index c92b726..a03adfe 100644
--- a/docs/oauth2/oidc/validator.rst
+++ b/docs/oauth2/oidc/validator.rst
@@ -1,7 +1,28 @@
-RequestValidator Extensions
-============================
+OpenID Connect
+=========================================
 
-Four methods must be implemented in your validator subclass if you wish to support OpenID Connect:
+Migrate your OAuth2.0 server into an OIDC provider
+----------------------------------------------------
+
+If you have a OAuth2.0 provider running and want to upgrade to OIDC, you can
+upgrade it by replacing one line of code:
+
+.. code-block:: python
+
+    from oauthlib.oauth2 import Server
+
+Into
+
+.. code-block:: python
+
+    from oauthlib.openid import Server
+
+Then, you have to implement the new RequestValidator methods as shown below.
+
+RequestValidator Extension
+----------------------------------------------------
+
+A couple of methods must be implemented in your validator subclass if you wish to support OpenID Connect:
 
 .. autoclass:: oauthlib.oauth2.RequestValidator
-   :members: validate_silent_authorization, validate_silent_login, validate_user_match, get_id_token
+   :members: validate_silent_authorization, validate_silent_login, validate_user_match, get_id_token, get_authorization_code_scopes, validate_jwt_bearer_token