Policy Reference Edit

This document is the authoritative specification of the Rego policy language (V1). All policies in OPA are written in Rego.

Built-in Functions

The built-in functions for the language provide basic operations to manipulate scalar values (e.g. numbers and strings), and aggregate functions that summarize complex types.

Comparison

Built-inDescription
x == yx is equal to y
x != yx is not equal to y
x < yx is less than y
x <= yx is less than or equal to y
x > yx is greater than y
x >= yx is greater than or equal to y

Numbers

Built-inDescription
z := x + yz is the sum of x and y
z := x - yz is the difference of x and y
z := x * yz is the product of x and y
z := x / yz is the quotient of x and y
z := x % yz is the remainder from the division of x and y
output := round(x)output is x rounded to the nearest integer
output := abs(x)output is the absolute value of x

Aggregates

Built-inDescription
output := count(collection_or_string)output is the length of the object, array, set, or string provided as input
output := sum(array_or_set)output is the sum of the numbers in array_or_set
output := product(array_or_set)output is the product of the numbers in array_or_set
output := max(array_or_set)output is the maximum value in array_or_set
output := min(array_or_set)output is the minimum value in array_or_set
output := sort(array_or_set)output is the sorted array containing elements from array_or_set.
output := all(array_or_set)output is true if all of the values in array_or_set are true. A collection of length 0 returns true.
output := any(array_or_set)output is true if any of the values in array_or_set is true. A collection of length 0 returns false.

Arrays

Built-inDescription
output := array.concat(array, array)output is the result of concatenating the two input arrays together.
output := array.slice(array, startIndex, stopIndex)output is the part of the array from startIndex to stopIndex including the first but excluding the last. If startIndex >= stopIndex then output == []. If both startIndex and stopIndex are less than zero, output == []. Otherwise, startIndex and stopIndex are clamped to 0 and count(array) respectively.

Sets

Built-inDescription
s3 := s1 & s2s3 is the intersection of s1 and s2.
s3 := s1 | s2s3 is the union of s1 and s2.
s3 := s1 - s2s3 is the difference between s1 and s2, i.e., the elements in s1 that are not in s2
output := intersection(set[set])output is the intersection of the sets in the input set
output := union(set[set])output is the union of the sets in the input set

Objects

Built-inDescription
value := object.get(object, key, default)value is the value stored by the object at key. If no value is found, default is returned.
output := object.remove(object, keys)output is a new object which is the result of removing the specified keys from object. keys must be either an array, object, or set of keys.
output := object.union(objectA, objectB)output is a new object which is the result of an asymmetric recursive union of two objects where conflicts are resolved by choosing the key from the right-hand object (objectB). For example: object.union({"a": 1, "b": 2, "c": {"d": 3}}, {"a": 7, "c": {"d": 4, "e": 5}}) will result in {"a": 7, "b": 2, "c": {"d": 4, "e": 5}}
filtered := object.filter(object, keys)filtered is a new object with the remaining data from object with only keys specified in keys which is an array, object, or set of keys. For example: object.filter({"a": {"b": "x", "c": "y"}, "d": "z"}, ["a"]) will result in {"a": {"b": "x", "c": "y"}}).
filtered := json.filter(object, paths)filtered is the remaining data from object with only keys specified in paths which is an array or set of JSON string paths. For example: json.filter({"a": {"b": "x", "c": "y"}}, ["a/b"]) will result in {"a": {"b": "x"}}).

The json string paths may reference into array values by using index numbers. For example with the object {"a": ["x", "y", "z"]} the path a[1] references y

When keys are provided as an object only the top level keys on the object will be used, values are ignored. For example: object.remove({"a": {"b": {"c": 2}}, "x": 123}, {"a": 1}) == {"x": 123} regardless of the value for key a in the keys object, the following keys object gives the same result object.remove({"a": {"b": {"c": 2}}, "x": 123}, {"a": {"b": {"foo": "bar"}}}) == {"x": 123}

Strings

Built-inDescription
output := concat(delimiter, array_or_set)output is the result of joining together the elements of array_or_set with the string delimiter
contains(string, search)true if string contains search
endswith(string, search)true if string ends with search
output := format_int(number, base)output is string representation of number in the given base
output := indexof(string, search)output is the index inside string where search first occurs, or -1 if search does not exist
output := lower(string)output is string after converting to lower case
output := replace(string, old, new)output is a string representing string with all instances of old replaced by new
output := strings.replace_n(patterns, string)patterns is an object with old, new string key value pairs (e.g. {"old1": "new1", "old2": "new2", ...}). output is a string with all old strings inside patterns replaced by the new strings
output := split(string, delimiter)output is array[string] representing elements of string separated by delimiter
output := sprintf(string, values)output is a string representing string formatted by the values in the array values.
startswith(string, search)true if string begins with search
output := substring(string, start, length)output is the portion of string from index start and having a length of length. If length is less than zero, length is the remainder of the string. If start is greater than the length of the string, output is empty. It is invalid to pass a negative offset to this function.
output := trim(string, cutset)output is a string representing string with all leading and trailing instances of the characters in cutset removed.
output := trim_left(string, cutset)output is a string representing string with all leading instances of the characters in cutset removed.
output := trim_prefix(string, prefix)output is a string representing string with leading instance of prefix removed. If string doesn’t start with prefix, string is returned unchanged.
output := trim_right(string, cutset)output is a string representing string with all trailing instances of the characters in cutset removed.
output := trim_suffix(string, suffix)output is a string representing string with trailing instance of suffix removed. If string doesn’t end with suffix, string is returned unchanged.
output := trim_space(string)output is a string representing string with all leading and trailing white space removed.
output := upper(string)output is string after converting to upper case

