Update README.md

README.md

@@ -36,6 +36,56 @@ pip install guardpost[jwt]
 
 For examples, refer to the [examples folder](./examples).
 
+## Functions to validate JWTs
+
+GuardPost includes functions to validate JSON Web Tokens (JWTs) and handle
+JSON Web Keys Sets (JWKS).
+
+The built-in validator class can retrieve automatically JWKS from identity providers
+and handle automatically caching and keys rotation. Caching is useful to not incur in
+useless performance fees (e.g. downloading JWKS at each web request), and keys rotation
+is important because identity providers can periodically change the keys they use to
+sign JWTs.
+
+To use these features, install to include additional dependencies:
+
+```bash
+pip install guardpost[jwt]
+```
+
+The following example shows how to use guardpost to validate tokens:
+
+```python
+import asyncio
+from guardpost.jwts import JWTValidator
+
+
+async def main():
+    validator = JWTValidator(
+        authority="YOUR_AUTHORITY",
+        valid_issuers=["YOUR_ISSUER_VALUE"],
+        valid_audiences=["YOUR_AUDIENCE"],
+    )
+
+    # keys are fetched when necessary
+    data = await validator.validate_jwt("YOUR_TOKEN")
+
+    print(data)
+
+
+asyncio.run(main())
+```
+
+An example value for `authority`, to validate access tokens issued by
+Azure Active Directory could be: `https://sts.windows.net/YOUR_TENANT_ID/`.
+
+GuardPost is used in BlackSheep and has been tested with:
+
+- Auth0
+- Azure Active Directory
+- Azure Active Directory B2C
+- Okta
+
 ## If you have doubts about authentication vs authorization...
 `Authentication` answers the question: _Who is the user who is initiating the
 action?_, or more in general: _Who is the user, or what is the service, that is