1. Documentation
    2. history bug_report picture_as_pdf
×

Using the 3scale WebAssembly module

The threescale-wasm-auth module runs on integrations of 3scale API Management 2.11 or later with Red Hat OpenShift Service Mesh 2.1.0 or later.

The threescale-wasm-auth module is a WebAssembly module that uses a set of interfaces, known as an application binary interfaces (ABI). This is defined by the Proxy-WASM specification to drive any piece of software that implements the ABI so it can authorize HTTP requests against 3scale.

As an ABI specification, Proxy-WASM defines the interaction between a piece of software named host and another named module, program, or extension. The host exposes a set of services used by the module to perform a task, and in this case, to process proxy requests.

The host environment is composed of a WebAssembly virtual machine interacting with a piece of software, in this case, an HTTP proxy.

The module itself runs in isolation to the outside world except for the instructions it runs on the virtual machine and the ABI specified by Proxy-WASM. This is a safe way to provide extension points to software: the extension can only interact in well-defined ways with the virtual machine and the host. The interaction provides a computing model and a connection to the outside world the proxy is meant to have.

Compatibility

The threescale-wasm-auth module is designed to be fully compatible with all implementations of the Proxy-WASM ABI specification. At this point, however, it has only been thoroughly tested to work with the Envoy reverse proxy.

Usage as a stand-alone module

Because of its self-contained design, it is possible to configure this module to work with Proxy-WASM proxies independently of Service Mesh, as well as 3scale Istio adapter deployments.

Prerequisites

  • The module works with all supported 3scale releases, except when configuring a service to use OpenID connect (OIDC), which requires 3scale 2.11 or later.

Configuring the threescale-wasm-auth module

Cluster administrators on OpenShift Container Platform can configure the threescale-wasm-auth module to authorize HTTP requests to 3scale API Management through an application binary interface (ABI). The ABI defines the interaction between host and the module, exposing the hosts services, and allows you to use the module to process proxy requests.

The Service Mesh extension

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

See custom resource definition for more information.

Configuring the WebAssembly extension is currently a manual process. Support for fetching the configuration for services from the 3scale system will be available in a future release.
Prerequisites

  • Identify a Kubernetes workload and namespace on your Service Mesh deployment that you will apply this module.

  • You must have a 3scale tenant account. See SaaS or 3scale 2.11 On-Premises with a matching service and relevant applications and metrics defined.

  • If you apply the module to the productpage microservice in the bookinfo namespace, see the Bookinfo sample application.

    • The following example is the YAML format for the custom resource for threescale-wasm-auth module. This example refers to the upstream Maistra version of Service Mesh, ServiceMeshExtension API. You must declare the namespace where the threescale-wasm-auth module is deployed, alongside a WorkloadSelector to identify the set of applications the module will apply to:

      apiVersion: maistra.io/v1
kind: ServiceMeshExtension
metadata:
  name: threescale-wasm-auth
  namespace: bookinfo (1)
spec:
  workloadSelector: (2)
    labels:
      app: productpage
  config: <yaml_configuration>
  image: registry.redhat.io/openshift-service-mesh/3scale-auth-wasm-rhel8:0.0.1
  phase: PostAuthZ
  priority: 100
      1 The namespace.
      2 The WorkloadSelector.

  • The spec.config field depends on the module configuration and it is not populated in the previous example. Instead, the example uses the <yaml_configuration> placeholder value. You can use the format of this custom resource example.

    • The spec.config field varies depending on the application. All other fields persist across multiple instances of this custom resource. As examples:

      • image: Only changes when newer versions of the module are deployed.

      • phase: Remains the same, since this module needs to be invoked after the proxy has done any local authorization, such as validating OpenID Connect (OIDC) tokens.

  • After you have the module configuration in spec.config and the rest of the custom resource, apply it with the oc apply command:

    $ oc apply -f threescale-wasm-auth-bookinfo.yaml
Additional resources

Applying 3scale external ServiceEntry objects

To have the threescale-wasm-auth module authorize requests against 3scale, the module must have access to 3scale services. You can accomplish this within Red Hat OpenShift Service Mesh and Istio by applying an external ServiceEntry object.

The custom resources set up the service entries for access from within Service Mesh to 3scale Hosted (SaaS) for the backend and system components of the Service Management API and the Account Management API. The Service Management API receives queries for the authorization status of each request. The Account Management API provides API management configuration settings for your services.

Procedure

  • Apply the following external ServiceEntry custom resources to your cluster:

    Custom resource for 3scale Hosted backend
    apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: threescale-saas-backend
spec:
  hosts:
  - su1.3scale.net
  ports:
  - number: 443
    name: https
    protocol: HTTPS
  location: MESH_EXTERNAL
  resolution: DNS
    Custom resource for 3scale Hosted system
    apiVersion: networking.istio.io/v1beta1
kind: ServiceEntry
metadata:
  name: threescale-saas-system
spec:
  hosts:
  - multitenant.3scale.net
  ports:
  - number: 443
    name: https
    protocol: HTTPS
  location: MESH_EXTERNAL
  resolution: DNS

    You can use the oc apply command with either of the following methods to apply the objects:

    • Save the objects to one or more files, and then use the following syntax:

      $ oc apply -f <filename.yml>

    • To apply the objects without first saving them to a file, use the following command:

      $ echo -n "<filename.yml>" | oc apply -f -

Alternatively, you can deploy an in-mesh 3scale service. To do this, change the location of these services in the custom resources.

Additional resources

The 3scale WebAssembly module configuration

The ServiceMeshExtension custom resource spec provides the configuration that the Proxy-WASM module reads from.

