Package: easyjwt
EasyJWTEasyJWT provides a simple interface to creating and verifyingJSON Web Tokens (JWTs)in Python. It allows you to once define the claims of the
JWT, and to then create and accept tokens with these claims without having to check if all the required data is given
or if the token actually is the one you expect.fromeasyjwtimportEasyJWT# Define the claims of your token.classMySuperSimpleJWT(EasyJWT):def__init__(self,key):super().__init__(key)# Define a claim `name`.self.name=None# Create a token with some values.token_object=MySuperSimpleJWT('Super secret key')token_object.name='Zaphod Beeblebrox'token=token_object.create()# Verify the created token.verified_token_object=MySuperSimpleJWT.verify(token,'Super secret key')assertverified_token_object.name=='Zaphod Beeblebrox'FeaturesDefine the claims of your token once as a class, then use this class to easily create and verify multiple tokens.No worries about typos in dictionary keys: the definition of your claim set as a class enables IDEs to find those
typos for you.Multiple tokens may have the same claims, but different intentions. EasyJWT will take care of this for you: you can
define a token for account validation and one for account deletion, both with the account ID as a claim, and you
don't need to worry about accidentally deleting a newly created account instead of validating it, just because
someone mixed up the tokens.Tokens will be rejected if mandatory claims are missing or unexpected claims are included.You can define optional claims for your tokens.All registered JWT claims are supported:aud,exp,iat,iss,jti,nbf, andsub.System Requirements & InstallationEasyJWT requires Python 3.6 or newer.EasyJWT is availableon PyPI. You can install it using your favorite package
manager.PIP:python-mpipinstalleasyjwtPipenv:pipenvinstalleasyjwtUsageBefore you can create tokens, you need to define the claims that your token will have. You do this by creating a token
class that inherits fromEasyJWT. In its__init__method, you specify the claims of your token, simply by defining
attributes with the name of your claims. EasyJWT will consider all attributes to be claims, unless they start with an
underscore_. Remember to call the__init__method on the parent class to correctly initialize the objects of your
class.fromeasyjwtimportEasyJWTclassMySuperSimpleJWT(EasyJWT):def__init__(self,key):super().__init__(key)# These are the claims of your token: `name` and `email`.self.name=Noneself.email=None# This attribute will not become a claim since it starts with an underscore.self._not_an_attribute=TrueYou can now create the actual token by instantiating your class with the key with which the token will be encoded,
setting your values on this token object, and then calling EasyJWT'screatemethod.token_object=MySuperSimpleJWT('Super secret key')token_object.name='Zaphod Beeblebrox'token_object.email='elprez@universe.gov'token=token_object.create()If you forget to set the value of one your claims, the creation will fail with anMissingRequiredClaimsErrorexception (see below for information on how to defineoptional claims).Once you receive a token to verify, you simply pass it and the key with which it has been encoded to EasyJWT'sverifymethod. If the token is valid, the returned object will contain the values of the token.verified_token_object=MySuperSimpleJWT.verify(token,'Super secret key')assertverified_token_object.name=='Zaphod Beeblebrox'assertverified_token_object.email=='elprez@universe.gov'If you try to verify a token that is missing one or more of the claims specified in your token class, or it includes one
or more claims that you did not specify in your token class, the verification will fail by raising anInvalidClaimSetErrorexception. Thus, you always know that the data you expect in the token will in fact be present.The neat thing about EasyJWT is: it knows with which class a token has been created, and will only accept tokens if they
have been created with the class with which you are trying to verify it (see belowfor more information and how to disable this behavior). Thus, you can have multiple token classes with the same claims,
but different contexts, and you don't have to worry about mixing up their tokens!fromeasyjwtimportEasyJWTclassAccountValidationToken(EasyJWT):""" Validate the newly created user account with the specified ID. """def__init__(self,key):super().__init__(key)self.user_id=NoneclassAccountDeletionToken(EasyJWT):""" Delete the user account with the specified ID. """def__init__(self,key):super().__init__(key)self.user_id=Nonevalidation_token_object=AccountValidationToken('Super secret key')validation_token_object.user_id=42validation_token=validation_token_object.create()# Verifying the validation token with the deletion token class will fail!# AccountDeletionToken.verify(validation_token, 'Super secret key')If you try to verify a token with a wrong class, EasyJWT will automatically reject your token by raising anInvalidClassErrorexception.Accepting Third-Party TokensBy default, EasyJWT will only accept tokens that have been created by the class with which you verify
it.[1]This is
done by including a special claim in the token upon creation. This claim is required when verifying a token. Tokens
without this claim or with a wrong value for this claim will fail verification. Usually, tokens from other sources will
not include this claim, and thus the validation of such a token will fail.You can disable the verification of this special claim by setting a special flag in your token class. This flag will
also prevent the special claim from being included in the created tokens.fromeasyjwtimportEasyJWTclassThirdPartyJWT(EasyJWT):# Disable the validation of the special claim.strict_verification=False# The usual definition of the token's claim set ...If you try to verify a token without this special claim and without disabling the strict verification mode, EasyJWT
will raise anUnspecifiedClassErrorexception.[1]: To be precise, the name of the class with which the token has been created must
be the same as the name of the class with which it is being verified. This class name is included in each token
created by EasyJWT in the special claim_easyjwt_class.Encoding AlgorithmsTokens created by EasyJWT are encoded using the HS256 algorithm by default. If you want to use a different algorithm,
you can specify this algorithm in the definition of your token class.fromeasyjwtimportAlgorithmfromeasyjwtimportEasyJWTclassMySuperSimpleJWT(EasyJWT):# Use the HS512 algorithm.algorithm=Algorithm.HS512# The usual definition of the token's claim set ...If you have previously created tokens with your token class, and later want to change the algorithm for new tokens,
you should tell EasyJWT to still use the previous algorithms for decoding tokens. Otherwise, tokens created with the old
version of your code cannot be verified!fromeasyjwtimportAlgorithmfromeasyjwtimportEasyJWTclassMySuperSimpleJWT(EasyJWT):# Use the HS512 algorithm.algorithm=Algorithm.HS512# Previously, tokens have been encoded with HS256, EasyJWT's default algorithm.# Thus, list it here.previous_algorithms={Algorithm.HS256}# The usual definition of the token's claim set ...You can find a list of all available algorithms in theAPI documentation.Optional ClaimsAll the claims you specify in the__init__method of your token class are mandatory, both for creating a token of this
class and for verifying a token. If you want some of these claims to be optional (both for creating and verifying a
token), you can override EasyJWT's_optional_claimsclass variable. You can override this class variable in your token
class to include the names of your optional claims. Note that you must include the value ofEasyJWT._optional_claimsin your class. Otherwise, the registered claims will become mandatory.fromeasyjwtimportEasyJWTclassMySuperSimpleJWT(EasyJWT):# The claim `my_optional_claim` is optional. All other claims are still mandatory._optional_claims=EasyJWT._optional_claims.union({'my_optional_claim'})def__init__(self,key):super().__init__(key)self.my_optional_claim=Noneself.my_mandatory_claim=Nonetoken_object=MySuperSimpleJWT('Super secret key')token_object.my_mandatory_claim='Some value'token=token_object.create()Registered ClaimsEasyJWT supports all registered claims of the JWT specification:aud,exp,iat,iss,jti,nbf, andsub.
All of these claims are optional.Audience:audThe audience identifies the recipients of the token, and can either be a string or a list of strings.You can set an audience for your token using the attributeaudienceof your token object. This attribute will
automatically be mapped to theaudclaim when creating the token.fromeasyjwtimportEasyJWTclassMySuperSimpleJWT(EasyJWT):def__init__(self,key):super().__init__(key)self.name=Nonetoken_object=MySuperSimpleJWT('Super secret key')token_object.name='Zaphod Beeblebrox'# This token is intended for everyone, and especially for Zaphod Beeblebrox.token_object.audience=['Zaphod Beeblebrox','Everyone']token=token_object.create()To verify a token with an audience, you must pass at least one of the audience values to EasyJWT'sverifymethod.
Otherwise, the verification will fail with anInvalidAudienceErrorexception. After the verification, the token's
audience will be set on theaudienceattribute.# We are everyone, so this token is intended for us.verified_token_object=MySuperSimpleJWT.verify(token,'Super secret key',audience='Everyone')assertverified_token_object.audience==['Zaphod Beeblebrox','Everyone']Expiration Date:expThe expiration date specifies how long the token will be valid. If a token with an expiration date is verified after its
expiration date has passed, the token will be invalid.You can set an expiration date for your token using the attributeexpiration_dateto adatetimeobject. This
attribute will automatically be mapped to theexpclaim when creating the token. Note that you must specify the
expiration date in UTC.importdatetimefromeasyjwtimportEasyJWTclassMySuperSimpleJWT(EasyJWT):def__init__(self,key):super().__init__(key)self.name=Nonetoken_object=MySuperSimpleJWT('Super secret key')token_object.name='Zaphod Beeblebrox'# This token will expire in 15 minutes.token_object.expiration_date=datetime.datetime.utcnow()+datetime.timedelta(minutes=15)token=token_object.create()When verifying a token with an expiration date, EasyJWT automatically checks if the expiration date has passed. If this
is the case, the verification will fail with anExpiredTokenErrorexception. After the verification, the token's
expiration date will be set on theexpiration_dateattribute as adatetimeobject in UTC.Issued At:iatThe issued at-date specifies the token's time of creation.When creating a token, this claim will automatically be set to the current time. If you want to set a different
issued at-date, you can pass adatetimeobject (in UTC) to the optionalissued_atparameter of EasyJWT'screatemethod.importdatetimefromeasyjwtimportEasyJWTclassMySuperSimpleJWT(EasyJWT):def__init__(self,key):super().__init__(key)self.name=Nonetoken_object=MySuperSimpleJWT('Super secret key')token_object.name='Zaphod Beeblebrox'# This token was issued five minutes ago.token=token_object.create(issued_at=datetime.datetime.utcnow()-datetime.timedelta(minutes=5))After verifying a token with an issued at-date, its issued at-date will be set on theissued_at_dateattribute.Issuer:issThe issuer identifies the creator of the token.You can set the issuer of your token using theissuerattribute of your token object. This attribute will
automatically be mapped to theissclaim when creating the token.fromeasyjwtimportEasyJWTclassMySuperSimpleJWT(EasyJWT):def__init__(self,key):super().__init__(key)self.name=Nonetoken_object=MySuperSimpleJWT('Super secret key')token_object.name='Zaphod Beeblebrox'# This token is intended for everyone, and especially for Zaphod Beeblebrox.token_object.issuer='Arthur Dent'token=token_object.create()To verify a token with an issuer, you must pass the issuer specified in the token to EasyJWT'sverifymethod.
Otherwise, the verification will fail with anInvalidIssuerErrorexception. After the verification, the token's issuer
will be set on theissuerattribute.# We are everyone, so this token is intended for us.verified_token_object=MySuperSimpleJWT.verify(token,'Super secret key',issuer='Arthur Dent')assertverified_token_object.issuer=='Arthur Dent'JWT ID:jtiThe JWT ID is an identifier for your token. It must be unique for each token.You can set the JWT ID of your token using theJWT_IDattribute of your token object. This attribute will
automatically be mapped to thejticlaim when creating the tokenfromeasyjwtimportEasyJWTclassMySuperSimpleJWT(EasyJWT):def__init__(self,key):super().__init__(key)self.name=Nonetoken_object=MySuperSimpleJWT('Super secret key')token_object.name='Zaphod Beeblebrox'# This ID must be unique for each token.token_object.JWT_ID='My super simple JWT 1'token=token_object.create()After verifying a token with a JWT ID, this ID will be set on theJWT_IDattribute.Note that this claim is not verified by EasyJWT. It is your responsibility to validate it after verifying the token if
you need this validation.Not Before:nbfThe not before-date specifies the time before which the token will not be valid. If a token with a not before-date is
verified before its not before-date has been reached, the token will be invalid.You can set a not before-date for your token using the attributenot_before_dateto a datetime object. This attribute
will automatically be mapped to thenbfclaim when creating the token. Note that you must specify the not before-date
in UTC.importdatetimefromeasyjwtimportEasyJWTclassMySuperSimpleJWT(EasyJWT):def__init__(self,key):super().__init__(key)self.name=Nonetoken_object=MySuperSimpleJWT('Super secret key')token_object.name='Zaphod Beeblebrox'# This token will be valid in 5 minutes.token_object.not_before_date=datetime.datetime.utcnow()+datetime.timedelta(minutes=5)token=token_object.create()When verifying a token with a not before-date, EasyJWT automatically checks if the not before-date has been reached. If
this is not the case, the verification will fail with anImmatureTokenErrorexception. After the verification, the
token's not before-date will be set on thenot_before_dateattribute as adatetimeobject in UTC.Subject:subThe subject specifies the topic of your token.You can set the subject of your token using thesubjectattribute of your token object. This attribute will
automatically be mapped to thesubclaim when creating the token.fromeasyjwtimportEasyJWTclassMySuperSimpleJWT(EasyJWT):def__init__(self,key):super().__init__(key)self.name=Nonetoken_object=MySuperSimpleJWT('Super secret key')token_object.name='Zaphod Beeblebrox'# This token is all about Douglas Adams' master work.token_object.subject='The Hitchhiker\'s Guide to the Galaxy'token=token_object.create()After verifying a token with a subject, this subject will be set on thesubjectattribute.Note that this claim is not verified by EasyJWT. It is your responsibility to validate it after verifying the token if
you need this validation.Future IdeasAllow creating tokens without an issued at-date.Add a mode to accept arbitrary claims and create corresponding attributes as needed.Allow specifying functions to pack and unpack claim values before creating a token and after verifying a token,
respectively.AcknowledgementsEasyJWT is just an easy-to-use abstraction layer around José Padilla'sPyJWT librarythat does the actual work of creating and verifying the tokens according to the JWT specification. Without his work,
EasyJWT would not be possible.LicenseEasyJWT is developed byBastian Meyer<bastian@bastianmeyer.eu> and is licensed under theMIT License. For details, see the attachedLICENSEfile.