From ab605fecc0877fcbdf4535b11106c61c91d92ab3 Mon Sep 17 00:00:00 2001 From: Roberto Prevato Date: Wed, 22 Mar 2023 07:52:21 +0100 Subject: [PATCH] Update README.md --- README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/README.md b/README.md index e4cc9a7..37648a5 100644 --- a/README.md +++ b/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