Filters

Following filters are supported:

• hex: Converts a string or a byte value into a hexadecimal string. Outputs lowercase hexadecimal digits without separators. Example: "Hello" becomes "48656c6c6f"
• hex_decode: Converts hexadecimal text into bytes. Use this filter to restore binary protocol values, such as a RADIUS State attribute returned as hexadecimal JSON text.
• base64_encode: Converts string or byte input into standard padded Base64 text. Multivalue input is concatenated in order before encoding, which reassembles fragmented RADIUS EAP-Message attributes. Use this filter to carry binary protocol values in JSON.
• base64_decode: Converts standard padded Base64 text into bytes. Use this filter to restore binary protocol values, such as RADIUS EAP-Message and State attributes received in JSON.
• base64url_encode: Converts string or byte input into URL-safe Base64 text without padding. Multivalue input is concatenated in order before encoding.
• base64url_decode: Converts URL-safe Base64 text, with or without padding, into bytes.
• sha256: Returns the raw 32-byte SHA-256 digest of each string or byte input value. Append hex or base64url_encode for text output.
• string: Converts a non-string or a byte value into a string. Masked passwords remain masked after conversion and require the reveal filter for plaintext access.
• uppercase: Converts a string value into uppercase
• lowercase: Converts a string value into lowercase
• value: Converts to a raw value format
• timestamp: Converts Unix timestamp seconds, RFC3339 text, or RFC2822 text into a timestamp value. See Timestamps
• timestamp_format([format]): Formats timestamp values, Unix timestamp seconds, or timestamp text as RFC3339 text, or with a custom timestamp format such as [year]-[month]-[day]. See Timestamps
• printable: Converts byte data to a printable ASCII string
• normalize_mac: Normalizes MAC address format to 12 lowercase hexadecimal digits without separators, preserving any trailing characters. Example: "00:1A:2B:3C:4D:5E" becomes "001a2b3c4d5e"
• escape_double_quotes: Escapes double quotes in a string
• ldap_dn_escape: Escapes special characters in LDAP distinguished names
• ldap_escape: Escapes special characters in LDAP search strings
• url_escape: Performs URL encoding on the string
• xml_escape: Escapes special characters in XML content
• substring(<start>[, <end>]): Extracts a substring from the value
• yubikey("<placement>", "<extract>"): Validates a Yubico OTP carried in a string value and returns either the full OTP or one of its components. Placement ("otp", "password_otp", "otp_password") selects where the OTP sits in the input; extract ("otp", "public_uid", "ciphertext", "password") selects what to return. Both arguments are quoted strings; unquoted names are deprecated but still accepted. Accepts plain strings, byte strings, and masked passwords. See YubiKey OTP filter for full reference and examples.
• split(<separator>[, <maxsplit>]): Splits a string into multiple values using either a string separator or a regex separator. If maxsplit is given, at most maxsplit splits are done. Examples:
  • "a,b,c" | split(",") returns "a", "b", and "c"
  • "a-b,,c" | split(/[,-]+/) returns "a", "b", and "c"
  • "a,b,c" | split(",", 1) returns "a" and "b,c"
• rsplit(<separator>[, <maxsplit>]): Splits a string into multiple values like split(), but applies maxsplit from the right. Examples:
  • "a,b,c" | rsplit(",") returns "a", "b", and "c"
  • "a-b,,c" | rsplit(/[,-]+/, 1) returns "a-b" and "c"
  • "a,b,c" | rsplit(",", 1) returns "a,b" and "c"
• type: Get internal type information of a value
• default(<default value>): Provides a default value if the value is none
• recover(<fallback>): If a filter fails, use this to recover from the error using the fallback value
• json: Parse a JSON string to a JSON value, or accept an already-parsed JSON value as-is (standard JSON only)
• jsonpath(<jsonpath expression>): Extract value from JSON using a JSONPath expression. Accepts both parsed JSON values and JSON strings (parsed automatically)
• regex: Parse string value to regex
• join(<separator>): Join array elements into a single string using the specified separator
• count: Returns the number of values in a multivalue. Useful for checking array lengths. Example: vars.groups | count returns 3 if vars.groups contains three values
• reveal: Reveals masked passwords. Example: radius.request.password | reveal
  • NOTE: Masked password can be compared directly without revealing!
• remove(<args...>): Removes values matching arguments from multivalue data or RADIUS attribute collections. See Filtering multivalue data and Filtering attributes in queries
• select(<args...>): Keeps only values matching arguments in multivalue data or RADIUS attribute collections. See Filtering multivalue data and Filtering attributes in queries
• hmac_sha256(<key>): Returns a raw 32-byte HMAC-SHA256 signature for each input value. Append hex or base64_encode for text output.
• hmac_sha384(<key>): As above, using SHA-384 with 48-byte output.
• hmac_sha512(<key>): As above, using SHA-512 with 64-byte output.

