1.20. Utilisation du module WebAssembly de 3scale

Service Mesh fournit une définition de ressource personnalisée pour spécifier et appliquer les extensions Proxy-WASM aux mandataires sidecar, connus sous le nom de WasmPlugin. Service Mesh applique cette ressource personnalisée à l'ensemble des charges de travail qui nécessitent une gestion de l'API HTTP avec 3scale.

Pour plus d'informations, voir la définition des ressources personnalisées.

L'architecture de la configuration du module WebAssembly de 3scale dépend du service de compte et d'autorisation de 3scale et de la liste des services à gérer.

La chaîne de niveau supérieur api du module 3scale WebAssembly définit la version de la configuration que le module utilisera.

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
  namespace: <info>
spec:
  pluginConfig:
    api: v1
...

L'entrée api définit le reste des valeurs de la configuration. La seule valeur acceptée est v1. Les nouveaux paramètres qui rompent la compatibilité avec la configuration actuelle ou qui nécessitent plus de logique que les modules utilisant v1 ne peuvent pas gérer, nécessiteront des valeurs différentes.

L'objet de premier niveau system spécifie comment accéder à l'API de gestion de compte 3scale pour un compte spécifique. Le champ upstream est la partie la plus importante de l'objet. L'objet system est facultatif, mais recommandé à moins que vous ne fournissiez une configuration entièrement statique pour le module 3scale WebAssembly, ce qui est une option si vous ne voulez pas fournir de connectivité au composant system de 3scale.

Lorsque vous fournissez des objets de configuration statiques en plus de l'objet system, les objets statiques sont toujours prioritaires.

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    system:
      name: <saas_porta>
      upstream: <object>
      token: <my_account_token>
      ttl: 300
  ...

L'objet upstream décrit un hôte externe vers lequel le proxy peut effectuer des appels.

apiVersion: maistra.io/v1
upstream:
  name: outbound|443||multitenant.3scale.net
  url: "https://myaccount-admin.3scale.net/"
  timeout: 5000
...

L'objet de premier niveau backend spécifie comment accéder à l'API de gestion des services 3scale pour autoriser et signaler les requêtes HTTP. Ce service est fourni par le composant Backend de 3scale.

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    backend:
      name: backend
      upstream: <object>
    ...

L'objet de premier niveau services spécifie quels identificateurs de service sont traités par cette instance particulière de module.

Étant donné que les comptes disposent de plusieurs services, vous devez spécifier ceux qui sont gérés. Le reste de la configuration porte sur la manière de configurer les services.

Le champ services est obligatoire. Il s'agit d'un tableau qui doit contenir au moins un service pour être utile.

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    services:
    - id: "2555417834789"
      token: service_token
      authorities:
        - "*.app"
        - 0.0.0.0
        - "0.0.0.0:8443"
      credentials: <object>
      mapping_rules: <object>
    ...

Chaque élément du tableau services représente un service à 3 échelles.

L'objet credentials est un composant de l'objet service. credentials spécifie le type d'informations d'identification à rechercher et les étapes à suivre pour réaliser cette action.

Tous les champs sont facultatifs, mais vous devez en spécifier au moins un, user_key ou app_id. L'ordre dans lequel vous spécifiez chaque justificatif n'a pas d'importance car il est préétabli par le module. N'indiquez qu'une seule instance de chaque justificatif.

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    services:
    - credentials:
        user_key: <array_of_lookup_queries>
        app_id: <array_of_lookup_queries>
        app_key: <array_of_lookup_queries>
    ...

L'objet lookup query fait partie de n'importe quel champ de l'objet credentials. Il spécifie comment un champ d'identification donné doit être trouvé et traité. Lorsqu'elle est évaluée, une résolution réussie signifie qu'une ou plusieurs valeurs ont été trouvées. Une résolution échouée signifie qu'aucune valeur n'a été trouvée.

Les tableaux de lookup queries décrivent un court-circuit ou une relation : la résolution réussie de l'une des requêtes arrête l'évaluation de toutes les requêtes restantes et attribue la ou les valeurs au type de justificatif spécifié. Chaque requête du tableau est indépendante des autres.

Un site lookup query est constitué d'un seul champ, un objet source, qui peut faire partie d'un certain nombre de types de sources. Voir l'exemple suivant :

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    services:
    - credentials:
        user_key:
          - <source_type>: <object>
          - <source_type>: <object>
          ...
        app_id:
          - <source_type>: <object>
          ...
        app_key:
          - <source_type>: <object>
          ...
    ...

