Add OIDC and id_token as JWT exampleoidc-doc

4 files changed, 96 insertions, 21 deletions

diff --git a/docs/feature_matrix.rst b/docs/feature_matrix.rst
index 59f3f3a..45010d1 100644
--- a/docs/feature_matrix.rst
+++ b/docs/feature_matrix.rst
@@ -7,21 +7,31 @@ Extensions and variations that are outside the spec are not supported.
 - HMAC-SHA1, RSA-SHA1 and plaintext signatures.
 - Signature placement in header, url or body.
 
-OAuth 2 client and provider support for
-
-- Authorization Code Grant
-- Implicit Grant
-- Client Credentials Grant
-- Resource Owner Password Credentials Grant
-- Refresh Tokens
-- Bearer Tokens
-- Draft MAC tokens
-- Token Revocation
-- Token Introspection
-- OpenID Connect Authentication
-
-with support for SAML2 and JWT tokens, dynamic client registration and more to
-come.
+OAuth 2.0 client and provider support for:
+
+- `RFC6749#section-4.1`_: Authorization Code Grant
+- `RFC6749#section-4.2`_: Implicit Grant
+- `RFC6749#section-4.3`_: Resource Owner Password Credentials Grant
+- `RFC6749#section-4.4`_: Client Credentials Grant
+- `RFC6749#section-6`_: Refresh Tokens
+- `RFC6750`_: Bearer Tokens
+- `RFC7009`_: Token Revocation
+- `RFC Draft MAC tokens`_
+- OAuth2.0 Provider: `OpenID Connect Core`_
+- OAuth2.0 Provider: `RFC7662`_: Token Introspection
+- OAuth2.0 Provider: `RFC8414`_: Authorization Server Metadata
+
+Features to be implemented (any help/PR are welcomed):
+
+- OAuth2.0 Client: `OpenID Connect Core`_
+- OAuth2.0 Client: `RFC7662`_: Token Introspection
+- OAuth2.0 Client: `RFC8414`_: Authorization Server Metadata
+- SAML2
+- Bearer JWT as Client Authentication
+- Dynamic client registration
+- OpenID Discovery
+- OpenID Session Management
+- ...and more
 
 Supported platforms
 -------------------
@@ -32,3 +42,14 @@ should be able to use OAuthLib on any platform that supports Python. If you use
 RSA you are limited to the platforms supported by `cryptography`_.
 
 .. _`cryptography`: https://cryptography.io/en/latest/installation/
+.. _`RFC6749#section-4.1`: https://tools.ietf.org/html/rfc6749#section-4.1
+.. _`RFC6749#section-4.2`: https://tools.ietf.org/html/rfc6749#section-4.2
+.. _`RFC6749#section-4.3`: https://tools.ietf.org/html/rfc6749#section-4.3
+.. _`RFC6749#section-4.4`: https://tools.ietf.org/html/rfc6749#section-4.4
+.. _`RFC6749#section-6`: https://tools.ietf.org/html/rfc6749#section-6
+.. _`RFC6750`: https://tools.ietf.org/html/rfc6750
+.. _`RFC Draft MAC tokens`: https://tools.ietf.org/id/draft-ietf-oauth-v2-http-mac-02.html
+.. _`RFC7009`: https://tools.ietf.org/html/rfc7009
+.. _`RFC7662`: https://tools.ietf.org/html/rfc7662
+.. _`OpenID Connect Core`: https://openid.net/specs/openid-connect-core-1_0.html
+.. _`RFC8414`: https://tools.ietf.org/html/rfc8414
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