auth: extract and clarify pointers to token validation libaries

nais · Sep 20, 2024 · 7dde219 · 7dde219
1 parent 428dd93
commit 7dde219
Show file tree

Hide file tree

Showing 9 changed files with 40 additions and 14 deletions.
diff --git a/docs/auth/entra-id/how-to/login.md b/docs/auth/entra-id/how-to/login.md
@@ -50,7 +50,7 @@ https://<ingress>/oauth2/login
 
 ### Validate token in `Authorization` header
 
-If the `Authorization` header is present, validate the token.
+If the `Authorization` header is present, validate the [JWT Bearer token](../../explanations/README.md#bearer-token) within.
 If invalid, redirect the employee to the [login endpoint]:
 
 ```

diff --git a/docs/auth/entra-id/how-to/secure.md b/docs/auth/entra-id/how-to/secure.md
@@ -25,7 +25,7 @@ Depending on who your consumers are, you must grant access to either application
 
 {% include 'auth/entra-id/partials/user-access.md' %}
 
-## Validate tokens
+---
 
 Now that you have granted access to your consumers, they can now acquire tokens that target your application, either:
 
@@ -34,6 +34,10 @@ Now that you have granted access to your consumers, they can now acquire tokens
 
 You will need to validate these tokens in your application.
 
+## Validate tokens
+
+Verify incoming requests from consumers by validating the [JWT Bearer token](../../explanations/README.md#bearer-token) in the `Authorization` header.
+
 {% include 'auth/entra-id/partials/validate.md' %}
 
 [variables-ref]: ../reference/README.md#variables-for-validating-tokens
diff --git a/docs/auth/entra-id/partials/validate.md b/docs/auth/entra-id/partials/validate.md
@@ -1,8 +1,7 @@
-!!! tip "Recommended JavaScript Library"
-
-    See <https://github.com/navikt/oasis> that helps with token validation and exchange in JavaScript applications.
+{% include 'auth/partials/validate.md' %}
 
 To validate the token, start by validating the [signature and standard time-related claims](../../explanations/README.md#token-validation).
+
 Additionally, perform the following validations:
 
 **Issuer Validation**

diff --git a/docs/auth/idporten/how-to/login.md b/docs/auth/idporten/how-to/login.md
@@ -46,18 +46,17 @@ https://<ingress>/oauth2/login
 
 ### Validate token in `Authorization` header
 
-If the `Authorization` header is present, validate the token.
+If the `Authorization` header is present, validate the [JWT Bearer token](../../explanations/README.md#bearer-token) within.
 If invalid, redirect the citizen to the [login endpoint]:
 
 ```
 https://<ingress>/oauth2/login
 ```
 
-!!! tip "Recommended JavaScript Library"
-
-    See <https://github.com/navikt/oasis> that helps with token validation and exchange in JavaScript applications.
+{% include 'auth/partials/validate.md' %}
 
 To validate the token, start by validating the [signature and standard time-related claims](../../explanations/README.md#token-validation).
+
 Additionally, perform the following validations:
 
 **Issuer Validation**

diff --git a/docs/auth/maskinporten/how-to/secure.md b/docs/auth/maskinporten/how-to/secure.md
@@ -55,9 +55,12 @@ You will now need to validate these tokens in your application.
 
 ## Validate tokens
 
-Verify incoming requests from the external consumer(s) by validating the [Bearer token](../../explanations/README.md#bearer-token) in the `Authorization` header.
+Verify incoming requests from consumers by validating the [JWT Bearer token](../../explanations/README.md#bearer-token) in the `Authorization` header.
+
+{% include 'auth/entra-id/partials/validate.md' %}
+
+To validate the token, start by validating the [signature and standard time-related claims](../../explanations/README.md#token-validation).
 
-Always validate the [signature and standard time-related claims](../../explanations/README.md#token-validation).
 Additionally, perform the following validations:
 
 **Issuer Validation**

diff --git a/docs/auth/partials/.pages b/docs/auth/partials/.pages
@@ -0,0 +1 @@
+hide: true
diff --git a/docs/auth/partials/validate.md b/docs/auth/partials/validate.md
@@ -0,0 +1,17 @@
+**JWT Validation**
+
+Validating a JWT involves a number of steps.
+These steps are outlined and described below in a language- and framework-agnostic way.
+
+!!! tip "Libraries for token validation"
+
+    We recommend using a library in your language of choice to handle all the validation steps described below.
+    Here are some recommended libraries:
+
+    - [navikt/oasis](https://github.com/navikt/oasis) (JavaScript)
+    - [navikt/token-support](https://github.com/navikt/token-support) (Java / Kotlin)
+
+    Validation is also supported by many popular frameworks:
+
+    - [Ktor](https://ktor.io/docs/server-jwt.html) (Kotlin)
+    - [Spring Security](https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/jwt.html) (Java / Kotlin)
diff --git a/docs/auth/reference/README.md b/docs/auth/reference/README.md
@@ -17,7 +17,7 @@ Below is a list of some well-known and widely used libraries for handling OAuth,
 
 - <https://github.com/navikt/token-support>
 - <https://ktor.io/docs/jwt.html>
-- <https://spring.io/projects/spring-security-oauth>
+- <https://docs.spring.io/spring-security/reference/servlet/oauth2/resource-server/>
 - <https://github.com/pac4j/pac4j>
 - <https://connect2id.com/products/nimbus-oauth-openid-connect-sdk>
 

diff --git a/docs/auth/tokenx/how-to/secure.md b/docs/auth/tokenx/how-to/secure.md
@@ -38,9 +38,12 @@ You will need to validate these tokens in your application.
 
 ## Validate tokens
 
-Verify incoming requests from consumers by validating the [Bearer token](../../explanations/README.md#bearer-token) in the `Authorization` header.
+Verify incoming requests from consumers by validating the [JWT Bearer token](../../explanations/README.md#bearer-token) in the `Authorization` header.
+
+{% include 'auth/partials/validate.md' %}
+
+To validate the token, start by validating the [signature and standard time-related claims](../../explanations/README.md#token-validation).
 
-Always validate the [signature and standard time-related claims](../../explanations/README.md#token-validation).
 Additionally, perform the following validations:
 
 **Issuer Validation**