Un objet source existe en tant que partie d'un tableau de sources dans n'importe quel champ de l'objet credentials. Le nom du champ de l'objet, appelé source-type, est l'un des suivants :

Tous les objets de type source possèdent au moins les deux champs suivants :

Le nom du champ filter comporte une entrée obligatoire path pour indiquer le chemin dans les métadonnées que vous utilisez pour rechercher des données.

Lorsqu'un key correspond aux données d'entrée, les autres clés ne sont pas évaluées et l'algorithme de résolution des sources passe à l'exécution du operations (ops) spécifié, le cas échéant. Si aucun ops n'est spécifié, la valeur de résultat du key correspondant, s'il y en a un, est renvoyée.

Operations fournissent un moyen de spécifier certaines conditions et transformations pour les entrées dont vous disposez après que la première phase a consulté un site key. Utilisez operations lorsque vous avez besoin de transformer, décoder et affirmer des propriétés, mais ils ne fournissent pas un langage mature pour répondre à tous les besoins et manquent de Turing-completeness.

Une pile stocke les résultats de operations. Lorsqu'il est évalué, lookup query termine en attribuant la ou les valeurs au bas de la pile, en fonction du nombre de valeurs consommées par le titre.

Chaque élément du tableau ops appartenant à un source type spécifique est un objet operation qui applique des transformations aux valeurs ou effectue des tests. Le nom du champ à utiliser pour un tel objet est le nom de l'objet operation lui-même, et toutes les valeurs sont les paramètres de l'objet operation, qui peuvent être des objets de structure, par exemple des cartes avec des champs et des valeurs, des listes ou des chaînes de caractères.

La plupart des sites operations traitent une ou plusieurs entrées et produisent une ou plusieurs sorties. Lorsqu'elles consomment des entrées ou produisent des sorties, elles travaillent avec une pile de valeurs : chaque valeur consommée par les opérations est extraite de la pile de valeurs et initialement remplie avec toutes les correspondances source. Les valeurs produites par les opérations sont poussées vers la pile. Les valeurs produites par ces opérations sont poussées vers la pile. D'autres sites operations ne consomment ni ne produisent de résultats autres que l'affirmation de certaines propriétés, mais ils inspectent une pile de valeurs.

Il existe plusieurs catégories de operations:

Toutes les opérations sont spécifiées par les identificateurs de nom sous forme de chaînes de caractères.

L'objet mapping_rules fait partie de l'objet service. Il spécifie un ensemble de modèles de chemins REST, de métriques 3scale et d'incréments de comptage à utiliser lorsque les modèles correspondent.

Vous avez besoin de cette valeur si aucune configuration dynamique n'est fournie dans l'objet de premier niveau system. Si l'objet est fourni en plus de l'entrée de premier niveau system, l'objet mapping_rules est évalué en premier.

mapping_rules est un objet de type tableau. Chaque élément de ce tableau est un objet mapping_rule. Les règles de correspondance évaluées sur une demande entrante fournissent l'ensemble de 3scale methods pour l'autorisation et le rapport à APIManager. Lorsque plusieurs règles de correspondance se réfèrent au même methods, il y a une addition de deltas lors de l'appel à 3scale. Par exemple, si deux règles augmentent deux fois la méthode Hits avec deltas de 1 et 3, une seule entrée de méthode pour les Hits faisant rapport à 3scale a une delta de 4.

L'objet mapping_rule fait partie d'un tableau dans l'objet mapping_rules.

Les champs de l'objet mapping_rule précisent les informations suivantes :

L'exemple suivant est indépendant des hiérarchies existantes entre les méthodes dans 3scale. En d'autres termes, tout ce qui est exécuté du côté de 3scale n'affectera pas cet exemple. Par exemple, la métrique Hits peut être le parent de toutes les méthodes, elle stocke donc 4 occurrences en raison de la somme de toutes les méthodes signalées dans la demande autorisée et appelle le point de terminaison de l'API 3scale Authrep.

L'exemple ci-dessous utilise une requête GET vers un chemin d'accès, /products/1/sold, qui répond à toutes les règles.

apiVersion: extensions.istio.io/v1alpha1
kind: WasmPlugin
metadata:
  name: <threescale_wasm_plugin_name>
spec:
  pluginConfig:
    ...
    mapping_rules:
      - method: GET
        pattern: /
        usages:
          - name: hits
            delta: 1
      - method: GET
        pattern: /products/
        usages:
          - name: products
            delta: 1
      - method: ANY
        pattern: /products/{id}/sold
        usages:
          - name: sales
            delta: 1
          - name: products
            delta: 1
    ...

