Merge pull request jpadilla#60 from wbolster/issue-59

Add base exception for invalid tokens

Author: jpadilla

README.md

@@ -43,6 +43,16 @@ You can still get the payload by setting the `verify` argument to `False`.
 jwt.decode('someJWTstring', verify=False)
 ```
 
+The `decode()` function can raise other exceptions, e.g. for invalid issuer or audience (see below). All exceptions that signify that the token is invalid extend from the base `InvalidTokenError` exception class, so applications can use this approach to catch any issues relating to invalid tokens:
+
+```python
+try:
+    payload = jwt.decode('someJWTstring')
+except jwt.InvalidTokenError:
+    pass  # do something sensible here, e.g. return HTTP 403 status code
+```
+
+
 ## Algorithms
 
 The JWT spec supports several algorithms for cryptographic signing. This library
@@ -112,14 +122,14 @@ jwt.encode({'exp': datetime.utcnow()}, 'secret')
 ```
 
 Expiration time is automatically verified in `jwt.decode()` and raises
-`jwt.ExpiredSignature` if the expiration time is in the past:
+`jwt.ExpiredSignatureError` if the expiration time is in the past:
 
 ```python
 import jwt
 
 try:
     jwt.decode('JWT_STRING', 'secret')
-except jwt.ExpiredSignature:
+except jwt.ExpiredSignatureError:
     # Signature has expired
 ```
 
@@ -187,6 +197,9 @@ token = jwt.encode(payload, 'secret')
 decoded = jwt.decode(token, 'secret', issuer='urn:foo')
 ```
 
+If the issuer claim is incorrect, `jwt.InvalidIssuerError` will be raised.
+
+
 ### Audience Claim
 
 > The aud (audience) claim identifies the recipients that the JWT is intended for. Each principal intended to process the JWT MUST identify itself with a value in the audience claim. If the principal processing the claim does not identify itself with a value in the aud claim when this claim is present, then the JWT MUST be rejected. In the general case, the aud value is an array of case-sensitive strings, each containing a StringOrURI value. In the special case when the JWT has one audience, the aud value MAY be a single case-sensitive string containing a StringOrURI value. The interpretation of audience values is generally application specific. Use of this claim is OPTIONAL.
@@ -204,6 +217,9 @@ token = jwt.encode(payload, 'secret')
 decoded = jwt.decode(token, 'secret', audience='urn:foo')
 ```
 
+If the audience claim is incorrect, `jwt.InvalidAudienceError` will be raised.
+
+
 ## License
 
 MIT

jwt/__init__.py

@@ -28,27 +28,49 @@
 
 __version__ = '0.4.0'
 __all__ = [
-    'encode', 'decode', 'DecodeError', 'ExpiredSignature',
-    'InvalidAudience', 'InvalidIssuer'
+    # Functions
+    'encode',
+    'decode',
+
+    # Exceptions
+    'InvalidTokenError',
+    'DecodeError',
+    'ExpiredSignatureError',
+    'InvalidAudienceError',
+    'InvalidIssuerError'
+
+    # Deprecated aliases
+    'ExpiredSignature',
+    'InvalidAudience',
+    'InvalidIssuer',
 ]
 
 
-class DecodeError(Exception):
+class InvalidTokenError(Exception):
     pass
 
 
-class ExpiredSignature(Exception):
+class DecodeError(InvalidTokenError):
     pass
 
 
-class InvalidAudience(Exception):
+class ExpiredSignatureError(InvalidTokenError):
     pass
 
 
-class InvalidIssuer(Exception):
+class InvalidAudienceError(InvalidTokenError):
     pass
 
 
