Using the 3scale WebAssembly module

Service Mesh provides a custom resource definition to specify and apply Proxy-WASM extensions to sidecar proxies, known as WasmPlugin. Service Mesh applies this custom resource to the set of workloads that require HTTP API management with 3scale.

The architecture of the 3scale WebAssembly module configuration depends on the 3scale account and authorization service, and the list of services to handle.

The prerequisites are a set of minimum mandatory fields in all cases:

The api top-level string from the 3scale WebAssembly module defines which version of the configuration the module will use.

The api entry defines the rest of the values for the configuration. The only accepted value is v1. New settings that break compatibility with the current configuration or need more logic that modules using v1 cannot handle, will require different values.

The system top-level object specifies how to access the 3scale Account Management API for a specific account. The upstream field is the most important part of the object. The system object is optional, but recommended unless you are providing a fully static configuration for the 3scale WebAssembly module, which is an option if you do not want to provide connectivity to the system component of 3scale.

When you provide static configuration objects in addition to the system object, the static ones always take precedence.

The upstream object describes an external host to which the proxy can perform calls.

The backend top-level object specifies how to access the 3scale Service Management API for authorizing and reporting HTTP requests. This service is provided by the Backend component of 3scale.

The services top-level object specifies which service identifiers are handled by this particular instance of the module.

Since accounts have multiple services, you must specify which ones are handled. The rest of the configuration revolves around how to configure services.

The services field is required. It is an array that must contain at least one service to be useful.

Each element in the services array represents a 3scale service.

The credentials object is a component of the service object. credentials specifies which kind of credentials to be looked up and the steps to perform this action.

All fields are optional, but you must specify at least one, user_key or app_id. The order in which you specify each credential is irrelevant because it is pre-established by the module. Only specify one instance of each credential.

The lookup query object is part of any of the fields in the credentials object. It specifies how a given credential field should be found and processed. When evaluated, a successful resolution means that one or more values were found. A failed resolution means that no values were found.

Arrays of lookup queries describe a short-circuit or relationship: a successful resolution of one of the queries stops the evaluation of any remaining queries and assigns the value or values to the specified credential-type. Each query in the array is independent of each other.

A lookup query is made up of a single field, a source object, which can be one of a number of source types. See the following example:

A source object exists as part of an array of sources within any of the credentials object fields. The object field name, referred to as a source-type is any one of the following:

All source-type objects have at least the following two fields:

The filter field name has a required path entry to show the path in the metadata you use to look up data.

When a key matches the input data, the rest of the keys are not evaluated and the source resolution algorithm jumps to executing the operations (ops) specified, if any. If no ops are specified, the result value of the matching key, if any, is returned.

Operations provide a way to specify certain conditions and transformations for inputs you have after the first phase looks up a key. Use operations when you need to transform, decode, and assert properties, however they do not provide a mature language to deal with all needs and lack Turing-completeness.

A stack stored the outputs of operations. When evaluated, the lookup query finishes by assigning the value or values at the bottom of the stack, depending on how many values the credential consumes.

Each element in the ops array belonging to a specific source type is an operation object that either applies transformations to values or performs tests. The field name to use for such an object is the name of the operation itself, and any values are the parameters to the operation, which could be structure objects, for example, maps with fields and values, lists, or strings.

Most operations attend to one or more inputs, and produce one or more outputs. When they consume inputs or produce outputs, they work with a stack of values: each value consumed by the operations is popped from the stack of values and initially populated with any source matches. The values outputted by them are pushed to the stack. Other operations do not consume or produce outputs other than asserting certain properties, but they inspect a stack of values.

There are a few different operations categories:

All operations are specified by the name identifiers as strings.

The mapping_rules object is part of the service object. It specifies a set of REST path patterns and related 3scale metrics and count increments to use when the patterns match.

You need the value if no dynamic configuration is provided in the system top-level object. If the object is provided in addition to the system top-level entry, then the mapping_rules object is evaluated first.

mapping_rules is an array object. Each element of that array is a mapping_rule object. The evaluated matching mapping rules on an incoming request provide the set of 3scale methods for authorization and reporting to the APIManager. When multiple matching rules refer to the same methods, there is a summation of deltas when calling into 3scale. For example, if two rules increase the Hits method twice with deltas of 1 and 3, a single method entry for Hits reporting to 3scale has a delta of 4.

The mapping_rule object is part of an array in the mapping_rules object.

The mapping_rule object fields specify the following information:

The following example is independent of existing hierarchies between methods in 3scale. That is, anything run on the 3scale side will not affect this. For example, the Hits metric might be a parent of them all, so it stores 4 hits due to the sum of all reported methods in the authorized request and calls the 3scale Authrep API endpoint.

The example below uses a GET request to a path, /products/1/sold, that matches all the rules.

All usages get added to the request the module performs to 3scale with usage data as follows:

The following example looks up a user_key in a query string parameter or header of the same name:

The following example looks up app_key and app_id credentials in a query or headers.

A request includes an app_id and app_key in an authorization header. If there is at least one or two values outputted at the end, then you can assign the app_key.

The resolution here assigns the app_key if there is one or two outputted at the end.

The authorization header specifies a value with the type of authorization and its value is encoded as Base64. This means you can split the value by a space character, take the second output and then split it again using a colon (:) as the separator. For example, if you use this format app_id:app_key, the header looks like the following example for credential:

You must use lower case header field names as shown in the following example:

The previous example use case looks at the headers for an authorization:

The last operation, assert, indicates that no side-effects make it into the stack. You can then modify the stack:

For Service Mesh and the 3scale Istio adapter, you must deploy a RequestAuthentication as shown in the following example, filling in your own workload data and jwtRules:

When you apply the RequestAuthentication, it configures Envoy with a native plugin to validate JWT tokens. The proxy validates everything before running the module so any requests that fail do not make it to the 3scale WebAssembly module.

When a JWT token is validated, the proxy stores its contents in an internal metadata object, with an entry whose key depends on the specific configuration of the plugin. This use case gives you the ability to look up structure objects with a single entry containing an unknown key name.

The 3scale app_id for OIDC matches the OAuth client_id. This is found in the azp or aud fields of JWT tokens.

To get app_id field from Envoy’s native JWT authentication filter, see the following example:

The example instructs the module to use the filter source type to look up filter metadata for an object from the Envoy-specific JWT authentication native plugin. This plugin includes the JWT token as part of a structure object with a single entry and a preconfigured name. Use 0 to specify that you will only access the single entry.

The resulting value is a structure for which you will resolve two fields:

The operation ensures only one value is held for assignment.

Some setups might have validation processes for JWT tokens where the validated token would reach this module via a header in JSON format.

To get the app_id, see the following example: