Merge pull request #360 from idan/save-authorization_code-docs

Save authorization code docs

oauthlib/oauth2/rfc6749/request_validator.py

@@ -51,12 +51,6 @@ def authenticate_client(self, request, *args, **kwargs):
         both body and query can be obtained by direct attribute access, i.e.
         request.client_id for client_id in the URL query.
 
-        OBS! Certain grant types rely on this authentication, possibly with
-        other fallbacks, and for them to recognize this authorization please
-        set the client attribute on the request (request.client). Note that
-        preferably this client object should have a client_id attribute of
-        unicode type (request.client.client_id).
-
         :param request: oauthlib.common.Request
         :rtype: True or False
 
@@ -90,14 +84,14 @@ def authenticate_client_id(self, client_id, request, *args, **kwargs):
 
     def confirm_redirect_uri(self, client_id, code, redirect_uri, client,
                              *args, **kwargs):
-        """Ensure client is authorized to redirect to the redirect_uri requested.
-
-        If the client specifies a redirect_uri when obtaining code then
-        that redirect URI must be bound to the code and verified equal
-        in this method.
+        """Ensure that the authorization process represented by this authorization
+        code began with this 'redirect_uri'.
 
-        All clients should register the absolute URIs of all URIs they intend
-        to redirect to. The registration is outside of the scope of oauthlib.
+        If the client specifies a redirect_uri when obtaining code then that
+        redirect URI must be bound to the code and verified equal in this
+        method, according to RFC 6749 section 4.1.3.  Do not compare against
+        the client's allowed redirect URIs, but against the URI used when the
+        code was saved.
 
         :param client_id: Unicode client identifier
         :param code: Unicode authorization_code.
@@ -214,21 +208,25 @@ def rotate_refresh_token(self, request):
     def save_authorization_code(self, client_id, code, request, *args, **kwargs):
         """Persist the authorization_code.
 
-        The code should at minimum be associated with:
-            - a client and it's client_id
+        The code should at minimum be stored with:
+            - the client_id (client_id)
             - the redirect URI used (request.redirect_uri)
-            - whether the redirect URI used is the client default or not
             - a resource owner / user (request.user)
-            - authorized scopes (request.scopes)
+            - the authorized scopes (request.scopes)
+            - the client state, if given (code.get('state'))
 
-        The authorization code grant dict (code) holds at least the key 'code'::
+        The 'code' argument is actually a dictionary, containing at least a
+        'code' key with the actual authorization code:
 
             {'code': 'sdf345jsdf0934f'}
 
+        It may also have a 'state' key containing a nonce for the client, if it
+        chose to send one.  That value should be saved and used in
+        'validate_code'.
+
         :param client_id: Unicode client identifier
-        :param code: A dict of the authorization code grant.
+        :param code: A dict of the authorization code grant and, optionally, state.
         :param request: The HTTP Request (oauthlib.common.Request)
-        :rtype: The default redirect URI for the client
 
         Method is used by:
             - Authorization Code Grant
@@ -339,8 +337,15 @@ def validate_client_id(self, client_id, request, *args, **kwargs):
         raise NotImplementedError('Subclasses must implement this method.')
 
     def validate_code(self, client_id, code, client, request, *args, **kwargs):
-        """Ensure the authorization_code is valid and assigned to client.
+        """Verify that the authorization_code is valid and assigned to the given
+        client.
+
+        Before returning true, set the following based on the information stored
+        with the code in 'save_authorization_code':
 
+            - request.user
+            - request.state (if given)
+            - request.scopes
         OBS! The request.user attribute should be set to the resource owner
         associated with this authorization code. Similarly request.scopes
         must also be set.

tests/oauth2/rfc6749/endpoints/test_revocation_endpoint.py

@@ -32,6 +32,18 @@ def test_revoke_token(self):
             self.assertEqual(h, {})
             self.assertEqual(b, '')
             self.assertEqual(s, 200)
+
+    def test_revoke_token_without_client_authentication(self):
+        self.validator.client_authentication_required.return_value = False
+        self.validator.authenticate_client.return_value = False        
+        for token_type in ('access_token', 'refresh_token', 'invalid'):
+            body = urlencode([('token', 'foo'),
+                              ('token_type_hint', token_type)])
+            h, b, s = self.endpoint.create_revocation_response(self.uri,
+                    headers=self.headers, body=body)
+            self.assertEqual(h, {})
+            self.assertEqual(b, None)
+            self.assertEqual(s, 200)
 
     def test_revoke_token_without_client_authentication(self):
         self.validator.client_authentication_required.return_value = False