From b94a87708a6b255a0d96a559bba4ae132e377ac0 Mon Sep 17 00:00:00 2001 From: max furman Date: Tue, 13 Nov 2018 22:05:06 -0800 Subject: [PATCH] add JWT documentation --- docs/recommendations.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/recommendations.md b/docs/recommendations.md index 248bab7b..9921c39c 100644 --- a/docs/recommendations.md +++ b/docs/recommendations.md @@ -14,6 +14,20 @@ best practices in the industry, and to have these practices codified as defaults in the `certificates` code base. If you have questions, suggestions, or comments about any of these decisions please let us know. +### Tokens + +We use JWTs (JSON Web Tokens to prove authenticity and identity within the Step +ecosystem. JWTs have received negative attention because they are easy to +misuse, misconfigure. +We agree! But lots of things are easy to misuse. We also believe +that when configured well JWTs are a great way to sign and encode data. Our JWT's +are, by default, short-lived (5 minute lifespan) and can only be used once during +the lifetime of the Step CA. We use a 1 minute clock drift leeway because that +was the recommended default in the reputable JWT package that we chose. If using +Step JWTs or your own JWTs in your code be sure to verify and validate every +single standard attributed of the JWT. JWTs, like all cryptographic tools, +are useless without proper attention to configuration and guidelines. + ### Keys ```