# py-jwt-verifier
Python JWT Verfier - Verifies the signature of a digitally signed JWT.
----------------
## Realease notes
Version | Release notes
------------ | -------------
0.7.0 | Added support for Salesforce. Minor fixes. Latest stable version. Re-named to py_jwt_verifier.
0.6.0 | Added support for Google, Microsoft and Auth0.
0.5.0 | **MAJOR Release.** Production stable. Added cache control.
0.4.0-beta | Security fix. Certificate Chain is mandatory for Okta Custom URL Domain.
0.3.0-beta | Minor release. Added support for Okta Custom URL Domain.
0.2.0-beta | Minor release. Added support for AWS Cognito JWT.
0.1.0-beta | Minor release. Increased configurability.
0.0.1-beta | First package release.
**PyPy**: https://pypi.org/project/py-jwt-verifier/
----------------
## Supported IdPs
* Okta
* AWS Cognito
* Google
* Microsoft
* Auth0
* Salesforce
----------------
## Supported Signing Algorithms
* RS256
----------------
## Disclaimer
This library is provded as is. None of the listed IdPs will provide support for issues related with the present library. I am the sole maintainer of it.
----------------
## Process Chain
1. Once the class is instantiated the following checks are performed:
* JWT Format.
* JWT Expiration time.
* JWT Claims if given when the class was instantiated.
* Is Algorithm Supported.
2. After the above checks are done, it will verify the token signature with the apropriate signing algorithm based on the "alg" header claim. If the signature is valid, it will return **None**. Else, it will raise a exception.
* If a check fails at any given step, the exception **PyJwtException** will be raised.
* The /.well-knwon/openid-configuration endoint will be compiled based on the 'iss' claim.
* The /keys endpoint will be determined from the output of the /.well-knwon/openid-configuration endpoint
* The response from /keys will be cached (**requests_cache**) for subsequent calls.
----------------
## Installation
```
pip install py-jwt-verifier
```
----------------
## Usage Examples
```
from py_jwt_verifier import PyJwtVerifier, PyJwtException
jwt = access_token / id_token
try:
PyJwtVerifier(jwt)
except PyJwtException as e:
print(f"Exception caught. Error: {e}")
```
* If **auto_verify** is set to **False** the class will not perform the signature validation. To check the signature the **verify()** method needs to be used. By default, the method will return None. In order to return the decoded jwt data (header + payload) **True** has to be passed. Example:
```
from py_jwt_verifier import PyJwtVerifier, PyJwtException
jwt = access_token / id_token
validator = PyJwtVerifier(jwt, auto_verify=False)
try:
payload = validator.verify(True)
print(payload)
except PyJwtException as e:
print(f"Exception caught. Error: {e}")
```
**Custom Claim Validation:**
```
from py_jwt_verifier import PyJwtVerifier, PyJwtException
jwt = access_token / id_token
validator = PyJwtVerifier(jwt, auto_verify=False, custom_claim_name="custom_claim_value")
try:
payload = validator.verify(True)
print(payload)
except PyJwtException as e:
print(f"Exception caught. Error: {e}")
```
**Cache Control:**
* redis
```
from redis import StrictRedis
from py_jwt_verifier import PyJwtVerifier, PyJwtException
redis = StrictRedis(host="localhost", port=6390)
jwt = access_token / id_token
validator = PyJwtVerifier(jwt, auto_verify=False, cache_store="redis", cache_store_connection=redis)
try:
payload = validator.verify(True)
print(payload)
except PyJwtException as e:
print(f"Exception caught. Error: {e}")
```
* pymongo
```
from pymongo import MongoClient
from py_jwt_verifier import PyJwtVerifier, PyJwtException
mongo = MongoClient("localhost", 27017)
jwt = access_token / id_token
validator = PyJwtVerifier(jwt, auto_verify=False, cache_store="mongo", cache_store_connection=mongo)
try:
payload = validator.verify(True)
print(payload)
except PyJwtException as e:
print(f"Exception caught. Error: {e}")
```
----------------
## Class Attributes
* The class **PyJwtVerifier** currently accepts:
Attribute | Required | Default value
----------|----------|--------------
jwt | Yes | **None**
cid - OIDC Client ID | No | **None**
aud - Audience | No | **None**
iss - Issuer | No | **None**
auto_verify | No | **True**
check_expiry | No | **True**
cache_enabled | No | **True**
cache_lifetime | No | **1 day**
cache_store | No | **sqlite**
cache_store_connection | No | **None**
* The class method **verify()** currently accepts:
Attribute | Required | Default value
----------|----------|--------------
get_payload | No | **False**
## Note
The reason why this class returns **None** or exception is to provide more flexibility. Not everyone needs to return the decoded payload of the jwt.
It is recommended to use it within **try:** **except** blocks.
----------------
## Cache Control
This library relies on the **requests** and **requests_cache** libraries. The caching control mechanism was implemented around these libraries.
### Cache Control attributes explained
* cache_enabled - Attribute type: Boolean - Accepted Values: True / False. Determines if the cache control mechanism will be used. If set to False, the response from the /.well-knwon/openid-configuration and /keys endpoints will never be cached.
* cache_lifetime - Attribute type: Integer - Accepted Values: 1 - 30. Represents the number of *days* the cache will be stored and used. The maximum value can not be higher than 30 days or less than 1 day.
* cache_store - Attribute type: String - Accepted Values: "memory", "sqlite", "mongo", "redis". Determines how and where the **requests_cache** library will store the responses and connect to the caching store. When there is no cache_store_connection provided, it will rely on the defaults for mongo and redis.
* cache_store_connection - Attribute type: DB instance object - Should be used only when the cache_store is set to "mongo" or "redis". This is necessary for production environments so you can specify the host, port, database, user and password to use to connect to the respective caching database selected.
### Note
When using redis or mongo as caching database solutions, the appropriate python connector libraries will be required (pymongo / redis).
For additional information in regards of how **requests_cache** works, please review their docs: https://requests-cache.readthedocs.io/en/latest/
----------------
## SUGGESTIONS?
Please feel free to email me at adrian.lazar95@outlook.com or lzr.adrian95@gmail.com. I am opened to improvement / suggestions and critics.
Raw data
{
"_id": null,
"home_page": "https://github.com/adrianlzr/py-jwt-verifier",
"name": "py-jwt-verifier",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.0",
"maintainer_email": "",
"keywords": "python jwt verifier,jwt verifier,jwt signature verifier,py-jwt-verifier,python-jwt-verifier,python jwt signature verifier",
"author": "Adrian Lazar",
"author_email": "adrian.lazar95@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/e8/9e/7e9c9811d9d64e96182010c23e081b5caecb7255c561be57bb08bdf51552/py_jwt_verifier-0.8.0.tar.gz",
"platform": null,
"description": "# py-jwt-verifier\n\nPython JWT Verfier - Verifies the signature of a digitally signed JWT.\n----------------\n\n\n## Realease notes\nVersion | Release notes\n------------ | -------------\n0.7.0 | Added support for Salesforce. Minor fixes. Latest stable version. Re-named to py_jwt_verifier.\n0.6.0 | Added support for Google, Microsoft and Auth0.\n0.5.0 | **MAJOR Release.** Production stable. Added cache control.\n0.4.0-beta | Security fix. Certificate Chain is mandatory for Okta Custom URL Domain.\n0.3.0-beta | Minor release. Added support for Okta Custom URL Domain.\n0.2.0-beta | Minor release. Added support for AWS Cognito JWT.\n0.1.0-beta | Minor release. Increased configurability.\n0.0.1-beta | First package release.\n\n\n**PyPy**: https://pypi.org/project/py-jwt-verifier/\n----------------\n\n\n## Supported IdPs\n* Okta\n* AWS Cognito\n* Google \n* Microsoft\n* Auth0\n* Salesforce\n\n----------------\n\n\n## Supported Signing Algorithms\n* RS256\n\n----------------\n\n\n## Disclaimer\nThis library is provded as is. None of the listed IdPs will provide support for issues related with the present library. I am the sole maintainer of it.\n\n----------------\n\n\n## Process Chain\n1. Once the class is instantiated the following checks are performed:\n * JWT Format.\n * JWT Expiration time.\n * JWT Claims if given when the class was instantiated.\n * Is Algorithm Supported.\n\n2. After the above checks are done, it will verify the token signature with the apropriate signing algorithm based on the \"alg\" header claim. If the signature is valid, it will return **None**. Else, it will raise a exception.\n\n * If a check fails at any given step, the exception **PyJwtException** will be raised.\n * The /.well-knwon/openid-configuration endoint will be compiled based on the 'iss' claim.\n * The /keys endpoint will be determined from the output of the /.well-knwon/openid-configuration endpoint\n * The response from /keys will be cached (**requests_cache**) for subsequent calls.\n \n----------------\n\n\n## Installation\n```\npip install py-jwt-verifier\n```\n\n----------------\n\n\n## Usage Examples\n```\nfrom py_jwt_verifier import PyJwtVerifier, PyJwtException\njwt = access_token / id_token\ntry:\n PyJwtVerifier(jwt)\nexcept PyJwtException as e:\n print(f\"Exception caught. Error: {e}\")\n```\n\n* If **auto_verify** is set to **False** the class will not perform the signature validation. To check the signature the **verify()** method needs to be used. By default, the method will return None. In order to return the decoded jwt data (header + payload) **True** has to be passed. Example:\n```\nfrom py_jwt_verifier import PyJwtVerifier, PyJwtException\njwt = access_token / id_token\nvalidator = PyJwtVerifier(jwt, auto_verify=False)\ntry:\n payload = validator.verify(True)\n print(payload)\nexcept PyJwtException as e:\n print(f\"Exception caught. Error: {e}\")\n```\n\n**Custom Claim Validation:**\n\n```\nfrom py_jwt_verifier import PyJwtVerifier, PyJwtException\njwt = access_token / id_token\nvalidator = PyJwtVerifier(jwt, auto_verify=False, custom_claim_name=\"custom_claim_value\")\ntry:\n payload = validator.verify(True)\n print(payload)\nexcept PyJwtException as e:\n print(f\"Exception caught. Error: {e}\")\n```\n\n\n**Cache Control:**\n\n* redis\n\n```\nfrom redis import StrictRedis\nfrom py_jwt_verifier import PyJwtVerifier, PyJwtException\n\n\nredis = StrictRedis(host=\"localhost\", port=6390)\n\njwt = access_token / id_token\nvalidator = PyJwtVerifier(jwt, auto_verify=False, cache_store=\"redis\", cache_store_connection=redis)\ntry:\n payload = validator.verify(True)\n print(payload)\nexcept PyJwtException as e:\n print(f\"Exception caught. Error: {e}\")\n```\n\n* pymongo\n\n```\nfrom pymongo import MongoClient\nfrom py_jwt_verifier import PyJwtVerifier, PyJwtException\n\n\nmongo = MongoClient(\"localhost\", 27017)\n\njwt = access_token / id_token\nvalidator = PyJwtVerifier(jwt, auto_verify=False, cache_store=\"mongo\", cache_store_connection=mongo)\ntry:\n payload = validator.verify(True)\n print(payload)\nexcept PyJwtException as e:\n print(f\"Exception caught. Error: {e}\")\n```\n\n----------------\n\n\n## Class Attributes\n* The class **PyJwtVerifier** currently accepts:\n\nAttribute | Required | Default value\n----------|----------|--------------\njwt | Yes | **None**\ncid - OIDC Client ID | No | **None**\naud - Audience | No | **None**\niss - Issuer | No | **None**\nauto_verify | No | **True**\ncheck_expiry | No | **True**\ncache_enabled | No | **True**\ncache_lifetime | No | **1 day**\ncache_store | No | **sqlite**\ncache_store_connection | No | **None**\n\n* The class method **verify()** currently accepts:\n\nAttribute | Required | Default value\n----------|----------|--------------\nget_payload | No | **False**\n\n## Note\n\nThe reason why this class returns **None** or exception is to provide more flexibility. Not everyone needs to return the decoded payload of the jwt. \nIt is recommended to use it within **try:** **except** blocks.\n \n----------------\n\n\n## Cache Control\nThis library relies on the **requests** and **requests_cache** libraries. The caching control mechanism was implemented around these libraries. \n\n\n### Cache Control attributes explained\n* cache_enabled - Attribute type: Boolean - Accepted Values: True / False. Determines if the cache control mechanism will be used. If set to False, the response from the /.well-knwon/openid-configuration and /keys endpoints will never be cached. \n* cache_lifetime - Attribute type: Integer - Accepted Values: 1 - 30. Represents the number of *days* the cache will be stored and used. The maximum value can not be higher than 30 days or less than 1 day.\n* cache_store - Attribute type: String - Accepted Values: \"memory\", \"sqlite\", \"mongo\", \"redis\". Determines how and where the **requests_cache** library will store the responses and connect to the caching store. When there is no cache_store_connection provided, it will rely on the defaults for mongo and redis.\n* cache_store_connection - Attribute type: DB instance object - Should be used only when the cache_store is set to \"mongo\" or \"redis\". This is necessary for production environments so you can specify the host, port, database, user and password to use to connect to the respective caching database selected.\n\n### Note\nWhen using redis or mongo as caching database solutions, the appropriate python connector libraries will be required (pymongo / redis).\nFor additional information in regards of how **requests_cache** works, please review their docs: https://requests-cache.readthedocs.io/en/latest/\n\n----------------\n\n\n## SUGGESTIONS?\n\nPlease feel free to email me at adrian.lazar95@outlook.com or lzr.adrian95@gmail.com. I am opened to improvement / suggestions and critics. \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python JWT Verfier - Verifies the signature of a digitally signed JWT.",
"version": "0.8.0",
"project_urls": {
"Documentation & Source": "https://github.com/adrianlzr/py-jwt-verifier",
"Homepage": "https://github.com/adrianlzr/py-jwt-verifier",
"Issue Tracker": "https://github.com/adrianlzr/py-jwt-verifier/issues"
},
"split_keywords": [
"python jwt verifier",
"jwt verifier",
"jwt signature verifier",
"py-jwt-verifier",
"python-jwt-verifier",
"python jwt signature verifier"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "af6889fac470a465371b91535ef8e4dc9a8594ab026113bb41c97adab3c25209",
"md5": "a6d72a646ff165d4e8d41929ecf1151c",
"sha256": "0d652cdd05bbb8ff8383af8e19bd9b2504d86894fc373c92f029c3726ae9b268"
},
"downloads": -1,
"filename": "py_jwt_verifier-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a6d72a646ff165d4e8d41929ecf1151c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.0",
"size": 11206,
"upload_time": "2024-02-26T08:45:57",
"upload_time_iso_8601": "2024-02-26T08:45:57.406610Z",
"url": "https://files.pythonhosted.org/packages/af/68/89fac470a465371b91535ef8e4dc9a8594ab026113bb41c97adab3c25209/py_jwt_verifier-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e89e7e9c9811d9d64e96182010c23e081b5caecb7255c561be57bb08bdf51552",
"md5": "4cf0dd32fde094cc701ee75176e842a8",
"sha256": "b437b5118cda84f4d58131aec2e5a2cefed17041655197a6ddb754a6e615b261"
},
"downloads": -1,
"filename": "py_jwt_verifier-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "4cf0dd32fde094cc701ee75176e842a8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.0",
"size": 11757,
"upload_time": "2024-02-26T08:45:59",
"upload_time_iso_8601": "2024-02-26T08:45:59.066228Z",
"url": "https://files.pythonhosted.org/packages/e8/9e/7e9c9811d9d64e96182010c23e081b5caecb7255c561be57bb08bdf51552/py_jwt_verifier-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-26 08:45:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adrianlzr",
"github_project": "py-jwt-verifier",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "py-jwt-verifier"
}
JSON
