Update description of OIDC scopes for claims and clarify related info.

Author: n2ygk

docs/oidc.rst

@@ -102,7 +102,7 @@ so there is no need to add a setting for the public key.
 
 
 Rotating the RSA private key
-~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Extra keys can be published in the jwks_uri with the ``OIDC_RSA_PRIVATE_KEYS_INACTIVE``
 setting. For example:::
 
@@ -250,33 +250,40 @@ our custom validator. It takes one of two forms:
 The first form gets passed a request object, and should return a dictionary
 mapping a claim name to claim data::
     class CustomOAuth2Validator(OAuth2Validator):
+	# Set `oidc_claim_scope = None` to ignore scopes that limit which claims to return,
+	# otherwise the OIDC standard scopes are used.
+
         def get_additional_claims(self, request):
-            claims = {}
-            claims["email"] = request.user.get_user_email()
-            claims["username"] = request.user.get_full_name()
+	    return {
+		"given_name": request.user.first_name,
+		"family_name": request.user.last_name,
+		"name": ' '.join([request.user.first_name, request.user.last_name]),
+		"preferred_username": request.user.username,
+		"email": request.user.email,
+	    }
 
-            return claims
 
 The second form gets no request object, and should return a dictionary
 mapping a claim name to a callable, accepting a request and producing
 the claim data::
     class CustomOAuth2Validator(OAuth2Validator):
-        def get_additional_claims(self):
-            def get_user_email(request):
-                return request.user.get_user_email()
+	# Set `oidc_claim_scope = None` to ignore scopes that limit which claims to return,
+	# otherwise the OIDC standard scopes are used.
 
-            claims = {}
-            claims["email"] = get_user_email
-            claims["username"] = lambda r: r.user.get_full_name()
+	def get_additional_claims(self):
+	    return {
+		"given_name": lambda request: request.user.first_name,
+		"family_name": lambda request: request.user.last_name,
+		"name": lambda request: ' '.join([request.user.first_name, request.user.last_name]),
+		"preferred_username": lambda request: request.user.username,
+		"email": lambda request: request.user.email,
+	    }
 
-            return claims
 
 Standard claim ``sub`` is included by default, to remove it override ``get_claim_dict``.
 
-In some cases, it might be desirable to not list all claims in discovery info. To customize
-which claims are advertised, you can override the ``get_discovery_claims`` method to return
-a list of claim names to advertise. If your ``get_additional_claims`` uses the first form
-and you still want to advertise claims, you can also override ``get_discovery_claims``.
+Supported claims discovery
+--------------------------
 
 In order to help clients discover claims early, they can be advertised in the discovery
 info, under the ``claims_supported`` key. In order for the discovery info view to automatically
@@ -285,19 +292,52 @@ because the discovery info views are requested with an unauthenticated request,
 producing claim data would fail. If you use the first form, producing claim data directly,
 your claims will not be added to discovery info.
 
+In some cases, it might be desirable to not list all claims in discovery info. To customize
+which claims are advertised, you can override the ``get_discovery_claims`` method to return
+a list of claim names to advertise. If your ``get_additional_claims`` uses the first form
+and you still want to advertise claims, you can also override ``get_discovery_claims``.
+
+Using OIDC scopes to determine which claims are returned
+--------------------------------------------------------
+
+The ``oidc_claim_scope`` OAuth2Validator class attribute implements OIDC's
+`5.4 Requesting Claims using Scope Values`_ feature.
+For example, a ``given_name`` claim is only returned if the ``profile`` scope was granted.
+
+To change the list of claims and which scopes result in their being returned,
+override ``oidc_claim_scope`` with a dict keyed by claim with a value of scope.
+The following example adds instructions to return the ``foo`` claim when the ``bar`` scope is granted::
+    class CustomOAuth2Validator(OAuth2Validator):
+        oidc_claim_scope = OAuth2Validator.oidc_claim_scope
+        oidc_claim_scope.update({"foo": "bar"})
+
+Set ``oidc_claim_scope = None`` to return all claims irrespective of the granted scopes.
+
+You have to make sure you've added addtional claims via ``get_aditional_claims``
+and defined the ``OAUTH2_PROVIDER["SCOPES"]`` in your settings in order for this functionality to work.
+
+
+Using the OIDC "claims" request parameter to determine which claims are returned
+--------------------------------------------------------------------------------
+
+Besides using standard OIDC scopes, you can use OIDC's
+`5.5 Requesting Claims using the "claims" Request Parameter`_ feature.
+
+TODO - confirm that this works and document so and whether it interferes with the scope stuff.
+
+
 .. note::
     This ``request`` object is not a ``django.http.Request`` object, but an
     ``oauthlib.common.Request`` object. This has a number of attributes that
     you can use to decide what claims to put in to the ID token:
 
-    * ``request.scopes`` - a list of the scopes requested by the client when
-      making an authorization request.
-    * ``request.claims`` - a dictionary of the requested claims, using the
-      `OIDC claims requesting system`_. These must be requested by the client
-      when making an authorization request.
+    * ``request.scopes`` - is `NOT the list of granted scopes <https://github.com/oauthlib/oauthlib/issues/799>`_. For that, use:
+    * ``request.access_token.scopes`` - the list of granted scopes.
+    * ``request.claims`` - a dictionary of the claims.
     * ``request.user`` - the django user object.
 
-.. _OIDC claims requesting system: https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter
+.. _5.4 Requesting Claims using Scope Values: https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims
+.. _5.5 Requesting Claims using the "claims" Request Parameter: https://openid.net/specs/openid-connect-core-1_0.html#ClaimsParameter
 
 What claims you decide to put in to the token is up to you to determine based
 upon what the scopes and / or claims means to your provider.
@@ -307,11 +347,11 @@ Adding information to the ``UserInfo`` service
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The ``UserInfo`` service is supplied as part of the OIDC service, and is used
-to retrieve more information about the user than was supplied in the ID token
-when the user logged in to the OIDC client application. It is optional to use
-the service. The service is accessed by making a request to the
+to retrieve information about the user given their Access Token.
+It is optional to use the service. The service is accessed by making a request to the
 ``UserInfo`` endpoint, eg ``/o/userinfo/`` and supplying the access token
-retrieved at login as a ``Bearer`` token.
+retrieved at login as a ``Bearer`` token or as a form-encoded ``access_token`` body parameter
+for a POST request.
 
 Again, to modify the content delivered, we need to add a function to our
 custom validator. The default implementation adds the claims from the ID