The spec is embedded in the host and read by the Proxy-WASM module. Typically, the configurations are in the JSON file format for the modules to parse, however the ServiceMeshExtension resource can interpret the spec value as YAML and convert it to JSON for consumption by the module.

If you use the Proxy-WASM module in stand-alone mode, you must write the configuration using the JSON format. Using the JSON format means using escaping and quoting where needed within the host configuration files, for example Envoy. When you use the WebAssembly module with the ServiceMeshExtension resource, the configuration is in the YAML format. In this case, an invalid configuration forces the module to show diagnostics based on its JSON representation to a sidecar’s logging stream.

The EnvoyFilter custom resource is not a supported API, although it can be used in some 3scale Istio adapter or Service Mesh releases. Using the EnvoyFilter custom resource is not recommended. Use the ServiceMeshExtension API instead of the EnvoyFilter custom resource. If you must use the EnvoyFilter custom resource, you must specify the spec in JSON format.

Configuring the 3scale WebAssembly module

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

Prerequisites

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

  • For the 3scale account and authorization service: the backend-listener URL.

  • For the list of services to handle: the service IDs and at least one credential look up method and where to find it.

  • You will find examples for dealing with userkey, appid with appkey, and OpenID Connect (OIDC) patterns.

  • The WebAssembly module uses the settings you specified in the static configuration. For example, if you add a mapping rule configuration to the module, it will always apply, even when the 3scale Admin Portal has no such mapping rule. The rest of the ServiceMeshExtension resource exists around the spec.config YAML entry.

The 3scale WebAssembly module api object

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

A non-existent or unsupported version of the api object renders the 3scale WebAssembly module inoperable.
The api top-level string example
apiVersion: maistra.io/v1
kind: ServiceMeshExtension
metadata:
  name: threescale-wasm-auth
  namespace: bookinfo
spec:
  config:
    api: v1
...

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 3scale WebAssembly module system object

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.

apiVersion: maistra.io/v1
kind: ServiceMeshExtension
metadata:
  name: threescale-wasm-auth
spec:
  ...
  config:
    system:
      name: saas_porta
      upstream: <object>
      token: myaccount_token
      ttl: 300
  ...
Table 1. system object fields
Name Description Required

name

An identifier for the 3scale service, currently not referenced elsewhere.

Optional

upstream

The details about a network host to be contacted. upstream refers to the 3scale Account Management API host known as system.

Yes

token

A 3scale personal access token with read permissions.

Yes

ttl

The minimum amount of seconds to consider a configuration retrieved from this host as valid before trying to fetch new changes. The default is 600 seconds (10 minutes). Note: there is no maximum amount, but the module will generally fetch any configuration within a reasonable amount of time after this TTL elapses.

Optional

The 3scale WebAssembly module upstream object

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

apiVersion: maistra.io/v1
upstream:
  name: outbound|443||multitenant.3scale.net
  url: "https://myaccount-admin.3scale.net/"
  timeout: 5000
...
Table 2. upstream object fields
Name Description Required

name

name is not a free-form identifier. It is the identifier for the external host as defined by the proxy configuration. In the case of stand-alone Envoy configurations, it maps to the name of a Cluster, also known as upstream in other proxies. Note: the value of this field, because the Service Mesh and 3scale Istio adapter control plane configure the name according to a format using a vertical bar (|) as the separator of multiple fields. For the purposes of this integration, always use the format: outbound|<port>||<hostname>.

Yes

url

The complete URL to access the described service. Unless implied by the scheme, you must include the TCP port.

Yes

Timeout

Timeout in milliseconds so that connections to this service that take more than the amount of time to respond will be considered errors. Default is 1000 seconds.

Optional

The 3scale WebAssembly module backend object

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.

apiVersion: maistra.io/v1
kind: ServiceMeshExtension
metadata:
  name: threescale-wasm-auth
spec:
  config:
    ...
    backend:
      name: backend
      upstream: <object>
    ...
Table 3. backend object fields
Name Description Required

name

An identifier for the 3scale backend, currently not referenced elsewhere.

Optional

upstream

The details about a network host to be contacted. This must refer to the 3scale Account Management API host, known, system.

Yes. The most important and required field.

The 3scale WebAssembly module services object

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.

apiVersion: maistra.io/v1
kind: ServiceMeshExtension
metadata:
  name: threescale-wasm-auth
spec:
  config:
    ...
    services:
    - id: "2555417834789"
      token: service_token
      authorities:
        - "*.app"
        - 0.0.0.0
        - "0.0.0.0:8443"
      credentials: <object>
      mapping_rules: <object>
    ...

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

Table 4. services object fields
Name Description Required

ID

An identifier for this 3scale service, currently not referenced elsewhere.

Yes

token

This token can be found in the proxy configuration for your service in System or you can retrieve the it from System with following curl command:

curl https://<system_host>/admin/api/services/<service_id>/proxy/configs/production/latest.json?access_token=<access_token>" | jq '.proxy_config.content.backend_authentication_value

Yes

authorities

An array of strings, each one representing the Authority of a URL to match. These strings accept glob patterns supporting the asterisk (*), plus sign (+), and question mark (?) matchers.

Yes

credentials

An object defining which kind of credentials to look for and where.

Yes

mapping_rules

An array of objects representing mapping rules and 3scale methods to hit.

Yes

The 3scale WebAssembly module credentials object

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.

apiVersion: maistra.io/v1
kind: ServiceMeshExtension
metadata:
  name: threescale-wasm-auth
spec:
  config:
    ...
    services:
    - credentials:
        user_key: <array_of_lookup_queries>
        app_id: <array_of_lookup_queries>
        app_key