First Draft for JWT Best Practices Doc #1182

chalbersma · 2023-08-11T21:25:16Z

Ignores .idea files (pycharm ide)
Index updated by make generate-site
Added assets/JWTCSA as a place for assets and snippets
Added a JWT Cheat Sheet Doc
Fixed google_analytics in mkdocs.yaml
Added pymdownx plugins for:
- Admonitions (blocks.details)
- Code Snippets (snippets)
- Tabbed Content (tabbed)
Pinned modern minimum versions on requirements.txt

This PR covers issue #1176 .

Please do not merge yet. This is a work in progress at best.

* Ignores .idea files (pycharm ide) * Index updated by make generate-site * Added assets/JWTCSA as a place for assets and snippets * Added a JWT Cheat Sheet Doc * Fixed google_analytics in mkdocs.yaml * Added pymdownx plugins for: * Admonitions (`blocks.details`) * Code Snippets (`snippets`) * Tabbed Content (`tabbed`) * Pinned modern minimum versions on requirements.txt

chalbersma · 2023-08-11T21:26:08Z

How the multi language stuff ends up looking.

szh · 2023-08-30T13:46:17Z

Please do not merge yet. This is a work in progress at best

I marked this PR as a draft so nobody does by mistake.

jmanico · 2023-09-07T16:19:43Z

I am super eager to see this fleshed out, can I help? Wanna meet and discuss?

chalbersma · 2023-09-08T05:55:46Z

Honestly we probably should, but I'm super busy this week. I might have some time next.

* Still not ready * Taking some feedback from our attempt to implement a jwt based auth scheme professionally. * Recommends jwt symmetrically signed with jwks certificates as it seems like it will be the best supported and offers an upgrade/portability path to OIDC.

chalbersma · 2023-10-28T07:05:22Z

Slow going but was able to get a little more work on this. Have a JWKS + JWT example in python in there atm.

EbonyAdder · 2023-11-25T15:25:57Z

Hello, @chalbersma , just wanted to check where things stand on this or if you would like any assistance? I am familiar with JWT security and multiple programming languages, so I would be happy to assist if it wanted.

chalbersma · 2023-11-29T16:41:23Z

Hello @EbonyAdder

At the company I work for we were looking to adopt a JWT auth-based standard. I was going to use the lessons learned and example code from that to populate this best practices document. Unfortunately in the process of building, I think we're learning an unfortunate less for "naked" jwts authentication/authorization; that it might be best to use a "fuller" service mesh style system (think envoy) to manage these tokens and connections.

This is still on my to-do list; I've just lost confidence that the approach recommended is still what should be recommended at this time.

jmanico · 2024-04-13T20:14:19Z

Can we revisit this? Here are some of the ASVS requirements for ASVS 5.0.

V9.1 Token source and integrity

This section includes requirements that ensure that the token has been produced by a trusted party and that it has not been tampered with.

#	Description	Level	#v5.0.be
9.1.1	Verify that self-contained tokens are validated using their digital signature or MAC to protect against tampering before accepting the token's contents.	1	v5.0.be-52.1.1
9.1.2	Verify that only algorithms on an allowlist can be used to create and verify self-contained tokens, for a given context. The allowlist must include the permitted algorithms, ideally only either symmetric or asymmetric algorithms, and must not include the 'None' algorithm. If both symmetric and asymmetric must be supported, additional controls will be needed to prevent key confusion.	1	v5.0.be-52.1.2
9.1.3	Verify that key material that is used to validate self-contained tokens is from trusted pre-configured sources for the token issuer, preventing attackers from specifying untrusted sources and keys. For JWTs and other JWS structures, headers such as 'jku', 'x5u', and 'jwk' must be validated against an allowlist of trusted sources.	1	v5.0.be-52.1.3

V9.2 Token content

Before making security decisions based on the content of a self-contained token, it is necessary to validate that the token has been presented within its validity period and that it is meant for use by the receiving service and for the purpose for which it was presented. This is to avoid insecure cross-usage between different services or with different token types from the same issuer.

Specific requirements for OAuth and OIDC are covered in the dedicated chapter.

