diff --git a/docs/docs/policy-reference/_examples/graphs/reachable/config.json b/docs/docs/policy-reference/_examples/graphs/reachable/config.json index 63f0955146..7d70c89138 100644 --- a/docs/docs/policy-reference/_examples/graphs/reachable/config.json +++ b/docs/docs/policy-reference/_examples/graphs/reachable/config.json @@ -1,6 +1,7 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.graph_reachable_example.result" + "showInput": false, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.graph_reachable_example.result" } diff --git a/docs/docs/policy-reference/_examples/graphs/reachable/intro.md b/docs/docs/policy-reference/_examples/graphs/reachable/intro.md new file mode 100644 index 0000000000..5a2239925f --- /dev/null +++ b/docs/docs/policy-reference/_examples/graphs/reachable/intro.md @@ -0,0 +1,4 @@ +A common class of recursive rules can be reduced to a graph reachability +problem, so `graph.reachable` is useful for more than just graph analysis. +This usually requires some pre- and postprocessing. The following example +shows you how to "flatten" a hierarchy of access permissions. diff --git a/docs/docs/policy-reference/_examples/graphs/reachable/title.txt b/docs/docs/policy-reference/_examples/graphs/reachable/title.txt new file mode 100644 index 0000000000..e06e55928b --- /dev/null +++ b/docs/docs/policy-reference/_examples/graphs/reachable/title.txt @@ -0,0 +1 @@ +Graph Reachable diff --git a/docs/docs/policy-reference/_examples/graphs/reachable_paths/config.json b/docs/docs/policy-reference/_examples/graphs/reachable_paths/config.json index 7ddddd05b6..2721545638 100644 --- a/docs/docs/policy-reference/_examples/graphs/reachable_paths/config.json +++ b/docs/docs/policy-reference/_examples/graphs/reachable_paths/config.json @@ -1,6 +1,7 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.graph_reachable_paths_example.result" + "showInput": false, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.graph_reachable_paths_example.result" } diff --git a/docs/docs/policy-reference/_examples/graphs/reachable_paths/intro.md b/docs/docs/policy-reference/_examples/graphs/reachable_paths/intro.md new file mode 100644 index 0000000000..fe23dfbea7 --- /dev/null +++ b/docs/docs/policy-reference/_examples/graphs/reachable_paths/intro.md @@ -0,0 +1 @@ +It may be useful to find all reachable paths from a root element. `graph.reachable_paths` can be used for this. Note that cyclical paths will terminate on the repeated node. If an element references a nonexistent element, the path will be terminated, and excludes the nonexistent node. diff --git a/docs/docs/policy-reference/_examples/graphs/reachable_paths/title.txt b/docs/docs/policy-reference/_examples/graphs/reachable_paths/title.txt new file mode 100644 index 0000000000..4ae56a7661 --- /dev/null +++ b/docs/docs/policy-reference/_examples/graphs/reachable_paths/title.txt @@ -0,0 +1 @@ +Graph Reachable Paths diff --git a/docs/docs/policy-reference/_examples/net/cdir_contains1/config.json b/docs/docs/policy-reference/_examples/net/cdir_contains1/config.json deleted file mode 100644 index f1c14824f2..0000000000 --- a/docs/docs/policy-reference/_examples/net/cdir_contains1/config.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.netcidrcontainsmatches.result" -} diff --git a/docs/docs/policy-reference/_examples/net/cdir_contains2/config.json b/docs/docs/policy-reference/_examples/net/cdir_contains2/config.json deleted file mode 100644 index f1c14824f2..0000000000 --- a/docs/docs/policy-reference/_examples/net/cdir_contains2/config.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.netcidrcontainsmatches.result" -} diff --git a/docs/docs/policy-reference/_examples/net/cdir_contains3/config.json b/docs/docs/policy-reference/_examples/net/cdir_contains3/config.json deleted file mode 100644 index f1c14824f2..0000000000 --- a/docs/docs/policy-reference/_examples/net/cdir_contains3/config.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.netcidrcontainsmatches.result" -} diff --git a/docs/docs/policy-reference/_examples/net/cdir_contains4/config.json b/docs/docs/policy-reference/_examples/net/cdir_contains4/config.json deleted file mode 100644 index f1c14824f2..0000000000 --- a/docs/docs/policy-reference/_examples/net/cdir_contains4/config.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.netcidrcontainsmatches.result" -} diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/config.json b/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/config.json new file mode 100644 index 0000000000..b1426891af --- /dev/null +++ b/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/config.json @@ -0,0 +1,7 @@ +{ + "showInput": false, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.netcidrcontainsmatches.result" +} diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/intro.md b/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/intro.md new file mode 100644 index 0000000000..49d51619d7 --- /dev/null +++ b/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/intro.md @@ -0,0 +1 @@ +Either (or both) operand(s) may be an array, set, or object. diff --git a/docs/docs/policy-reference/_examples/net/cdir_contains2/policy.rego b/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/policy.rego similarity index 100% rename from docs/docs/policy-reference/_examples/net/cdir_contains2/policy.rego rename to docs/docs/policy-reference/_examples/net/cidr_contains_array_string/policy.rego diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/title.txt b/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/title.txt new file mode 100644 index 0000000000..e92e77e4ab --- /dev/null +++ b/docs/docs/policy-reference/_examples/net/cidr_contains_array_string/title.txt @@ -0,0 +1 @@ +CIDR Match with Array diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/config.json b/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/config.json new file mode 100644 index 0000000000..b1426891af --- /dev/null +++ b/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/config.json @@ -0,0 +1,7 @@ +{ + "showInput": false, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.netcidrcontainsmatches.result" +} diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/intro.md b/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/intro.md new file mode 100644 index 0000000000..3db16128a0 --- /dev/null +++ b/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/intro.md @@ -0,0 +1 @@ +The array/set/object elements may be arrays. In that case, the first element must be a valid CIDR/IP. diff --git a/docs/docs/policy-reference/_examples/net/cdir_contains3/policy.rego b/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/policy.rego similarity index 100% rename from docs/docs/policy-reference/_examples/net/cdir_contains3/policy.rego rename to docs/docs/policy-reference/_examples/net/cidr_contains_arrays/policy.rego diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/title.txt b/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/title.txt new file mode 100644 index 0000000000..6c5946302d --- /dev/null +++ b/docs/docs/policy-reference/_examples/net/cidr_contains_arrays/title.txt @@ -0,0 +1 @@ +CIDR Match with Arrays diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_objects/config.json b/docs/docs/policy-reference/_examples/net/cidr_contains_objects/config.json new file mode 100644 index 0000000000..b1426891af --- /dev/null +++ b/docs/docs/policy-reference/_examples/net/cidr_contains_objects/config.json @@ -0,0 +1,7 @@ +{ + "showInput": false, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.netcidrcontainsmatches.result" +} diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_objects/intro.md b/docs/docs/policy-reference/_examples/net/cidr_contains_objects/intro.md new file mode 100644 index 0000000000..e42ccd08be --- /dev/null +++ b/docs/docs/policy-reference/_examples/net/cidr_contains_objects/intro.md @@ -0,0 +1 @@ +If the operand is a set, the outputs are matching elements. If the operand is an object, the outputs are matching keys. diff --git a/docs/docs/policy-reference/_examples/net/cdir_contains4/policy.rego b/docs/docs/policy-reference/_examples/net/cidr_contains_objects/policy.rego similarity index 100% rename from docs/docs/policy-reference/_examples/net/cdir_contains4/policy.rego rename to docs/docs/policy-reference/_examples/net/cidr_contains_objects/policy.rego diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_objects/title.txt b/docs/docs/policy-reference/_examples/net/cidr_contains_objects/title.txt new file mode 100644 index 0000000000..ab31b003a2 --- /dev/null +++ b/docs/docs/policy-reference/_examples/net/cidr_contains_objects/title.txt @@ -0,0 +1 @@ +CIDR Match with Objects diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_strings/config.json b/docs/docs/policy-reference/_examples/net/cidr_contains_strings/config.json new file mode 100644 index 0000000000..b1426891af --- /dev/null +++ b/docs/docs/policy-reference/_examples/net/cidr_contains_strings/config.json @@ -0,0 +1,7 @@ +{ + "showInput": false, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.netcidrcontainsmatches.result" +} diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_strings/intro.md b/docs/docs/policy-reference/_examples/net/cidr_contains_strings/intro.md new file mode 100644 index 0000000000..2b5929a272 --- /dev/null +++ b/docs/docs/policy-reference/_examples/net/cidr_contains_strings/intro.md @@ -0,0 +1 @@ +If both operands are string values the function is similar to `net.cidr_contains`. diff --git a/docs/docs/policy-reference/_examples/net/cdir_contains1/policy.rego b/docs/docs/policy-reference/_examples/net/cidr_contains_strings/policy.rego similarity index 100% rename from docs/docs/policy-reference/_examples/net/cdir_contains1/policy.rego rename to docs/docs/policy-reference/_examples/net/cidr_contains_strings/policy.rego diff --git a/docs/docs/policy-reference/_examples/net/cidr_contains_strings/title.txt b/docs/docs/policy-reference/_examples/net/cidr_contains_strings/title.txt new file mode 100644 index 0000000000..de0af2b043 --- /dev/null +++ b/docs/docs/policy-reference/_examples/net/cidr_contains_strings/title.txt @@ -0,0 +1 @@ +CIDR Match with String Ranges diff --git a/docs/docs/policy-reference/_examples/rego/rule_metadata/config.json b/docs/docs/policy-reference/_examples/rego/rule_metadata/config.json index 2c13ba20be..2743717033 100644 --- a/docs/docs/policy-reference/_examples/rego/rule_metadata/config.json +++ b/docs/docs/policy-reference/_examples/rego/rule_metadata/config.json @@ -1,6 +1,7 @@ { - "showInput": true, - "showData": false, - "showTitles": false, - "command": "data.example" + "showInput": true, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.example" } diff --git a/docs/docs/policy-reference/_examples/rego/rule_metadata/intro.md b/docs/docs/policy-reference/_examples/rego/rule_metadata/intro.md new file mode 100644 index 0000000000..be1ec16c55 --- /dev/null +++ b/docs/docs/policy-reference/_examples/rego/rule_metadata/intro.md @@ -0,0 +1,4 @@ +The following policy will deny the given input because: + +- the `number` is greater than 5 +- the `subject` does not have the `admin` role diff --git a/docs/docs/policy-reference/_examples/rego/rule_metadata/title.txt b/docs/docs/policy-reference/_examples/rego/rule_metadata/title.txt new file mode 100644 index 0000000000..2afdf1c2c8 --- /dev/null +++ b/docs/docs/policy-reference/_examples/rego/rule_metadata/title.txt @@ -0,0 +1 @@ +Rule Metadata diff --git a/docs/docs/policy-reference/_examples/semver/isvalid/config.json b/docs/docs/policy-reference/_examples/semver/isvalid/config.json index a2bcd1ac23..6ac5ff999a 100644 --- a/docs/docs/policy-reference/_examples/semver/isvalid/config.json +++ b/docs/docs/policy-reference/_examples/semver/isvalid/config.json @@ -1,6 +1,7 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.semverisvalid" + "showInput": false, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.semverisvalid" } diff --git a/docs/docs/policy-reference/_examples/semver/isvalid/intro.md b/docs/docs/policy-reference/_examples/semver/isvalid/intro.md new file mode 100644 index 0000000000..11fc03d8d9 --- /dev/null +++ b/docs/docs/policy-reference/_examples/semver/isvalid/intro.md @@ -0,0 +1,8 @@ +The `result := semver.is_valid(vsn)` function checks to see if a version +string is of the form: `MAJOR.MINOR.PATCH[-PRERELEASE][+METADATA]`, where +items in square braces are optional elements. + +:::warning +When working with Go-style semantic versions, remember to remove the +leading `v` character, or the semver string will be marked as invalid! +::: diff --git a/docs/docs/policy-reference/_examples/semver/isvalid/title.txt b/docs/docs/policy-reference/_examples/semver/isvalid/title.txt new file mode 100644 index 0000000000..b8e5945232 --- /dev/null +++ b/docs/docs/policy-reference/_examples/semver/isvalid/title.txt @@ -0,0 +1 @@ +Example of semver.is_valid diff --git a/docs/docs/policy-reference/_examples/time/time_format/config.json b/docs/docs/policy-reference/_examples/time/time_format/config.json index bf9a04ea11..df34d705bf 100644 --- a/docs/docs/policy-reference/_examples/time/time_format/config.json +++ b/docs/docs/policy-reference/_examples/time/time_format/config.json @@ -1,6 +1,7 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.time_format" + "showInput": false, + "showData": false, + "showTitles": false, + "command": "data.time_format", + "titleSize": 5 } diff --git a/docs/docs/policy-reference/_examples/time/time_format/intro.md b/docs/docs/policy-reference/_examples/time/time_format/intro.md new file mode 100644 index 0000000000..48e912f54f --- /dev/null +++ b/docs/docs/policy-reference/_examples/time/time_format/intro.md @@ -0,0 +1 @@ +In OPA, we can parse a simple YYYY-MM-DD timestamp as follows: diff --git a/docs/docs/policy-reference/_examples/time/time_format/title.txt b/docs/docs/policy-reference/_examples/time/time_format/title.txt new file mode 100644 index 0000000000..0a9a1809c9 --- /dev/null +++ b/docs/docs/policy-reference/_examples/time/time_format/title.txt @@ -0,0 +1 @@ +Timestamp Parsing diff --git a/docs/docs/policy-reference/_examples/tokens/sign/empty_json/config.json b/docs/docs/policy-reference/_examples/tokens/sign/empty_json/config.json index f5572f64af..664417172f 100644 --- a/docs/docs/policy-reference/_examples/tokens/sign/empty_json/config.json +++ b/docs/docs/policy-reference/_examples/tokens/sign/empty_json/config.json @@ -1,6 +1,7 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.jwt.result" + "showInput": false, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.jwt.result" } diff --git a/docs/docs/policy-reference/_examples/tokens/sign/empty_json/title.txt b/docs/docs/policy-reference/_examples/tokens/sign/empty_json/title.txt new file mode 100644 index 0000000000..da0cc9ea8b --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/sign/empty_json/title.txt @@ -0,0 +1 @@ +Symmetric Key with empty JSON payload diff --git a/docs/docs/policy-reference/_examples/tokens/sign/hmac/config.json b/docs/docs/policy-reference/_examples/tokens/sign/hmac/config.json index f5572f64af..664417172f 100644 --- a/docs/docs/policy-reference/_examples/tokens/sign/hmac/config.json +++ b/docs/docs/policy-reference/_examples/tokens/sign/hmac/config.json @@ -1,6 +1,7 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.jwt.result" + "showInput": false, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.jwt.result" } diff --git a/docs/docs/policy-reference/_examples/tokens/sign/hmac/title.txt b/docs/docs/policy-reference/_examples/tokens/sign/hmac/title.txt new file mode 100644 index 0000000000..ed005e78d0 --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/sign/hmac/title.txt @@ -0,0 +1 @@ +Symmetric Key (HMAC with SHA-256) diff --git a/docs/docs/policy-reference/_examples/tokens/sign/rsa/config.json b/docs/docs/policy-reference/_examples/tokens/sign/rsa/config.json index f5572f64af..664417172f 100644 --- a/docs/docs/policy-reference/_examples/tokens/sign/rsa/config.json +++ b/docs/docs/policy-reference/_examples/tokens/sign/rsa/config.json @@ -1,6 +1,7 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.jwt.result" + "showInput": false, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.jwt.result" } diff --git a/docs/docs/policy-reference/_examples/tokens/sign/rsa/title.txt b/docs/docs/policy-reference/_examples/tokens/sign/rsa/title.txt new file mode 100644 index 0000000000..43d8d0a3ac --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/sign/rsa/title.txt @@ -0,0 +1 @@ +RSA Key (RSA Signature with SHA-256) diff --git a/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/config.json b/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/config.json index f5572f64af..664417172f 100644 --- a/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/config.json +++ b/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/config.json @@ -1,6 +1,7 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.jwt.result" + "showInput": false, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.jwt.result" } diff --git a/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/intro.md b/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/intro.md new file mode 100644 index 0000000000..a49f6ca577 --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/intro.md @@ -0,0 +1,3 @@ +If you need to generate the signature for a serialized token you an use the +`io.jwt.encode_sign_raw` built-in function which accepts JSON serialized string +parameters. diff --git a/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/title.txt b/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/title.txt new file mode 100644 index 0000000000..8a4f22fa21 --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/sign/sign_raw/title.txt @@ -0,0 +1 @@ +Raw Token Signing diff --git a/docs/docs/policy-reference/_examples/tokens/verify/cert/config.json b/docs/docs/policy-reference/_examples/tokens/verify/cert/config.json index 838d264eca..9bd499f9c8 100644 --- a/docs/docs/policy-reference/_examples/tokens/verify/cert/config.json +++ b/docs/docs/policy-reference/_examples/tokens/verify/cert/config.json @@ -1,7 +1,8 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "showPlayground": false, - "command": "data.jwt" + "showInput": false, + "showData": false, + "showTitles": false, + "showPlayground": false, + "titleSize": 5, + "command": "data.jwt" } diff --git a/docs/docs/policy-reference/_examples/tokens/verify/cert/intro.md b/docs/docs/policy-reference/_examples/tokens/verify/cert/intro.md new file mode 100644 index 0000000000..6848200742 --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/verify/cert/intro.md @@ -0,0 +1,3 @@ +This example shows a two-step process to verify the token signature and then decode it for +further checks of the payload content. This approach gives more flexibility in verifying only +the claims that the policy needs to enforce. diff --git a/docs/docs/policy-reference/_examples/tokens/verify/cert/title.txt b/docs/docs/policy-reference/_examples/tokens/verify/cert/title.txt new file mode 100644 index 0000000000..cee3da9d3b --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/verify/cert/title.txt @@ -0,0 +1 @@ +Certificate Verify diff --git a/docs/docs/policy-reference/_examples/tokens/verify/cert_single/config.json b/docs/docs/policy-reference/_examples/tokens/verify/cert_single/config.json index 838d264eca..9bd499f9c8 100644 --- a/docs/docs/policy-reference/_examples/tokens/verify/cert_single/config.json +++ b/docs/docs/policy-reference/_examples/tokens/verify/cert_single/config.json @@ -1,7 +1,8 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "showPlayground": false, - "command": "data.jwt" + "showInput": false, + "showData": false, + "showTitles": false, + "showPlayground": false, + "titleSize": 5, + "command": "data.jwt" } diff --git a/docs/docs/policy-reference/_examples/tokens/verify/cert_single/intro.md b/docs/docs/policy-reference/_examples/tokens/verify/cert_single/intro.md new file mode 100644 index 0000000000..cfa5969031 --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/verify/cert_single/intro.md @@ -0,0 +1,4 @@ +This next example shows doing the same token signature verification, decoding, and content checks +but instead with a single call to `io.jwt.decode_verify`. Note that this gives less flexibility +in validating the payload content as **all** claims defined in the JWT spec are verified with the +provided constraints. diff --git a/docs/docs/policy-reference/_examples/tokens/verify/cert_single/title.txt b/docs/docs/policy-reference/_examples/tokens/verify/cert_single/title.txt new file mode 100644 index 0000000000..1ac5f59852 --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/verify/cert_single/title.txt @@ -0,0 +1 @@ +Certificate Verify Single diff --git a/docs/docs/policy-reference/_examples/tokens/verify/jwks/config.json b/docs/docs/policy-reference/_examples/tokens/verify/jwks/config.json index 838d264eca..9bd499f9c8 100644 --- a/docs/docs/policy-reference/_examples/tokens/verify/jwks/config.json +++ b/docs/docs/policy-reference/_examples/tokens/verify/jwks/config.json @@ -1,7 +1,8 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "showPlayground": false, - "command": "data.jwt" + "showInput": false, + "showData": false, + "showTitles": false, + "showPlayground": false, + "titleSize": 5, + "command": "data.jwt" } diff --git a/docs/docs/policy-reference/_examples/tokens/verify/jwks/intro.md b/docs/docs/policy-reference/_examples/tokens/verify/jwks/intro.md new file mode 100644 index 0000000000..6848200742 --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/verify/jwks/intro.md @@ -0,0 +1,3 @@ +This example shows a two-step process to verify the token signature and then decode it for +further checks of the payload content. This approach gives more flexibility in verifying only +the claims that the policy needs to enforce. diff --git a/docs/docs/policy-reference/_examples/tokens/verify/jwks/title.txt b/docs/docs/policy-reference/_examples/tokens/verify/jwks/title.txt new file mode 100644 index 0000000000..ae546bb0e3 --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/verify/jwks/title.txt @@ -0,0 +1 @@ +JWKS Verify diff --git a/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/config.json b/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/config.json index 838d264eca..9bd499f9c8 100644 --- a/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/config.json +++ b/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/config.json @@ -1,7 +1,8 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "showPlayground": false, - "command": "data.jwt" + "showInput": false, + "showData": false, + "showTitles": false, + "showPlayground": false, + "titleSize": 5, + "command": "data.jwt" } diff --git a/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/intro.md b/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/intro.md new file mode 100644 index 0000000000..49b2d55f98 --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/intro.md @@ -0,0 +1,4 @@ +This next example shows doing the token signature verification, decoding, and content checks +all in one call using `io.jwt.decode_verify`. Note that this gives less flexibility in validating +the payload content as **all** claims defined in the JWT spec are verified with the provided +constraints. diff --git a/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/title.txt b/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/title.txt new file mode 100644 index 0000000000..e42777726e --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/verify/jwks_single/title.txt @@ -0,0 +1 @@ +JWKS Single Verify diff --git a/docs/docs/policy-reference/_examples/tokens/verify/sign/config.json b/docs/docs/policy-reference/_examples/tokens/verify/sign/config.json index e5aaefb3e0..5c3b946f6b 100644 --- a/docs/docs/policy-reference/_examples/tokens/verify/sign/config.json +++ b/docs/docs/policy-reference/_examples/tokens/verify/sign/config.json @@ -1,6 +1,7 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.jwt" + "showInput": false, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.jwt" } diff --git a/docs/docs/policy-reference/_examples/tokens/verify/sign/intro.md b/docs/docs/policy-reference/_examples/tokens/verify/sign/intro.md new file mode 100644 index 0000000000..4a61fa5a7c --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/verify/sign/intro.md @@ -0,0 +1 @@ +This one demonstrates how to encode the and sign the same token contents as in the example above but with `io.jwt.encode_sign` instead of the `raw` variant. diff --git a/docs/docs/policy-reference/_examples/tokens/verify/sign/title.txt b/docs/docs/policy-reference/_examples/tokens/verify/sign/title.txt new file mode 100644 index 0000000000..a6acae0639 --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/verify/sign/title.txt @@ -0,0 +1 @@ +Sign and Verify diff --git a/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/config.json b/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/config.json index e5aaefb3e0..5c3b946f6b 100644 --- a/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/config.json +++ b/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/config.json @@ -1,6 +1,7 @@ { - "showInput": false, - "showData": false, - "showTitles": false, - "command": "data.jwt" + "showInput": false, + "showData": false, + "showTitles": false, + "titleSize": 5, + "command": "data.jwt" } diff --git a/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/intro.md b/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/intro.md new file mode 100644 index 0000000000..9ec8a2d6dd --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/intro.md @@ -0,0 +1 @@ +This exambles demonstrates how to do this using the `io.jwt.encode_sign_raw` built-in: diff --git a/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/title.txt b/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/title.txt new file mode 100644 index 0000000000..a49884e020 --- /dev/null +++ b/docs/docs/policy-reference/_examples/tokens/verify/sign_raw/title.txt @@ -0,0 +1 @@ +Sign and Verify Raw diff --git a/docs/docs/policy-reference/index.md b/docs/docs/policy-reference/index.md index 94211ce173..002aba74d4 100644 --- a/docs/docs/policy-reference/index.md +++ b/docs/docs/policy-reference/index.md @@ -498,24 +498,12 @@ This differs from the plain text secrets provided with the algorithm specific ve #### Token Signing Examples -##### Symmetric Key (HMAC with SHA-256) - -##### Symmetric Key with empty JSON payload - -##### RSA Key (RSA Signature with SHA-256) - -##### Raw Token Signing - -If you need to generate the signature for a serialized token you an use the -`io.jwt.encode_sign_raw` built-in function which accepts JSON serialized string -parameters. - @@ -546,6 +534,7 @@ Exactly one of `cert` and `secret` must be present. If there are any unrecognized constraints then the token is considered invalid. #### Token Verification Examples + The examples below use the following token: ```rego @@ -556,7 +545,7 @@ es256_token := "eyJ0eXAiOiAiSldUIiwgImFsZyI6ICJFUzI1NiJ9.eyJuYmYiOiAxNDQ0NDc4NDA -##### Using JWKS +#### Using JWKS This example shows a two-step process to verify the token signature and then decode it for further checks of the payload content. This approach gives more flexibility in verifying only @@ -579,14 +568,9 @@ jwks := `{ -The next example shows doing the token signature verification, decoding, and content checks -all in one call using `io.jwt.decode_verify`. Note that this gives less flexibility in validating -the payload content as **all** claims defined in the JWT spec are verified with the provided -constraints. - -##### Using PEM encoded X.509 Certificate +#### Using PEM encoded X.509 Certificate The following examples will demonstrate verifying tokens using an X.509 Certificate defined as: @@ -608,29 +592,16 @@ OHoCIHmNX37JOqTcTzGn2u9+c8NlnvZ0uDvsd1BmKPaUmjmm -This example shows a two-step process to verify the token signature and then decode it for -further checks of the payload content. This approach gives more flexibility in verifying only -the claims that the policy needs to enforce. - -The next example shows doing the same token signature verification, decoding, and content checks -but instead with a single call to `io.jwt.decode_verify`. Note that this gives less flexibility -in validating the payload content as **all** claims defined in the JWT spec are verified with the -provided constraints. - -##### Round Trip - Sign and Verify - -This example shows how to encode a token, verify, and decode it with the different options available. +#### Round Trip - Sign and Verify -Start with using the `io.jwt.encode_sign_raw` built-in: +These examples show how to encode a token, verify, and decode it with the different options available. -Now encode the and sign the same token contents but with `io.jwt.encode_sign` instead of the `raw` variant. - :::info @@ -689,10 +660,6 @@ Examples of valid values for each timestamp field: For supported constants, formatting of nanoseconds, time zones, and other fields, see the [Go `time/format` module documentation](https://cs.opensource.google/go/go/+/master:src/time/format.go;l=9-113). -#### Timestamp Parsing Example - -In OPA, we can parse a simple `YYYY-MM-DD` timestamp as follows: - @@ -705,15 +672,8 @@ In OPA, we can parse a simple `YYYY-MM-DD` timestamp as follows: -A common class of recursive rules can be reduced to a graph reachability -problem, so `graph.reachable` is useful for more than just graph analysis. -This usually requires some pre- and postprocessing. The following example -shows you how to "flatten" a hierarchy of access permissions. - -It may be useful to find all reachable paths from a root element. `graph.reachable_paths` can be used for this. Note that cyclical paths will terminate on the repeated node. If an element references a nonexistent element, the path will be terminated, and excludes the nonexistent node. - @@ -1012,21 +972,13 @@ the match in `a` and the second tuple element refers to the match in `b`. | `set` | `set` element | | `object` | `object` key | -If both operands are string values the function is similar to `net.cidr_contains`. - - - -Either (or both) operand(s) may be an array, set, or object. - - + -The array/set/object elements may be arrays. In that case, the first element must be a valid CIDR/IP. + - + -If the operand is a set, the outputs are matching elements. If the operand is an object, the outputs are matching keys. - - + @@ -1038,17 +990,6 @@ If the operand is a set, the outputs are matching elements. If the operand is an -#### Example of `semver.is_valid` - -The `result := semver.is_valid(vsn)` function checks to see if a version -string is of the form: `MAJOR.MINOR.PATCH[-PRERELEASE][+METADATA]`, where -items in square braces are optional elements. - -:::warning -When working with Go-style semantic versions, remember to remove the -leading `v` character, or the semver string will be marked as invalid! -::: - @@ -1059,11 +1000,6 @@ leading `v` character, or the semver string will be marked as invalid! #### Example -The following policy will deny the given input because: - -- the `number` is greater than 5 -- the `subject` does not have the `admin` role - #### Metadata Merge strategies diff --git a/docs/src/components/PlaygroundExample/index.js b/docs/src/components/PlaygroundExample/index.js index 766212566d..5f0c3429b7 100644 --- a/docs/src/components/PlaygroundExample/index.js +++ b/docs/src/components/PlaygroundExample/index.js @@ -8,8 +8,21 @@ import RunSnippet from "../RunSnippet"; import SideBySideColumn from "../SideBySide/Column"; import SideBySideContainer from "../SideBySide/Container"; +function getTitle(titleSize, title) { + const ret = [ + (