Regex

Built-inDescription
re_match(pattern, value)true if the value matches the regex pattern
output := regex.split(pattern, string)output is array[string] representing elements of string separated by pattern
regex.globs_match(glob1, glob2)true if the intersection of regex-style globs glob1 and glob2 matches a non-empty set of non-empty strings. The set of regex symbols is limited for this builtin: only ., *, +, [, -, ] and \ are treated as special symbols.
output := regex.template_match(patter, string, delimiter_start, delimiter_end)output is true if string matches pattern. pattern is a string containing 0..n regular expressions delimited by delimiter_start and delimiter_end. Example regex.template_match("urn:foo:{.*}", "urn:foo:bar:baz", "{", "}", x) returns true for x.
output := regex.find_n(pattern, string, number)output is an array[string] with the number of values matching the pattern. A number of -1 means all matches.
output := regex.find_all_string_submatch_n(pattern, string, number)output is an array[array[string]] with the outer array including a number of matches which match the pattern. A number of -1 means all matches.

Glob

Built-inDescription
output := glob.match(pattern, delimiters, match)output is true if match can be found in pattern which is separated by delimiters. For valid patterns, check the table below. Argument delimiters is an array of single-characters (e.g. [".", ":"]). If delimiters is empty, it defaults to ["."].
output := glob.quote_meta(pattern)output is the escaped string of pattern. Calling glob.quote_meta("*.github.com", output) returns \\*.github.com as output.

The following table shows examples of how glob.match works:

calloutputDescription
output := glob.match("*.github.com", [], "api.github.com")trueA glob with the default ["."] delimiter.
output := glob.match("*.github.com", [], "api.cdn.github.com")falseA glob with the default ["."] delimiter.
output := glob.match("*:github:com", [":"], "api:github:com")trueA glob with delimiters [":"].
output := glob.match("api.**.com", [], "api.github.com")trueA super glob.
output := glob.match("api.**.com", [], "api.cdn.github.com")trueA super glob.
output := glob.match("?at", [], "cat")trueA glob with a single character wildcard.
output := glob.match("?at", [], "at")falseA glob with a single character wildcard.
output := glob.match("[abc]at", [], "bat")trueA glob with character-list matchers.
output := glob.match("[abc]at", [], "cat")trueA glob with character-list matchers.
output := glob.match("[abc]at", [], "lat")falseA glob with character-list matchers.
output := glob.match("[!abc]at", [], "cat")falseA glob with negated character-list matchers.
output := glob.match("[!abc]at", [], "lat")trueA glob with negated character-list matchers.
output := glob.match("[a-c]at", [], "cat")trueA glob with character-range matchers.
output := glob.match("[a-c]at", [], "lat")falseA glob with character-range matchers.
output := glob.match("[!a-c]at", [], "cat")falseA glob with negated character-range matchers.
output := glob.match("[!a-c]at", [], "lat")trueA glob with negated character-range matchers.
output := glob.match("{cat,bat,[fr]at}", [], "cat")trueA glob with pattern-alternatives matchers.
output := glob.match("{cat,bat,[fr]at}", [], "bat")trueA glob with pattern-alternatives matchers.
output := glob.match("{cat,bat,[fr]at}", [], "rat")trueA glob with pattern-alternatives matchers.
output := glob.match("{cat,bat,[fr]at}", [], "at")falseA glob with pattern-alternatives matchers.

Conversions

Built-inDescription
output := to_number(x)output is x converted to a number. null is converted to zero, true and false are converted to one and zero (respectively), string values are interpreted as base 10, and numbers are a no-op. Other types are not supported.

Units

Built-inDescription
output := units.parse_bytes(x)output is x converted to a number with support for standard byte units (e.g., KB, KiB, etc.) KB, MB, GB, and TB are treated as decimal units and KiB, MiB, GiB, and TiB are treated as binary units.

Types

Built-inDescription
output := is_number(x)output is true if x is a number; otherwise undefined
output := is_string(x)output is true if x is a string; otherwise undefined
output := is_boolean(x)output is true if x is a boolean; otherwise undefined
output := is_array(x)output is true if x is an array; otherwise undefined
output := is_set(x)output is true if x is a set; otherwise undefined
output := is_object(x)output is true if x is an object; otherwise undefined
output := is_null(x)output is true if x is null; otherwise undefined
output := type_name(x)output is the type of x