#	Description	Level	#v5.0.be
9.2.1	Verify that, if a validity time span is present in the token data, the token and its content are accepted only if the verification time is within this validity time span. For example, for JWTs, the claims 'nbf' and 'exp' must be verified.	1	v5.0.be-52.2.1
9.2.2	Verify that the service receiving a token validates the token to be the correct type and is meant for the intended purpose before accepting the token's contents. For example, only access tokens can be accepted for authorization decisions and only ID Tokens can be used for proving user authentication.	2	v5.0.be-52.2.2
9.2.3	Verify that the service only accepts tokens which are intended for use with that service (audience). For JWTs, this can be achieved by validating the 'aud' claim against an allowlist defined in the service.	2	v5.0.be-52.2.3
9.2.4	Verify that, if a token issuer uses the same private key for issuing tokens to different audiences, the issued tokens contain an audience restriction that uniquely identifies the intended audiences. This will prevent a token from being reused with an unintended audience. If the audience identifier is dynamically provisioned, the token issuer must validate these audiences in order to make sure that they do not result in audience impersonation.	2	v5.0.be-52.2.4

randomstuff · 2024-05-21T08:53:47Z

cheatsheets/JWT_Cheat_Sheet.md

+
+## Issues
+
+### None Hashing Algorithm


None is not an "hashing" algorithm. It is an (not really) "authentication algorithm".

randomstuff · 2024-10-08T20:06:51Z

assets/JWTCSA/0-verification.md

+<!-- --8<-- [start:pyjwt] -->
+```
+try:
+    pyjwt.decode(encoded, key, algorithms=["HS256","ES256"])


This is weird to support HS256 (a MAC) and ES256 (a signature) at the same time. Either your key is a shared secret and you will support HS256 or this is a public key and you support ES256. I think ES256 is spurious here. This would be consistent with other examples.

randomstuff · 2024-10-08T20:10:20Z

assets/JWTCSA/1-jwks.md

+import uuid
+from jwcrypto import jwk, jwt
+
+unique_kid = uuid.uuid4()


I'm always wondering why everyone keeps insisting on using UUID for this kind of things when you can just use a random token :) What about unique_kid = secrets.token_urlsafe(20)? It is shorter than a uuid.uuid4() but still has more entropy.

randomstuff · 2024-10-08T20:16:05Z

assets/JWTCSA/1-jwks.md

+
+# Publish to Datastore in Multinode system
+
+this_token = jwt.JWT(header={"alg": "RS256"},


This is a JWT but at the same time there is not expiration. There should probably at least be some expiration in the "default example"?

randomstuff · 2024-10-08T20:23:11Z

cheatsheets/JWT_Cheat_Sheet.md

+
+## Introduction
+
+Many applications use **JSON Web Tokens** (JWT) to allow the client to indicate its identity for further exchange after


"to allow the client", I guess you mean the user. JWT can definitely be used to represent claims about the client, I think you are actually thinking more about the user.

randomstuff · 2024-10-08T20:30:12Z

cheatsheets/JWT_Cheat_Sheet.md

+#### Symptom
+
+This attack occurs when a token has been intercepted/stolen by an attacker and they use it to gain access to the system
+ using targeted user identity. In part, this attack really can't be mitigated "in platform" as JWTs are generically stateless


It could be mitigated using some proof-of-possession such as:

sender-constrained JWT such as TLS-bound access tokens and DPoP access tokens;

SD-JWT bound to a public key pair

cheatsheets/JWT_Cheat_Sheet.md

jmanico · 2025-02-20T13:56:22Z

Any thoughts on this, @chalbersma ?

Also, there are new ASVS requirements on JWTs to consider.

https://github.com/OWASP/ASVS/blob/master/5.0/en/0x18-V9-Tokens.md

jmanico · 2025-04-11T22:57:28Z

There is a lot going on here. Hey @randomstuff do you have desire to take this on and drive it home? I trust your talent from ASVS to finish this - even if its not complete, just a cheat will do - so long as its accurate.

jmanico · 2025-04-12T16:42:42Z

Here is the latest ASVS Content on tokens:

V9.1 Token source and integrity

This section includes requirements that ensure that the token has been produced by a trusted party and that it has not been tampered with.

#	Description	Level	#v5.0.be
9.1.1	Verify that self-contained tokens are validated using their digital signature or MAC to protect against tampering before accepting the token's contents.	1	v5.0.be-52.1.1
9.1.2	Verify that only algorithms on an allowlist can be used to create and verify self-contained tokens, for a given context. The allowlist must include the permitted algorithms, ideally only either symmetric or asymmetric algorithms, and must not include the 'None' algorithm. If both symmetric and asymmetric must be supported, additional controls will be needed to prevent key confusion.	1	v5.0.be-52.1.2
9.1.3	Verify that key material that is used to validate self-contained tokens is from trusted pre-configured sources for the token issuer, preventing attackers from specifying untrusted sources and keys. For JWTs and other JWS structures, headers such as 'jku', 'x5u', and 'jwk' must be validated against an allowlist of trusted sources.	1	v5.0.be-52.1.3

V9.2 Token content

Before making security decisions based on the content of a self-contained token, it is necessary to validate that the token has been presented within its validity period and that it is meant for use by the receiving service and for the purpose for which it was presented. This is to avoid insecure cross-usage between different services or with different token types from the same issuer.

Specific requirements for OAuth and OIDC are covered in the dedicated chapter.

#	Description	Level	#v5.0.be
9.2.1	Verify that, if a validity time span is present in the token data, the token and its content are accepted only if the verification time is within this validity time span. For example, for JWTs, the claims 'nbf' and 'exp' must be verified.	1	v5.0.be-52.2.1
9.2.2	Verify that the service receiving a token validates the token to be the correct type and is meant for the intended purpose before accepting the token's contents. For example, only access tokens can be accepted for authorization decisions and only ID Tokens can be used for proving user authentication.	2	v5.0.be-52.2.2
9.2.3	Verify that the service only accepts tokens which are intended for use with that service (audience). For JWTs, this can be achieved by validating the 'aud' claim against an allowlist defined in the service.	2	v5.0.be-52.2.3
9.2.4	Verify that, if a token issuer uses the same private key for issuing tokens to different audiences, the issued tokens contain an audience restriction that uniquely identifies the intended audiences. This will prevent a token from being reused with an unintended audience. If the audience identifier is dynamically provisioned, the token issuer must validate these audiences in order to make sure that they do not result in audience impersonation.	2	v5.0.be-52.2.4

randomstuff · 2025-04-23T21:41:02Z

cheatsheets/JWT_Cheat_Sheet.md

+### Verification
+
+Your application, absolutely should verify that the tokens it recieves are valid. You can do this with a symmetric scheme, where
+a secret between all parties out of band. For more on how to manage secrets please refer to the [secrets management cheat sheet](Secrets_Management_Cheat_Sheet.md). Or you can use an asymmetric key to signe your tokens.  you have the option of signing your


a [shared] secret between all parties out of band

It is dangerous to share a secret between more than two parties. I would say "between two parties".

chalbersma requested review from mackowski, jmanico and szh as code owners August 11, 2023 21:25

Fixes markdown linting errors.

c2e3e28

szh marked this pull request as draft August 30, 2023 13:45

chalbersma and others added 2 commits October 27, 2023 22:01

Merge branch 'master' into jwt_things

6aa2eea

More work on this

4dcaedf

* Still not ready * Taking some feedback from our attempt to implement a jwt based auth scheme professionally. * Recommends jwt symmetrically signed with jwks certificates as it seems like it will be the best supported and offers an upgrade/portability path to OIDC.

Updating Cheat Sheet

cc26767

randomstuff reviewed May 21, 2024

View reviewed changes

randomstuff reviewed Oct 8, 2024

View reviewed changes

cheatsheets/JWT_Cheat_Sheet.md Show resolved Hide resolved

randomstuff reviewed Apr 23, 2025

View reviewed changes


		# Publish to Datastore in Multinode system

		this_token = jwt.JWT(header={"alg": "RS256"},


		## Introduction

		Many applications use JSON Web Tokens (JWT) to allow the client to indicate its identity for further exchange after

First Draft for JWT Best Practices Doc #1182

Are you sure you want to change the base?

First Draft for JWT Best Practices Doc #1182

Uh oh!

Conversation

chalbersma commented Aug 11, 2023

Uh oh!

chalbersma commented Aug 11, 2023

Uh oh!

szh commented Aug 30, 2023

Uh oh!

jmanico commented Sep 7, 2023

Uh oh!

chalbersma commented Sep 8, 2023

Uh oh!

chalbersma commented Oct 28, 2023

Uh oh!

EbonyAdder commented Nov 25, 2023

Uh oh!

chalbersma commented Nov 29, 2023

Uh oh!

jmanico commented Apr 13, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

V9.1 Token source and integrity

V9.2 Token content

Uh oh!

randomstuff May 21, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

randomstuff Oct 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

randomstuff Oct 8, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

randomstuff Oct 8, 2024

Choose a reason for hiding this comment

Uh oh!

randomstuff Oct 8, 2024

Choose a reason for hiding this comment

Uh oh!

randomstuff Oct 8, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jmanico commented Feb 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jmanico commented Apr 11, 2025

Uh oh!

jmanico commented Apr 12, 2025

V9.1 Token source and integrity

V9.2 Token content

Uh oh!

randomstuff Apr 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jmanico commented Apr 13, 2024 •

edited

Loading

randomstuff May 21, 2024 •

edited

Loading

randomstuff Oct 8, 2024 •

edited

Loading

randomstuff Oct 8, 2024 •

edited

Loading

jmanico commented Feb 20, 2025 •

edited

Loading