substring

substring(<start>[, <end>]) extracts a substring from the value. The start parameter is required and specifies the starting character position (zero-indexed). The optional end parameter specifies the ending position (exclusive). Negative values count from the end of the string. Examples:

• "example" | substring(2, 5) returns "amp" (characters from index 2 to 5)
• "example" | substring(0, -1) returns "exampl" (all except last character)
• "example" | substring(-3, 0) returns "ple" (last 3 characters)
• "password123456" | substring(0, -6) returns "password" (remove last 6 characters)
• "password123456" | substring(-6) returns "123456" (last 6 characters)

Usage

Filters can be used in any expression. The syntax is:

radius.reply.attr.Alc-Subsc-ID-Str = vars.subscriber_id | substring(2, 10) | uppercase;

It is also possible to use filters in format strings:

radius.reply.attr.Alc-Subsc-ID-Str = "FIBER.%{ vars.subscriber_id | substring(2, 10) | uppercase }";

Working with JSON data

The jsonpath filter accepts both parsed JSON values and JSON strings - the string is parsed automatically. An explicit | json step is optional, but useful when the same parsed value is reused multiple times:

vars.user_json = vars.user_data | json;
vars.user_name = vars.user_json | jsonpath("$.name");
vars.user_email = vars.user_json | jsonpath("$.email");

See JSONPath for context references, array results, and examples using JSON from RadiatorDB, SQL, and HTTP.

Error handling

Sometimes a filter can fail. For example, when trying to parse invalid input with the json filter or regexes with the regex filter, they will produce an error value.

You may recover from these errors using the recover filter. For example:

vars.user_json = vars.user_data | json | recover("{\"name\": \"unknown\"}" | json);
vars.user_name = vars.user_json | jsonpath("$.name");

Filter errors do not cause execution pipeline errors immediately, but if an error value is attempted to be assigned, for example to a RADIUS reply attribute, it will cause a pipeline error and the authentication will be rejected. However, the error values are allowed to be logged.

The error value is false in all comparison operations and all filters just pass it through.

A jsonpath filter returns no values when nothing matches. Query errors during execution produce error values. See JSONPath error handling for missing references, invalid input, and recovery examples.

SQL mappings

SQL backend query mappings support filter expressions to transform column values. See SQL query mappings for examples that extract fields from JSON columns.

Filtering multivalue data

The remove and select filters can operate on multivalue data, filtering individual values based on regex patterns or attribute identifiers.

remove(<args...>)

Removes values matching any of the specified arguments:

# Remove specific values from cisco-avpair that match the pattern
radius.request.attr.cisco-avpair = radius.request.attr.cisco-avpair[*] | remove(/ding=.+/);

select(<args...>)

Keeps only values matching any of the specified arguments, removing all others:

# Keep only cisco-avpair values matching the pattern
radius.request.attr.cisco-avpair = radius.request.attr.cisco-avpair[*] | select(/dong=.+/);

For filtering RADIUS attribute collections (bulk attrs), see Filtering attributes in queries in the RADIUS backend query documentation.

HMAC-SHA2

hmac_sha256(<key>), hmac_sha384(<key>) and hmac_sha512(<key>) return raw 32-, 48- and 64-byte signatures respectively for each input value. Messages accept strings or bytes; keys accept strings, bytes or masked passwords. The required key argument can be a runtime expression. Append hex or base64_encode for text output, for example: vars.message | hmac_sha256(vars.secret) | hex.

Missing, empty or unsupported values produce value errors handled with recover(). Errors do not include key material. With multiple inputs, each signature remains separate; base64_encode concatenates them before encoding.

See Chargeable-User-Identity for an usage example.

Base64url and SHA-256

base64url_encode and base64url_decode use the URL-safe Base64 alphabet defined in RFC 4648 section 5. This alphabet uses - and _ instead of + and /. base64url_encode never adds = padding. base64url_decode accepts input with or without padding and rejects the standard + and / characters. JSON Web Tokens, OAuth 2.0 and OpenID Connect use this encoding.

sha256 returns the raw 32-byte digest of each input value. Inputs accept strings or bytes. A missing input stays none, and unsupported input types produce value errors handled with recover().

Derive a PKCE (Proof Key for Code Exchange) S256 code challenge from a code verifier:

vars.code_challenge = vars.code_verifier | sha256 | base64url_encode;

Decode a JSON value carried as URL-safe Base64 text in a query parameter:

vars.state = http.query.state | base64url_decode | string | json;

See also

• Environment Variables -- using environment variables and the default() filter in configuration values