Encoding

Built-inDescription
output := base64.encode(x)output is x serialized to a base64 encoded string
output := base64.decode(string)output is x deserialized from a base64 encoding string
output := base64url.encode(x)output is x serialized to a base64url encoded string
output := base64url.decode(string)output is string deserialized from a base64url encoding string
output := urlquery.encode(string)output is string serialized to a URL query parameter encoded string
output := urlquery.encode_object(object)output is object serialized to a URL query parameter encoded string
output := urlquery.decode(string)output is string deserialized from a URL query parameter encoded string
output := json.marshal(x)output is x serialized to a JSON string
output := json.unmarshal(string)output is string deserialized to a term from a JSON encoded string
output := yaml.marshal(x)output is x serialized to a YAML string
output := yaml.unmarshal(string)output is string deserialized to a term from YAML encoded string

Token Signing

OPA provides two builtins that implement JSON Web Signature RFC7515 functionality.

io.jwt.encode_sign_raw() takes three JSON Objects (strings) as parameters and returns their JWS Compact Serialization. This builtin should be used by those that want maximum control over the signing and serialization procedure. It is important to remember that StringOrURI values are compared as case-sensitive strings with no transformations or canonicalizations applied. Therefore, line breaks and whitespaces are significant.

io.jwt.encode_sign() takes three Rego Objects as parameters and returns their JWS Compact Serialization. This builtin should be used by those that want to use rego objects for signing during policy evaluation.

Note that with io.jwt.encode_sign the Rego objects are serialized to JSON with standard formatting applied whereas the io.jwt.encode_sign_raw built-in will not affect whitespace of the strings passed in. This will mean that the final encoded token may have different string values, but the decoded and parsed JSON will match.

The following algorithms are supported:

ES256       "ES256" // ECDSA using P-256 and SHA-256
ES384       "ES384" // ECDSA using P-384 and SHA-384
ES512       "ES512" // ECDSA using P-521 and SHA-512
HS256       "HS256" // HMAC using SHA-256
HS384       "HS384" // HMAC using SHA-384
HS512       "HS512" // HMAC using SHA-512
NoSignature "none"
PS256       "PS256" // RSASSA-PSS using SHA256 and MGF1-SHA256
PS384       "PS384" // RSASSA-PSS using SHA384 and MGF1-SHA384
PS512       "PS512" // RSASSA-PSS using SHA512 and MGF1-SHA512
RS256       "RS256" // RSASSA-PKCS-v1.5 using SHA-256
RS384       "RS384" // RSASSA-PKCS-v1.5 using SHA-384
RS512       "RS512" // RSASSA-PKCS-v1.5 using SHA-512

Built-inDescription
output := io.jwt.encode_sign_raw(headers, payload, key)headers, payload and key as strings that represent the JWS Protected Header, JWS Payload and JSON Web Key (RFC7517) respectively.
output := io.jwt.encode_sign(headers, payload, key)headers, payload and key are JSON objects that represent the JWS Protected Header, JWS Payload and JSON Web Key (RFC7517) respectively.

Note that the key’s provided should be base64 encoded as per the specification (RFC7517). This differs from the plain text secrets provided with the algorithm specific verify built-ins described below.

Token Signing Examples

