docs: minor fixes to JWT auth docs (#17680)

* Fixes * service intentions fixes
hashicorp · Jun 12, 2023 · 2f8269a · 2f8269a
1 parent 76530fc
commit 2f8269a
Show file tree

Hide file tree

Showing 2 changed files with 196 additions and 80 deletions.
diff --git a/website/content/docs/connect/config-entries/jwt-provider.mdx b/website/content/docs/connect/config-entries/jwt-provider.mdx
@@ -101,50 +101,54 @@ When every field is defined, a JWT provider configuration entry has the followin
 Kind = "jwt-provider"                                # required
 Name = "<name-of-provider-configuration-entry>"      # required
 Issuer = "<jwt-issuer>"                              # required
-JWKS = {                                             # required
-    Local = {                                        # cannot specify with JWKS{}.Remote
-        String = "<JWKS-formatted-as-string>"        # cannot specify with JWKS{}.Remote{}.Filename
-        Filename = "<path/to/JWKS/file>"             # cannot specify with JWKS{}.Remote{}.String
-    }
+JSONWebKeySet = {                                    # required
+  Local = {                                          # cannot specify with JWKS{}.Remote
+    JWKS = "<JWKS-as-base64-string>"                 # cannot specify with JWKS{}.Local{}.Filename
+    Filename = "<path/to/JWKS/file>"                 # cannot specify with JWKS{}.Local{}.String
+  }
 }
-JWKS = {
-        Remote = {                                   # cannot specify with JWKS{}.Local
-          URI = "<uniform-resource-identifier>"
-          RequestTimeoutMs = 1500
-          CacheDuration = "5m"
-          FetchAsynchronously = false
-          RetryPolicy = {
-            NumRetries = 0
-          }
-        }
+JSONWebKeySet = {
+  Remote = {                                         # cannot specify with JWKS{}.Local
+    URI = "<uniform-resource-identifier>"
+    RequestTimeoutMs = 1500
+    CacheDuration = "5m"
+    FetchAsynchronously = false
+    RetryPolicy = {
+      NumRetries = 0
+      RetryPolicyBackoff = {
+        BaseInterval = "1s"
+        MaxInterval = "10s"
       }
+    }
+  }
+}
 Audiences = ["<aud-claims>"]
 Locations = [
-    {
-        Header = {
-            Name = "<name-of-header-with-token>"
-            ValuePrefix = "<prefix-in-header-before-token>"
-            Forward = false
-        }
-    },
-    {
-        QueryParam = {
-            Name = "<name-of-query-parameter-with-token>"
-        }
-    },
-    {
-        Cookie = {
-            Name = "<name-of-cookie-with-token>"
-        }
+  {
+    Header = {
+      Name = "<name-of-header-with-token>"
+      ValuePrefix = "<prefix-in-header-before-token>"
+      Forward = false
+    }
+  },
+  {
+    QueryParam = {
+      Name = "<name-of-query-parameter-with-token>"
     }
+  },
+  {
+    Cookie = {
+      Name = "<name-of-cookie-with-token>"
+    }
+  }
 ]
 Forwarding = {
-    HeaderName = "<name-appended-to-forwarding-header>"
-    PadForwardPayloadHeader = false
+  HeaderName = "<name-appended-to-forwarding-header>"
+  PadForwardPayloadHeader = false
 }
 ClockSkewSeconds = 30
 CacheConfig = {
-    Size = 0
+  Size = 0
 }
 ```
 
@@ -154,54 +158,58 @@ CacheConfig = {
 
 ```json
 {
-"Kind": "jwt-provider",                               // required
-"Name": "<name-of-provider-configuration-entry>",     // required
-"Issuer": "<jwt-issuer>",                             // required
-"JWKS": {                                             // required
-    "Local": {                                        // cannot specify with JWKS.Remote
-        "String": "<JWKS-formatted-as-string>",       // cannot specify with JWKS.Local.Filename
-        "Filename": "<path/to/JWKS/file>"             // cannot specify with JWKS.Local.String
+  "Kind": "jwt-provider",                               // required
+  "Name": "<name-of-provider-configuration-entry>",     // required
+  "Issuer": "<jwt-issuer>",                             // required
+  "JSONWebKeySet": {                                    // required
+    "Local": {                                          // cannot specify with JWKS.Remote
+      "JWKS": "<JWKS-as-base64-string>",                // cannot specify with JWKS.Local.Filename
+      "Filename": "<path/to/JWKS/file>"                 // cannot specify with JWKS.Local.String
     }
-},
-"JWKS": {
-        "Remote": {                                   // cannot specify with JWKS.Local
-          "URI": "<uniform-resource-identifier>",
-          "RequestTimeoutMs": "1500",
-          "CacheDuration": "5m",
-          "FetchAsynchronously": "false",
-          "RetryPolicy": {
-            "NumRetries": "0"
-          }
+  },
+  "JSONWebKeySet": {
+    "Remote": {                                         // cannot specify with JWKS.Local
+      "URI": "<uniform-resource-identifier>",
+      "RequestTimeoutMs": "1500",
+      "CacheDuration": "5m",
+      "FetchAsynchronously": "false",
+      "RetryPolicy": {
+        "NumRetries": "0",
+        "RetryPolicyBackOff": {
+          "BaseInterval": "1s",
+          "MaxInterval": "10s"
         }
-},
-"Audiences": ["<aud-claims>"],
-"Locations": [
+      }
+    }
+  },
+  "Audiences": ["<aud-claims>"],
+  "Locations": [
     {
-        "Header": {
-            "Name": "<name-of-header-with-token>",
-            "ValuePrefix": "<prefix-in-header-before-token>",
-            "Forward": "false"
-        }
+      "Header": {
+        "Name": "<name-of-header-with-token>",
+        "ValuePrefix": "<prefix-in-header-before-token>",
+        "Forward": "false"
+      }
     },
     {
-        "QueryParam": {
-            "Name":"<name-of-query-parameter-with-token>",
-        }
+      "QueryParam": {
+        "Name":"<name-of-query-parameter-with-token>",
+      }
     },
     {
-        "Cookie": {
-            "Name": "<name-of-cookie-with-token>"
-        }
+      "Cookie": {
+        "Name": "<name-of-cookie-with-token>"
+      }
     }
-],
-"Forwarding": {
-    "HeaderName": "<name-appended-to-forwarding-header>",
-    "PadForwardPayloadHeader": "false"
-},
-"ClockSkewSeconds": "30",
-"CacheConfig": {
+  ],
+  "Forwarding": {
+      "HeaderName": "<name-appended-to-forwarding-header>",
+      "PadForwardPayloadHeader": "false"
+  },
+  "ClockSkewSeconds": "30",
+  "CacheConfig": {
     "Size": "0"
-}
+  }
 }
 ```
 
@@ -217,12 +225,12 @@ metadata:                                         # required
   namespace: <namespace>
 spec:                                             # required
   issuer: <jwt-issuer>
-  jwks:
-    local:                                        # cannot specify with spec.jwks.remote
-     string: <jwks-formatted-as-string>           # cannot specify with spec.jwks.local.filename
-     filename: <path/to/jwks/file>                # cannot specify with spec.jwks.local.string
-  jwks:
-    remote:                                       # cannot specify with spec.jwks.local
+  jsonWebKeySet:
+    local:                                        # cannot specify with spec.jsonWebKeySet.remote
+     jwks: <jwks-as-base64-string>                # cannot specify with spec.jsonWebKeySet.local.filename
+     filename: <path/to/jwks/file>                # cannot specify with spec.jsonWebKeySet.local.string
+  jsonWebKeySet:
+    remote:                                       # cannot specify with spec.jsonWebKeySet.local
       uri: <uniform-resource-identifier>
       requestTimeoutMs: 1500
       cacheDuration: 5m
@@ -953,7 +961,7 @@ metadata:
   name: okta
 spec:
   issuer: okta
-  jwks:
+  jsonWebKeySet:
     remote:
       uri: https://dev-850216.okta.com/oauth2/default/v1/keys
       cacheDuration: 30m

diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx
@@ -1313,3 +1313,111 @@ When using cluster peering connections, intentions secure your deployments with
   ```
 
   </CodeTabs>
+
+### JWT validation with intentions
+
+The following example configures a service intention that evaluates requests when a service named `backend` receives a request from the `frontend` service. When the request is sent to the `/admin` HTTP path, a JSON Web Token provided by Okta is evaluated. In addition to the validation requirements in a separate JWT provider configuration entry, an additional check occurs to confirm that the token has either a `perms` or `role` claim with the `admin` value. If it does, the request is authorized.
+
+Because the intention allows requests that come from the `/` HTTP path, only requests on the `/admin` path are subject to token validation.
+
+<CodeTabs tabs={[ "HCL", "Kubernetes YAML", "JSON" ]}>
+
+```hcl
+Kind = "service-intentions"
+Name = "backend"
+Sources = [
+  {
+    Name = "frontend"
+    Permissions = [
+      {
+        HTTP = {
+          PathExact = "/admin"
+        }
+        JWT = {
+          Providers = [
+            {
+              Name = "okta"
+              VerifyClaims = [
+                {
+                  Path = ["perms", "role"]
+                  Value = "admin"
+                }
+              ]
+            }
+          ]
+        }
+      },
+      {
+        Action = "allow"
+        HTTP = {
+          PathPrefix = "/"
+        }
+      }
+    ]
+  }
+]
+```
+
+```yaml
+apiVersion: consul.hashicorp.com/v1alpha1
+kind: ServiceIntentions
+metadata:
+  name: backend
+spec:
+  sources:
+    name: frontend
+    permissions:
+      http:
+        pathExact: /admin
+      jwt:
+        providers:
+          name: okta
+          verifyClaims:
+            path: 
+              - perms
+              - role
+            value: admin
+    action: allow
+    http:
+      pathPrefix: /
+```
+
+```json
+{
+  "Kind": "service-intentions",
+  "Name": "backend",
+  "Sources": [
+    {
+      "Name": "frontend",
+      "Permissions": [
+        {
+          "HTTP": {
+            "PathExact": "/admin"
+          },
+          "JWT": {
+            "Providers": [
+              {
+                "Name": "okta",
+                "VerifyClaims": [
+                  {
+                    "Path": ["perms", "role"],
+                    "Value": "admin"
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "Action": "allow",
+          "HTTP": {
+            "PathPrefix": "/"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+</CodeTabs>