Username Params

Username parameters let you embed structured routing hints in the presented username.

They do not select an egress path by themselves. The extracted key-value pairs are copied into the egress context and can then be consumed by a helper such as comply_context. See Egress Path Selection for the full data flow.

The authentication username is the portion before the first recognized parameter key.

Example configuration:

required_keys:
  - country
optional_keys:
  - city

If the client sends test-me-country-cn-city-none, the authentication username becomes test-me.

Parsing notes derived from the implementation:

  • The username must contain a non-empty prefix before the first recognized parameter key. A string made entirely of parameters is rejected.

  • Parameters are parsed as <separator><key><separator><value> pairs. A trailing key without a value is rejected.

  • If the same parameter key appears multiple times, the last value wins.

  • Unknown keys are either rejected or ignored, depending on reject_unknown_keys.

The configuration value is a map with the following keys:

required_keys

optional, type: list of string, alias: required

Required parameter keys.

The request fails if any required key is missing from the username supplied by the client.

optional_keys

optional, type: list of string, alias: optional

Optional parameter keys.

The same key must not appear in both required_keys and optional_keys.

reject_unknown_keys

optional, type: bool, alias: reject_unknown

Set to true to reject unknown keys, meaning keys that are neither in required_keys nor in optional_keys.

The request fails if the client-supplied username contains an unknown parameter key.

default: true

param_separator

optional, type: char

Separator character used between parameter keys and values.

default: ‘-’

Example

username_params:
  required_keys: [country]
  optional_keys: [city, line]
  reject_unknown_keys: false
  param_separator: '-'

With that configuration, alice-country-us-city-sea-extra-ignored is accepted and produces:

  • authentication username: alice

  • egress context: country=us, city=sea