Symmetric Key (HMAC with SHA-256)
io.jwt.encode_sign({
    "typ": "JWT",
    "alg": "HS256"
}, {
    "iss": "joe",
    "exp": 1300819380,
    "aud": ["bob", "saul"],
    "http://example.com/is_root": true,
    "privateParams": {
        "private_one": "one",
        "private_two": "two"
    }
}, {
    "kty": "oct",
    "k": "AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"
})
"eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJhdWQiOiBbImJvYiIsICJzYXVsIl0sICJleHAiOiAxMzAwODE5MzgwLCAiaHR0cDovL2V4YW1wbGUuY29tL2lzX3Jvb3QiOiB0cnVlLCAiaXNzIjogImpvZSIsICJwcml2YXRlUGFyYW1zIjogeyJwcml2YXRlX29uZSI6ICJvbmUiLCAicHJpdmF0ZV90d28iOiAidHdvIn19.M10TcaFADr_JYAx7qJ71wktdyuN4IAnhWvVbgrZ5j_4"
Symmetric Key with empty JSON payload
io.jwt.encode_sign({
    "typ": "JWT",
    "alg": "HS256"},
    {}, {
    "kty": "oct",
    "k": "AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"
})
"eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.e30.Odp4A0Fj6NoKsV4Gyoy1NAmSs6KVZiC15S9VRGZyR20"
RSA Key (RSA Signature with SHA-256)
io.jwt.encode_sign({
    "alg": "RS256"
}, {
    "iss": "joe",
    "exp": 1300819380,
    "aud": ["bob", "saul"],
    "http://example.com/is_root": true,
    "privateParams": {
        "private_one": "one",
        "private_two": "two"
    }
},
{
    "kty": "RSA",
    "n": "ofgWCuLjybRlzo0tZWJjNiuSfb4p4fAkd_wWJcyQoTbji9k0l8W26mPddxHmfHQp-Vaw-4qPCJrcS2mJPMEzP1Pt0Bm4d4QlL-yRT-SFd2lZS-pCgNMsD1W_YpRPEwOWvG6b32690r2jZ47soMZo9wGzjb_7OMg0LOL-bSf63kpaSHSXndS5z5rexMdbBYUsLA9e-KXBdQOS-UTo7WTBEMa2R2CapHg665xsmtdVMTBQY4uDZlxvb3qCo5ZwKh9kG4LT6_I5IhlJH7aGhyxXFvUK-DWNmoudF8NAco9_h9iaGNj8q2ethFkMLs91kzk2PAcDTW9gb54h4FRWyuXpoQ",
    "e": "AQAB",
    "d": "Eq5xpGnNCivDflJsRQBXHx1hdR1k6Ulwe2JZD50LpXyWPEAeP88vLNO97IjlA7_GQ5sLKMgvfTeXZx9SE-7YwVol2NXOoAJe46sui395IW_GO-pWJ1O0BkTGoVEn2bKVRUCgu-GjBVaYLU6f3l9kJfFNS3E0QbVdxzubSu3Mkqzjkn439X0M_V51gfpRLI9JYanrC4D4qAdGcopV_0ZHHzQlBjudU2QvXt4ehNYTCBr6XCLQUShb1juUO1ZdiYoFaFQT5Tw8bGUl_x_jTj3ccPDVZFD9pIuhLhBOneufuBiB4cS98l2SR_RQyGWSeWjnczT0QU91p1DhOVRuOopznQ",
    "p": "4BzEEOtIpmVdVEZNCqS7baC4crd0pqnRH_5IB3jw3bcxGn6QLvnEtfdUdiYrqBdss1l58BQ3KhooKeQTa9AB0Hw_Py5PJdTJNPY8cQn7ouZ2KKDcmnPGBY5t7yLc1QlQ5xHdwW1VhvKn-nXqhJTBgIPgtldC-KDV5z-y2XDwGUc",
    "q": "uQPEfgmVtjL0Uyyx88GZFF1fOunH3-7cepKmtH4pxhtCoHqpWmT8YAmZxaewHgHAjLYsp1ZSe7zFYHj7C6ul7TjeLQeZD_YwD66t62wDmpe_HlB-TnBA-njbglfIsRLtXlnDzQkv5dTltRJ11BKBBypeeF6689rjcJIDEz9RWdc",
    "dp": "BwKfV3Akq5_MFZDFZCnW-wzl-CCo83WoZvnLQwCTeDv8uzluRSnm71I3QCLdhrqE2e9YkxvuxdBfpT_PI7Yz-FOKnu1R6HsJeDCjn12Sk3vmAktV2zb34MCdy7cpdTh_YVr7tss2u6vneTwrA86rZtu5Mbr1C1XsmvkxHQAdYo0",
    "dq": "h_96-mK1R_7glhsum81dZxjTnYynPbZpHziZjeeHcXYsXaaMwkOlODsWa7I9xXDoRwbKgB719rrmI2oKr6N3Do9U0ajaHF-NKJnwgjMd2w9cjz3_-kyNlxAr2v4IKhGNpmM5iIgOS1VZnOZ68m6_pbLBSp3nssTdlqvd0tIiTHU",
    "qi": "IYd7DHOhrWvxkwPQsRM2tOgrjbcrfvtQJipd-DlcxyVuuM9sQLdgjVk2oy26F0EmpScGLq2MowX7fhd_QJQ3ydy5cY7YIBi87w93IKLEdfnbJtoOPLUW0ITrJReOgo1cq9SbsxYawBgfp_gh6A5603k2-ZQwVK0JKSHuLFkuQ3U"
})
"eyJhbGciOiAiUlMyNTYifQ.eyJhdWQiOiBbImJvYiIsICJzYXVsIl0sICJleHAiOiAxMzAwODE5MzgwLCAiaHR0cDovL2V4YW1wbGUuY29tL2lzX3Jvb3QiOiB0cnVlLCAiaXNzIjogImpvZSIsICJwcml2YXRlUGFyYW1zIjogeyJwcml2YXRlX29uZSI6ICJvbmUiLCAicHJpdmF0ZV90d28iOiAidHdvIn19.ITpfhDICCeVV__1nHRN2CvUFni0yyYESvhNlt4ET0yiySMzJ5iySGynrsM3kgzAv7mVmx5uEtSCs_xPHyLVfVnADKmDFtkZfuvJ8jHfcOe8TUqR1f7j1Zf_kDkdqJAsuGuqkJoFJ3S_gxWcZNwtDXV56O3k_7Mq03Ixuuxtip2oF0X3fB7QtUzjzB8mWPTJDFG2TtLLOYCcobPHmn36aAgesHMzJZj8U8sRLmqPXsIc-Lo_btt8gIUc9zZSgRiy7NOSHxw5mYcIMlKl93qvLXu7AaAcVLvzlIOCGWEnFpGGcRFgSOLnShQX6hDylWavKLQG-VOUJKmtXH99KBK-OYQ"
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.

io.jwt.encode_sign_raw(
    `{"typ":"JWT","alg":"HS256"}`,
     `{"iss":"joe","exp":1300819380,"http://example.com/is_root":true}`,
    `{"kty":"oct","k":"AyM1SysPpbyDfgZld3umj1qzKObwVMkoqQ-EstJQLr_T-1qS0gZH75aKtMN3Yj0iPS4hcgUuTwjAzZr1Z9CAow"}`
)
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLCJleHAiOjEzMDA4MTkzODAsImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.lliDzOlRAdGUCfCHCPx_uisb6ZfZ1LRQa0OJLeYTTpY"

Token Verification

Built-inDescription
output := io.jwt.verify_rs256(string, certificate)output is true if the RS256 signature of the input token is valid. certificate is the PEM encoded certificate or the JWK key (set) used to verify the RS256 signature
output := io.jwt.verify_ps256(string, certificate)output is true if the PS256 signature of the input token is valid. certificate is the PEM encoded certificate or the JWK key (set) used to verify the PS256 signature
output := io.jwt.verify_es256(string, certificate)output is true if the ES256 signature of the input token is valid. certificate is the PEM encoded certificate or the JWK key (set) used to verify the ES256 signature
output := io.jwt.verify_hs256(string, secret)output is true if the Secret signature of the input token is valid. secret is a plain text secret used to verify the HS256 signature
output := io.jwt.decode(string)output is of the form [header, payload, sig]. header and payload are object. sig is the hexadecimal representation of the signature on the token.
output := io.jwt.decode_verify(string, constraints)output is of the form [valid, header, payload]. If the input token verifies and meets the requirements of constraints then valid is true and header and payload are objects containing the JOSE header and the JWT claim set. Otherwise, valid is false and header and payload are {}.

Note that the io.jwt.verify_XX built-in methods verify only the signature. They do not provide any validation for the JWT payload and any claims specified. The io.jwt.decode_verify built-in will verify the payload and all standard claims.

The input string is a JSON Web Token encoded with JWS Compact Serialization. JWE and JWS JSON Serialization are not supported. If nested signing was used, the header, payload and signature will represent the most deeply nested token.

For io.jwt.decode_verify, constraints is an object with the following members:

NameMeaningRequired
certA PEM encoded certificate or a JWK key (set) containing an RSA or ECDSA public key.See below
secretThe secret key for HS256, HS384 and HS512 verification.See below
algThe JWA algorithm name to use. If it is absent then any algorithm that is compatible with the key is accepted.Optional
issThe issuer string. If it is present the only tokens with this issuer are accepted. If it is absent then any issuer is accepted.Optional
timeThe time in nanoseconds to verify the token at. If this is present then the exp and nbf claims are compared against this value. If it is absent then they are compared against the current time.Optional
audThe audience that the verifier identifies with. If this is present then the aud claim is checked against it. If it is absent then the aud claim must be absent too.Optional

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:

es256_token = "eyJ0eXAiOiAiSldUIiwgImFsZyI6ICJFUzI1NiJ9.eyJuYmYiOiAxNDQ0NDc4NDAwLCAiaXNzIjogInh4eCJ9.lArczfN-pIL8oUU-7PU83u-zfXougXBZj6drFeKFsPEoVhy9WAyiZlRshYqjTSXdaw8yw2L-ovt4zTUZb2PWMg"
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 the claims that the policy needs to enforce.

jwks = `{
    "keys": [{
        "kty":"EC",
        "crv":"P-256",
        "x":"z8J91ghFy5o6f2xZ4g8LsLH7u2wEpT2ntj8loahnlsE",
        "y":"7bdeXLH61KrGWRdh7ilnbcGQACxykaPKfmBccTHIOUo"
    }]
}`
io.jwt.verify_es256(es256_token, jwks)                  # Verify the token with the JWKS
[header, payload, _] := io.jwt.decode(es256_token)      # Decode the token
payload.iss == "xxx"                                    # Ensure the issuer (`iss`) claim is the expected value
+-----------------------------+--------------------------------+
|           header            |            payload             |
+-----------------------------+--------------------------------+
| {"alg":"ES256","typ":"JWT"} | {"iss":"xxx","nbf":1444478400} |
+-----------------------------+--------------------------------+

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.

[valid, header, payload] := io.jwt.decode_verify(es256_token, {
    "cert": jwks,
    "iss": "xxx",
})
+-----------------------------+--------------------------------+-------+
|           header            |            payload             | valid |
+-----------------------------+--------------------------------+-------+
| {"alg":"ES256","typ":"JWT"} | {"iss":"xxx","nbf":1444478400} | true  |
+-----------------------------+--------------------------------+-------+
Using PEM encoded X.509 Certificate

The following examples will demonstrate verifying tokens using an X.509 Certificate defined as:

cert = `-----BEGIN CERTIFICATE-----
MIIBcDCCARagAwIBAgIJAMZmuGSIfvgzMAoGCCqGSM49BAMCMBMxETAPBgNVBAMM
CHdoYXRldmVyMB4XDTE4MDgxMDE0Mjg1NFoXDTE4MDkwOTE0Mjg1NFowEzERMA8G
A1UEAwwId2hhdGV2ZXIwWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAATPwn3WCEXL
mjp/bFniDwuwsfu7bASlPae2PyWhqGeWwe23Xlyx+tSqxlkXYe4pZ23BkAAscpGj
yn5gXHExyDlKo1MwUTAdBgNVHQ4EFgQUElRjSoVgKjUqY5AXz2o74cLzzS8wHwYD
VR0jBBgwFoAUElRjSoVgKjUqY5AXz2o74cLzzS8wDwYDVR0TAQH/BAUwAwEB/zAK
BggqhkjOPQQDAgNIADBFAiEA4yQ/88ZrUX68c6kOe9G11u8NUaUzd8pLOtkKhniN
OHoCIHmNX37JOqTcTzGn2u9+c8NlnvZ0uDvsd1BmKPaUmjmm
-----END CERTIFICATE-----`

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.

io.jwt.verify_es256(es256_token, cert)                # Verify the token with the certificate
[header, payload, _] := io.jwt.decode(es256_token)    # Decode the token
payload.iss == "xxx"                                  # Ensure the issuer claim is the expected value
+-----------------------------+--------------------------------+
|           header            |            payload             |
+-----------------------------+--------------------------------+
| {"alg":"ES256","typ":"JWT"} | {"iss":"xxx","nbf":1444478400} |
+-----------------------------+--------------------------------+

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.

[valid, header, payload] := io.jwt.decode_verify(     # Decode and verify in one-step
    es256_token,
    {                                                 # With the supplied constraints:
        "cert": cert,                                 #   Verify the token with the certificate
        "iss": "xxx",                                 #   Ensure the issuer claim is the expected value
    }
)
+-----------------------------+--------------------------------+-------+
|           header            |            payload             | valid |
+-----------------------------+--------------------------------+-------+
| {"alg":"ES256","typ":"JWT"} | {"iss":"xxx","nbf":1444478400} | true  |
+-----------------------------+--------------------------------+-------+
Round Trip - Sign and Verify

This example shows how to encode a token, verify, and decode it with the different options available.

Start with using the io.jwt.encode_sign_raw built-in:

raw_result_hs256 := io.jwt.encode_sign_raw(
    `{"alg":"HS256","typ":"JWT"}`,
    `{}`,
    `{"kty":"oct","k":"Zm9v"}`  	# "Zm9v" is the base64 URL encoded string "foo"
)

# Important!! - Use the un-encoded plain text secret to verify and decode
raw_result_valid_hs256 := io.jwt.verify_hs256(raw_result_hs256, "foo")
raw_result_parts_hs256 := io.jwt.decode_verify(raw_result_hs256, {"secret": "foo"})
+----------------------------------------------------------------------------------------+---------------------------------------+------------------------+
|                                    raw_result_hs256                                    |        raw_result_parts_hs256         | raw_result_valid_hs256 |
+----------------------------------------------------------------------------------------+---------------------------------------+------------------------+
| "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.Duw7jWmGY54yEu6kcqd2w1TKp1EspzboBnx8EeMc-z0" | [true,{"alg":"HS256","typ":"JWT"},{}] | true                   |
+----------------------------------------------------------------------------------------+---------------------------------------+------------------------+

Now encode the and sign the same token contents but with io.jwt.encode_sign instead of the raw varient.

result_hs256 := io.jwt.encode_sign(
    {
        "alg":"HS256",
        "typ":"JWT"
    },
    {},
    {
        "kty":"oct",
        "k":"Zm9v"
    }
)

# Important!! - Use the un-encoded plain text secret to verify and decode
result_parts_hs256 := io.jwt.decode_verify(result_hs256, {"secret": "foo"})
result_valid_hs256 := io.jwt.verify_hs256(result_hs256, "foo")
+--------------------------------------------------------------------------------------------+---------------------------------------+--------------------+
|                                        result_hs256                                        |          result_parts_hs256           | result_valid_hs256 |
+--------------------------------------------------------------------------------------------+---------------------------------------+--------------------+
| "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.e30.h4crob8QjgDq0JlZpf5mtylPvUzULS0XzdbG2-z_YKc" | [true,{"alg":"HS256","typ":"JWT"},{}] | true               |
+--------------------------------------------------------------------------------------------+---------------------------------------+--------------------+

Note that the resulting encoded token is different from the first example using io.jwt.encode_sign_raw. The reason is that the io.jwt.encode_sign function is using canonicalized formatting for the header and payload whereas io.jwt.encode_sign_raw does not change the whitespace of the strings passed in. The decoded and parsed JSON values are still the same.