Toutes les adresses usages sont ajoutées à la requête que le module adresse à 3scale avec les données d'utilisation comme suit :

L'exemple suivant recherche une adresse user_key dans un paramètre de chaîne de requête ou un en-tête du même nom :

credentials:
  user_key:
    - query_string:
        keys:
          - user_key
    - header:
        keys:
          - user_key

L'exemple suivant permet de rechercher les informations d'identification app_key et app_id dans une requête ou des en-têtes.

credentials:
  app_id:
    - header:
        keys:
          - app_id
    - query_string:
        keys:
          - app_id
  app_key:
    - header:
        keys:
          - app_key
    - query_string:
        keys:
          - app_key

Une requête comprend un en-tête app_id et app_key dans un en-tête authorization. S'il y a au moins une ou deux valeurs produites à la fin, alors vous pouvez assigner l'en-tête app_key.

La résolution ici attribue le app_key s'il y a un ou deux résultats à la fin.

L'en-tête authorization spécifie une valeur avec le type d'autorisation et sa valeur est encodée comme Base64. Cela signifie que vous pouvez diviser la valeur par un caractère espace, prendre la deuxième sortie et la diviser à nouveau en utilisant un deux-points ( :) comme séparateur. Par exemple, si vous utilisez le format app_id:app_key, l'en-tête ressemble à l'exemple suivant pour credential:

aladdin:opensesame:  Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l

Vous devez utiliser des noms de champs d'en-tête en minuscules, comme indiqué dans l'exemple suivant :

credentials:
  app_id:
    - header:
        keys:
          - authorization
        ops:
          - split:
              separator: " "
              max: 2
          - length:
              min: 2
          - drop:
              head: 1
          - base64_urlsafe
          - split:
              max: 2
  app_key:
    - header:
        keys:
          - app_key

L'exemple de cas d'utilisation précédent porte sur les en-têtes d'un site authorization:

La dernière opération, assert, indique qu'aucun effet secondaire ne se retrouve dans la pile. Vous pouvez alors modifier la pile :

Pour Service Mesh et l'adaptateur Istio 3scale, vous devez déployer un site RequestAuthentication comme indiqué dans l'exemple suivant, en renseignant vos propres données de charge de travail et jwtRules:

apiVersion: security.istio.io/v1beta1
kind: RequestAuthentication
metadata:
  name: jwt-example
  namespace: info
spec:
  selector:
    matchLabels:
      app: productpage
  jwtRules:
  - issuer: >-
      http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak
    jwksUri: >-
      http://keycloak-keycloak.34.242.107.254.nip.io/auth/realms/3scale-keycloak/protocol/openid-connect/certs

Lorsque vous appliquez le RequestAuthentication, il configure Envoy avec un plugin natif pour valider les jetons JWT. Le proxy valide tout avant d'exécuter le module, de sorte que les demandes qui échouent ne parviennent pas au module 3scale WebAssembly.

Lorsqu'un jeton JWT est validé, le proxy stocke son contenu dans un objet de métadonnées interne, avec une entrée dont la clé dépend de la configuration spécifique du plugin. Ce cas d'utilisation vous permet de rechercher des objets de structure avec une seule entrée contenant un nom de clé inconnu.

Le 3scale app_id pour l'OIDC correspond à l'OAuth client_id. Ceci se trouve dans les champs azp ou aud des jetons JWT.

Pour obtenir le champ app_id à partir du filtre d'authentification natif d'Envoy JWT, voir l'exemple suivant :

credentials:
  app_id:
    - filter:
        path:
          - envoy.filters.http.jwt_authn
          - "0"
        keys:
          - azp
          - aud
        ops:
          - take:
              head: 1

L'exemple indique au module d'utiliser le type de source filter pour rechercher les métadonnées de filtrage d'un objet provenant du plugin natif d'authentification JWT spécifique à Envoy. Ce plugin inclut le jeton JWT dans un objet de structure avec une seule entrée et un nom préconfiguré. Utilisez 0 pour spécifier que vous n'accéderez qu'à l'entrée unique.

La valeur résultante est une structure pour laquelle vous résoudrez deux champs :

Cette opération permet de s'assurer qu'une seule valeur est conservée pour l'affectation.

Certaines configurations peuvent avoir des processus de validation pour les jetons JWT où le jeton validé atteindrait ce module par le biais d'un en-tête au format JSON.

Pour obtenir le site app_id, voir l'exemple suivant :

credentials:
  app_id:
    - header:
        keys:
          - x-jwt-payload
        ops:
          - base64_urlsafe
          - json:
            - keys:
              - azp
              - aud
          - take:
              head: 1