+class InvalidIssuerError(InvalidTokenError):
+    pass
+
+
+# Compatibility aliases (deprecated)
+ExpiredSignature = ExpiredSignatureError
+InvalidAudience = InvalidAudienceError
+InvalidIssuer = InvalidIssuerError
+
 signing_methods = {
     'none': lambda msg, key: b'',
     'HS256': lambda msg, key: hmac.new(key, msg, hashlib.sha256).digest(),
@@ -395,13 +417,13 @@ def verify_signature(payload, signing_input, header, signature, key='',
         utc_timestamp = timegm(datetime.utcnow().utctimetuple())
 
         if payload['nbf'] > (utc_timestamp + leeway):
-            raise ExpiredSignature('Signature not yet valid')
+            raise ExpiredSignatureError('Signature not yet valid')
 
     if 'exp' in payload and verify_expiration:
         utc_timestamp = timegm(datetime.utcnow().utctimetuple())
 
         if payload['exp'] < (utc_timestamp - leeway):
-            raise ExpiredSignature('Signature has expired')
+            raise ExpiredSignatureError('Signature has expired')
 
     if audience is not None:
         if isinstance(audience, list):
@@ -410,8 +432,8 @@ def verify_signature(payload, signing_input, header, signature, key='',
             audiences = [audience]
 
         if payload.get('aud') not in audiences:
-            raise InvalidAudience('Invalid audience')
+            raise InvalidAudienceError('Invalid audience')
 
     if issuer is not None:
         if payload.get('iss') != issuer:
-            raise InvalidIssuer('Invalid issuer')
+            raise InvalidIssuerError('Invalid issuer')

tests/test_jwt.py

@@ -357,13 +357,13 @@ def test_decode_with_expiration(self):
         jwt_message = jwt.encode(self.payload, secret)
 
         self.assertRaises(
-            jwt.ExpiredSignature,
+            jwt.ExpiredSignatureError,
             lambda: jwt.decode(jwt_message, secret))
 
         decoded_payload, signing, header, signature = jwt.load(jwt_message)
 
         self.assertRaises(
-            jwt.ExpiredSignature,
+            jwt.ExpiredSignatureError,
             lambda: jwt.verify_signature(
                 decoded_payload, signing, header, signature, secret))
 
@@ -373,13 +373,13 @@ def test_decode_with_notbefore(self):
         jwt_message = jwt.encode(self.payload, secret)
 
         self.assertRaises(
-            jwt.ExpiredSignature,
+            jwt.ExpiredSignatureError,
             lambda: jwt.decode(jwt_message, secret))
 
         decoded_payload, signing, header, signature = jwt.load(jwt_message)
 
         self.assertRaises(
-            jwt.ExpiredSignature,
+            jwt.ExpiredSignatureError,
             lambda: jwt.verify_signature(
                 decoded_payload, signing, header, signature, secret))
 
@@ -422,11 +422,11 @@ def test_decode_with_expiration_with_leeway(self):
         # With 1 seconds, should fail
         for leeway in (1, timedelta(seconds=1)):
             self.assertRaises(
-                jwt.ExpiredSignature,
+                jwt.ExpiredSignatureError,
                 lambda: jwt.decode(jwt_message, secret, leeway=leeway))
 
             self.assertRaises(
-                jwt.ExpiredSignature,
+                jwt.ExpiredSignatureError,
                 lambda: jwt.verify_signature(decoded_payload, signing,
                                              header, signature, secret,
                                              leeway=leeway))
@@ -446,11 +446,11 @@ def test_decode_with_notbefore_with_leeway(self):
 
         # With 1 seconds, should fail
         self.assertRaises(
-            jwt.ExpiredSignature,
+            jwt.ExpiredSignatureError,
             lambda: jwt.decode(jwt_message, secret, leeway=1))
 
         self.assertRaises(
-            jwt.ExpiredSignature,
+            jwt.ExpiredSignatureError,
             lambda: jwt.verify_signature(decoded_payload, signing,
                                          header, signature, secret, leeway=1))
 
@@ -737,7 +737,7 @@ def test_raise_exception_invalid_audience(self):
         token = jwt.encode(payload, 'secret')
 
         self.assertRaises(
-            jwt.InvalidAudience,
+            jwt.InvalidAudienceError,
             lambda: jwt.decode(token, 'secret', audience=audience))
 
     def test_raise_exception_invalid_audience_in_array(self):
@@ -751,7 +751,7 @@ def test_raise_exception_invalid_audience_in_array(self):
         token = jwt.encode(payload, 'secret')
 
         self.assertRaises(
-            jwt.InvalidAudience,
+            jwt.InvalidAudienceError,
             lambda: jwt.decode(token, 'secret', audience=audience))
 
     def test_raise_exception_token_without_audience(self):
@@ -764,7 +764,7 @@ def test_raise_exception_token_without_audience(self):
         token = jwt.encode(payload, 'secret')
 
         self.assertRaises(
-            jwt.InvalidAudience,
+            jwt.InvalidAudienceError,
             lambda: jwt.decode(token, 'secret', audience=audience))
 
     def test_raise_exception_token_without_audience_in_array(self):
@@ -777,7 +777,7 @@ def test_raise_exception_token_without_audience_in_array(self):
         token = jwt.encode(payload, 'secret')
 
         self.assertRaises(
-            jwt.InvalidAudience,
+            jwt.InvalidAudienceError,
             lambda: jwt.decode(token, 'secret', audience=audience))
 
     def test_check_issuer(self):
@@ -804,7 +804,7 @@ def test_raise_exception_invalid_issuer(self):
         token = jwt.encode(payload, 'secret')
 
         self.assertRaises(
-            jwt.InvalidIssuer,
+            jwt.InvalidIssuerError,
             lambda: jwt.decode(token, 'secret', issuer=issuer))
 
     def test_raise_exception_token_without_issuer(self):
@@ -817,7 +817,7 @@ def test_raise_exception_token_without_issuer(self):
         token = jwt.encode(payload, 'secret')
 
         self.assertRaises(
-            jwt.InvalidIssuer,
+            jwt.InvalidIssuerError,
             lambda: jwt.decode(token, 'secret', issuer=issuer))
 
     def test_custom_json_encoder(self):