Time

Built-inDescription
output := time.now_ns()output is number representing the current time since epoch in nanoseconds.
output := time.parse_ns(layout, value)output is number representing the time value in nanoseconds since epoch. See the Go time package documentation for more details on layout.
output := time.parse_rfc3339_ns(value)output is number representing the time value in nanoseconds since epoch.
output := time.parse_duration_ns(duration)output is number representing the duration duration in nanoseconds. See the Go time package documentation for more details on duration.
output := time.date(ns)
output := time.date([ns, tz])
output is of the form [year, month, day], which includes the year, month (0-12), and day (0-31) as numbers representing the date from the nanoseconds since epoch (ns) in the timezone (tz), if supplied, or as UTC.
output := time.clock(ns)
output := time.clock([ns, tz])
output is of the form [hour, minute, second], which outputs the hour, minute (0-59), and second (0-59) as numbers representing the time of day for the nanoseconds since epoch (ns) in the timezone (tz), if supplied, or as UTC.
day := time.weekday(ns)
day := time.weekday([ns, tz])
outputs the day as string representing the day of the week for the nanoseconds since epoch (ns) in the timezone (tz), if supplied, or as UTC.

Multiple calls to the time.now_ns built-in function within a single policy evaluation query will always return the same value.

Timezones can be specified as

  • an IANA Time Zone string e.g. “America/New_York”
  • “UTC” or “”, which are equivalent to not passing a timezone (i.e. will return as UTC)
  • “Local”, which will use the local timezone.

Note that the opa executable will need access to the timezone files in the environment it is running in (see the Go time.LoadLocation() documentation for more information).

Cryptography

Built-inDescription
output := crypto.x509.parse_certificates(string)output is an array of X.509 certificates represented as JSON objects.
output := crypto.md5(string)output is string md5 hashed.
output := crypto.sha1(string)output is string sha1 hashed.
output := crypto.sha256(string)output is string sha256 hashed.

Graphs

Built-inDescription
walk(x, [path, value])walk is a relation that produces path and value pairs for documents under x. path is array representing a pointer to value in x. Queries can use walk to traverse documents nested under x (recursively).

HTTP

Built-inDescription
response := http.send(request)http.send executes an HTTP request and returns a response.

The request object parameter may contain the following fields:

FieldRequiredTypeDescription
urlyesstringHTTP URL to specify in the request (e.g., "https://www.openpolicyagent.org").
methodyesstringHTTP method to specify in request (e.g., "GET", "POST", "PUT", etc.)
bodynoanyHTTP message body to include in request. The value will be serialized to JSON.
raw_bodynostringHTTP message body to include in request. The value WILL NOT be serialized. Use this for non-JSON messages.
headersnoobjectHTTP headers to include in the request (e.g,. {"X-Opa": "rules"}).
enable_redirectnobooleanFollow HTTP redirects. Default: false.
force_json_decodenobooleanDecode the HTTP response message body as JSON even if the Content-Type header is missing. Default: false.
tls_use_system_certsnobooleanUse system certificate pool.
tls_ca_cert_filenostringPath to file containing a root certificate in PEM encoded format.
tls_ca_cert_env_variablenostringEnvironment variable containing a root certificate in PEM encoded format.
tls_client_cert_env_variablenostringEnvironment variable containing a client certificate in PEM encoded format.
tls_client_key_env_variablenostringEnvironment variable containing a client key in PEM encoded format.
tls_client_cert_filenostringPath to file containing a client certificate in PEM encoded format.
tls_client_key_filenostringPath to file containing a key in PEM encoded format.
timeoutnostring or numberTimeout for the HTTP request with a default of 5 seconds (5s). Numbers provided are in nanoseconds. Strings must be a valid duration string where a duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as “300ms”, “-1.5h” or “2h45m”. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”. A zero timeout means no timeout.

When sending HTTPS requests with client certificates at least one the following combinations must be included

  • tls_client_cert_file and tls_client_key_file
  • tls_client_cert_env_variable and tls_client_key_env_variable

The user must also provide a trusted root CA through tls_ca_cert_file or tls_ca_cert_env_variable. Alternatively the user could set tls_use_system_certs to true and the system certificate pool will be used.

The response object parameter will contain the following fields:

FieldTypeDescription
statusstringHTTP status message (e.g., "200 OK").
status_codenumberHTTP status code (e.g., 200).
bodyanyAny JSON value. If the HTTP response message body was not deserialized from JSON, this field is set to null.
raw_bodystringThe entire raw HTTP resposne message body represented as a string.

The table below shows examples of calling http.send:

ExampleComments
Accessing Google using System Cert Poolhttp.send({"method": "get", "url": "https://www.google.com", "tls_use_system_certs": true })
Files containing TLS materialhttp.send({"method": "get", "url": "https://127.0.0.1:65331", "tls_ca_cert_file": "testdata/ca.pem", "tls_client_cert_file": "testdata/client-cert.pem", "tls_client_key_file": "testdata/client-key.pem"})
Environment variables containing TLS materialhttp.send({"method": "get", "url": "https://127.0.0.1:65360", "tls_ca_cert_env_variable": "CLIENT_CA_ENV", "tls_client_cert_env_variable": "CLIENT_CERT_ENV", "tls_client_key_env_variable": "CLIENT_KEY_ENV"})

Net

Built-inDescription
net.cidr_contains(cidr, cidr_or_ip)output is true if cidr_or_ip (e.g. 127.0.0.64/26 or 127.0.0.1) is contained within cidr (e.g. 127.0.0.1/24) and false otherwise. Supports both IPv4 and IPv6 notations.
net.cidr_intersects(cidr1, cidr2)output is true if cidr1 (e.g. 192.168.0.0/16) overlaps with cidr2 (e.g. 192.168.1.0/24) and false otherwise. Supports both IPv4 and IPv6 notations.
net.cidr_expand(cidr)output is the set of hosts in cidr (e.g., net.cidr_expand("192.168.0.0/30") generates 4 hosts: {"192.168.0.0", "192.168.0.1", "192.168.0.2", "192.168.0.3"}

Rego

Built-inDescription
output := rego.parse_module(filename, string)rego.parse_module parses the input string as a Rego module and returns the AST as a JSON object output.

OPA

Built-inDescription
output := opa.runtime()opa.runtime returns a JSON object output that describes the runtime environment where OPA is deployed. Caution: Policies that depend on the output of opa.runtime may return different answers depending on how OPA was started. If possible, prefer using an explicit input or data value instead of opa.runtime. The output of opa.runtime will include a "config" key if OPA was started with a configuration file. The output of opa.runtime will include a "env" key containing the environment variables that the OPA process was started with. The output of opa.runtime will include "version" and "commit" keys containing the semantic version and build commit of OPA.

Debugging

Built-inDescription
trace(string)trace outputs the debug message string as a Note event in the query explanation. For example, trace("Hello There!") includes Note "Hello There!" in the query explanation. To print variables, use sprintf. For example, person := "Bob"; trace(sprintf("Hello There! %v", [person])) will emit Note "Hello There! Bob".

Reserved Names

The following words are reserved and cannot be used as variable names, rule names, or dot-access style reference arguments:

as
default
else
false
import
package
not
null
true
with

Grammar

Rego’s syntax is defined by the following grammar:

module          = package { import } policy
package         = "package" ref
import          = "import" package [ "as" var ]
policy          = { rule }
rule            = [ "default" ] rule-head { rule-body }
rule-head       = var [ "(" rule-args ")" ] [ "[" term "]" ] [ ( ":=" / "=" ) term ]
rule-args       = term { "," term }
rule-body       = [ else [ = term ] ] "{" query "}"
query           = literal { ";" | [\r\n] literal }
literal         = ( some-decl | expr | "not" expr ) { with-modifier }
with-modifier   = "with" term "as" term
some-decl       = "some" var { "," var }
expr            = term | expr-call | expr-infix
expr-call       = var [ "." var ] "(" [ term { , term } ] ")"
expr-infix      = [ term "=" ] term infix-operator term
term            = ref | var | scalar | array | object | set | array-compr | object-compr | set-compr
array-compr     = "[" term "|" rule-body "]"
set-compr       = "{" term "|" rule-body "}"
object-compr    = "{" object-item "|" rule-body "}"
infix-operator  = bool-operator | arith-operator | bin-operator
bool-operator   = "==" | "!=" | "<" | ">" | ">=" | "<="
arith-operator  = "+" | "-" | "*" | "/"
bin-operator    = "&" | "|"
ref             = ( var | array | object | set | array-compr | object-compr | set-compr | expr-call ) { ref-arg }
ref-arg         = ref-arg-dot | ref-arg-brack
ref-arg-brack   = "[" ( scalar | var | array | object | set | "_" ) "]"
ref-arg-dot     = "." var
var             = ( ALPHA | "_" ) { ALPHA | DIGIT | "_" }
scalar          = string | NUMBER | TRUE | FALSE | NULL
string          = STRING | raw-string
raw-string      = "`" { CHAR-"`" } "`"
array           = "[" term { "," term } "]"
object          = "{" object-item { "," object-item } "}"
object-item     = ( scalar | ref | var ) ":" term
set             = empty-set | non-empty-set
non-empty-set   = "{" term { "," term } "}"
empty-set       = "set(" ")"

The grammar defined above makes use of the following syntax. See the Wikipedia page on EBNF for more details:

[]     optional (zero or one instances)
{}     repetition (zero or more instances)
|      alternation (one of the instances)
()     grouping (order of expansion)
STRING JSON string
NUMBER JSON number
TRUE   JSON true
FALSE  JSON false
NULL   JSON null
CHAR   Unicode character
ALPHA  ASCII characters A-Z and a-z
DIGIT  ASCII characters 0-9