{title}

), + (

{title}

), + (

{title}

), + (

{title}

), + (
{title}
), + (
{title}
), + ][Math.min(5, Math.max(0, titleSize - 1))]; + return ret; +} + export default function PlaygroundExample({ - dir, files + dir, + files, }) { let source_files = dir.keys().reduce((acc, key) => { let fileName = key.replace(`./`, ""); @@ -24,8 +37,8 @@ export default function PlaygroundExample({ return acc; }, {}); const config = source_files["config.json"]; - const input = source_files["input.json"]||"{}"; - const data = source_files["data.json"]||"{}"; + const input = source_files["input.json"] || "{}"; + const data = source_files["data.json"] || "{}"; const policy = source_files["policy.rego"]; const title = source_files["title.txt"]; @@ -39,6 +52,7 @@ export default function PlaygroundExample({ const showTitles = config?.showTitles ?? true; const showPlayground = config?.showPlayground ?? true; const command = config?.command ?? "data.play"; + const titleSize = config?.titleSize ?? 2; const state = encodeToBase64(JSON.stringify({ i: JSON.stringify(input, null, 2), @@ -53,15 +67,19 @@ export default function PlaygroundExample({ if (config && config.showData && config.dataLineLimit) { dataString = dataString.split("\n").slice(0, config.dataLineLimit).join("\n") + "\n..."; } + const introT = intro ? intro() : ""; + const outroT = outro ? outro() : ""; // id is used to stop contents from other examples on the same page being used const id = getId(state); - const snippetFiles = files?`${files} #${id}-input.json:input.json #${id}-data.json:data.json`:`#${id}-input.json:input.json #${id}-data.json:data.json`; - return ( -
- {title &&

{title}

} + const snippetFiles = files + ? `${files} #${id}-input.json:input.json #${id}-data.json:data.json` + : `#${id}-input.json:input.json #${id}-data.json:data.json`; + const header = title && getTitle(titleSize, title); - {intro && intro()} + const contents = ( +
+ {intro && introT} {showInput && ( @@ -115,7 +133,12 @@ export default function PlaygroundExample({ {policy} - + )} @@ -153,7 +176,13 @@ export default function PlaygroundExample({ )} - {outro && outro()} + {outro && outroT} +
+ ); + return ( +
+ {header} + {contents}
); }