Cette page a été traduite par l'API Cloud Translation.

Guide d'utilisation

<ph type="x-smartling-placeholder"></ph> Vous consultez la documentation Apigee Edge.
Accédez à la page Documentation sur Apigee X. En savoir plus

Comment obtenir une clé API

L'exemple suivant explique comment obtenir une clé API que vous pouvez utiliser pour valider les appels d'API à un service cible envoyé par proxy via Apigee Adapter for Envoy.

1. Se connecter à Apigee

Ouvrez l'interface utilisateur Apigee dans un navigateur.
Une fois dans l'interface utilisateur, sélectionnez la même organisation que celle que vous avez utilisée pour configurer Apigee Adapter for Envoy.

2. Créer un développeur

Vous pouvez utiliser un développeur existant pour effectuer des tests ou en créer un autre en procédant comme suit :

Sélectionnez Publier > Développeurs dans le menu de navigation latéral.
Cliquez sur + Développeur.
Renseignez la boîte de dialogue pour créer un développeur. Vous pouvez utiliser le nom et l'adresse e-mail du développeur de votre choix.

3. Créer un produit d'API

Suivez l'exemple de création de produit fourni ci-dessous. Consultez également la section À propos de la configuration du produit d'API.

Dans le menu de navigation latéral, sélectionnez Publier > Produits API.
Cliquez sur + Produit API.
Renseignez la page d'informations détaillées sur le produit comme suit.

Champ	Valeur
Nom	`httpbin-product`
Nom à afficher	`httpbin product`
Environment	`your_environment` Définissez ce paramètre sur l'environnement que vous avez utilisé lors du provisionnement d'Apigee Adapter pour Envoy.
Accès	`Private`
Quota	5 requêtes toutes les minutes Voir aussi Quotas.

Dans la section Cibles de services distants Apigee, cliquez sur Ajouter une cible de service distant Apigee.

Dans la boîte de dialogue de cible de service distant Apigee, ajoutez les valeurs suivantes :

Attribut	Valeur	Description
Nom de la cible	Saisissez le nom du service cible. Par exemple : `httpbin.org`	Point de terminaison cible présenté par le proxy Envoy.
Chemin d'accès	Saisissez un chemin d'accès à une ressource sur le service à faire correspondre. Par exemple : `/headers`.	Chemin de la requête à mettre en correspondance avec le point de terminaison cible. Les appels de proxy d'API vers ce chemin correspondront à ce produit API.

Cliquez sur Enregistrer.

4. Créer une application de développeur

Sélectionnez Publier > Applications dans le menu de navigation latéral.
Cliquez sur + App (+ Application).
Renseignez la page "Application de développeur" comme suit. Ne procédez pas à l'enregistrement tant que vous n'y êtes pas invité.

Nom	`httpbin-app`
Nom à afficher	`httpbin app`
Développeur	Sélectionnez le développeur que vous avez créé précédemment ou sélectionnez un développeur de votre choix dans la liste.

Ajoutez ensuite le produit API à l'application: <ph type="x-smartling-placeholder">

Dans la section "Identifiants", cliquez sur + Ajouter un produit et sélectionnez le produit que vous venez de configurer : httpbin-product.
Cliquez sur Create (Créer).
Sous "Identifiants", cliquez sur Afficher à côté de la Clé.
Copiez la valeur de la clé client. Cette valeur est la clé API que vous utiliserez pour effectuer des appels d'API vers le service httpbin.

À propos des produits API

Les produits API constituent le point de contrôle principal du service distant Apigee. Lorsque vous créez un produit API et que vous l'associez à un service cible, vous créez une règle qui s'applique à toutes les requêtes que vous configurez pour être traitée par Apigee Adapter for Envoy.

Définition du produit API

Lorsque vous définissez un produit API dans Apigee, vous pouvez définir un certain nombre de paramètres qui serviront à évaluer les requêtes :

Cible
Chemin de requête
Quota
Champs d'application OAuth

Cibles de services distants

La définition de produit API s'applique à une requête si cette requête correspond à la fois à la liaison cible (par exemple, httpbin.org) et au chemin de la requête (par exemple, /httpbin). La liste des cibles potentielles est stockée en tant qu'attribut sur le produit API.

Par défaut, le service distant d'Apigee compare l'en-tête :authority (host) spécial d'Envoy à sa liste de cibles, mais vous pouvez le configurer pour utiliser d'autres en-têtes.

Chemin de ressource API

Le chemin saisi correspond aux règles suivantes :

La barre oblique (/) seule correspond à n'importe quel chemin.
La fonction * est valide n'importe où et correspond dans un segment (entre barres obliques).
La valeur ** est valide à la fin et correspond à tout élément à la fin de la ligne.

Quota

Un quota spécifie le nombre de messages de requêtes qu'une application est autorisée à envoyer à une API au cours d'une heure, d'une journée, d'une semaine ou d'un mois. Lorsqu'une application atteint sa limite de quota, les appels d'API suivants sont rejetés.

Cas d'utilisation des quotas

Les quotas vous permettent d'appliquer des contraintes au nombre de requêtes qu'un client peut envoyer à un service pendant une période donnée. Les quotas sont souvent utilisés pour appliquer des contrats d'entreprise ou des contrats de niveau de service vis-à-vis de développeurs et de partenaires, plutôt que pour la gestion du trafic opérationnel. Par exemple, un quota peut être utilisé pour limiter le trafic à un service gratuit, tout en autorisant l'accès complet aux clients payants.

Le quota est défini dans un produit API.

Les paramètres de quota sont configurés dans les produits API. Par exemple, lorsque vous créez un produit API, vous pouvez éventuellement définir la limite de quota, l'unité de temps et l'intervalle autorisés.

Étant donné que les clés API sont mappées aux produits API, chaque fois qu'une clé API est validée, le compteur de quota approprié peut être diminué (si un quota est défini dans le produit associé).

Contrairement à l'environnement d'exécution Apigee, les quotas saisis dans la définition du produit sont automatiquement appliqués par le service distant Apigee. Si la requête est autorisée, elle est comptabilisée dans le quota autorisé.

Emplacement de gestion des quotas

Les quotas sont maintenus et vérifiés localement par le processus du service distant, et maintenus de manière asynchrone avec l'environnement d'exécution Apigee. Les quotas ne sont donc pas précis et risquent certains dépassements si vous avez plusieurs services distants qui maintiennent le quota. Si la connexion à l'environnement d'exécution Apigee est interrompue, le quota local continue de faire office de quota autonome jusqu'à ce qu'il puisse se reconnecter à l'environnement d'exécution Apigee.

Champs d'application OAuth

Si vous utilisez des jetons JWT, vous pouvez limiter les jetons à des sous-ensembles des champs d'application OAuth autorisés. Les champs d'application attribués au jeton JWT émis seront comparés aux champs d'application du produit d'API.

À propos des applications de développeurs

Une fois vos produits API configurés, vous pouvez créer une application associée à un développeur. L'application permet à un client d'accéder aux produits API associés à l'aide d'une clé API ou d'un jeton JWT.

Utiliser l'authentification basée sur JWT

Vous pouvez utiliser un jeton JWT pour effectuer des appels de proxy d'API authentifiés au lieu d'utiliser une clé API. Cette section explique comment utiliser la commande apigee-remote-service-cli token pour créer, inspecter et faire pivoter des jetons JWT.

Présentation

La validation et l'authentification JWT sont gérées par Envoy à l'aide de son filtre d'authentification JWT.

Une fois authentifié, le filtre ext-authz Envoy envoie les en-têtes de requête et le jeton JWT à apigee-remote-service-envoy. Il associe les revendications api_product_list et scope du jeton JWT aux produits API Apigee pour les autoriser par rapport à la cible de la requête.

Créer des jetons JWT Apigee

Les jetons JWT Apigee peuvent être créés à l'aide de la CLI :

$CLI_HOME/apigee-remote-service-cli token create -c config.yaml --id $KEY --secret $SECRET

Ou en utilisant le point de terminaison de jeton OAuth standard. Exemple Curl :

curl https://org-env.apigee.net/remote-token/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

Utiliser le jeton JWT

Une fois que vous disposez du jeton, il vous suffit de le transmettre à Envoy dans l'en-tête d'autorisation. Exemple :

curl localhost:8080/httpbin/headers -i -H "Authorization:Bearer $TOKEN"

Échec du jeton JWT

Refus Envoy

Si Envoy refuse le jeton, un message de ce type peut s'afficher :

Jwks remote fetch is failed

Si tel est le cas, assurez-vous que votre configuration Envoy contient un URI valide dans la section remote_jwks, qu'il est accessible par Envoy et que vous avez correctement défini les certificats lorsque vous avez installé le proxy Apigee. Vous devez pouvoir appeler directement l'URI avec un appel GET et recevoir une réponse JSON valide.

Exemple :

curl https://myorg-eval-test.apigee.net/remote-service/certs

D'autres messages d'Envoy peuvent se présenter comme suit :

"Les audiences de Jwt ne sont pas autorisées"
"L'émetteur Jwt n'est pas configuré"

Ces messages proviennent des exigences de votre configuration Envoy, que vous devrez peut-être modifier.

Inspecter un jeton

Vous pouvez utiliser la CLI pour inspecter votre jeton. Exemple

$CLI_HOME/apigee-remote-service-cli -c config.yaml token inspect -f path/to/file

$CLI_HOME/apigee-remote-service-cli -c config.yaml token inspect <<< $TOKEN

Débogage

Consultez la section Échec d'une clé API valide.

Logging

Vous pouvez ajuster le niveau de journalisation sur le service $REMOTE_SERVICE_HOME/apigee-remote-service-envoy. Toute la journalisation est envoyée à stdout et stderr.

Élément	Valeur	Description
-l, --log-level	Niveaux valides : débogage, informations, avertissement, erreur.	Ajuste le niveau de journalisation. Valeur par défaut : info
-j, --json-log		Émet la sortie du journal sous forme d'enregistrements JSON.

Envoy comprend la journalisation. Pour en savoir plus, consultez la documentation Envoy aux liens suivants :

Utiliser un proxy réseau

Un proxy HTTP peut être inséré à l'aide des variables d'environnement HTTP_PROXY et HTTPS_PROXY dans l'environnement du binaire apigee-remote-service-envoy. Lorsque vous utilisez ces variables, la variable d'environnement NO_PROXY vous permet également d'empêcher l'envoi d'hôtes spécifiques via le proxy.

HTTP_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
HTTPS_PROXY=http://[user]:[pass]@[proxy_ip]:[proxy_port]
NO_PROXY=127.0.0.1,localhost

N'oubliez pas que le proxy doit être accessible à partir de apigee-remote-service-envoy.

À propos des métriques et des données d'analyse

Un point de terminaison de métriques Prometheus est disponible à l'adresse :5001/metrics. Vous pouvez configurer ce numéro de port. Consultez la section Fichier de configuration.

Analyses Envoy

Les liens suivants fournissent des informations sur l'obtention de données d'analyse de proxy Envoy :

Analyses Istio

Les liens suivants fournissent des informations sur l'obtention de données d'analyse de proxy Envoy :

Analyse Apigee

Apigee Remote Service for Envoy envoie des statistiques de requête à Apigee pour traitement. Apigee signale ces requêtes sous le nom de produit API associé.

Pour plus d'informations sur l'analyse Apigee, voir Présentation des services d'analyse.

Compatibilité avec les environnements mutualisés

Vous pouvez désormais activer l'adaptateur pour gérer plusieurs environnements au sein d'une organisation Apigee. Cette fonctionnalité vous permet d'utiliser une instance d'Apigee Adapter for Envoy associée à une organisation Apigee afin de gérer plusieurs environnements. Avant ce changement, un adaptateur était nécessaire pour chaque environnement Apigee.

Pour configurer la compatibilité avec plusieurs environnements, remplacez la valeur de tenant:env_name par * dans le fichier config.yaml. Exemple :

Ouvrez le fichier config.yaml dans un éditeur.

Remplacez la valeur de tenant.env_name par *. Exemple :

apiVersion: v1
kind: ConfigMap
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
data:
  config.yaml: |
    tenant:
      remote_service_api: https://myorg-myenv.apigee.net/remote-service
      org_name: apigee-docs-hybrid-a
      env_name: *
      allow_unverified_ssl_cert: true
    analytics:
      collection_interval: 10s
    auth:
      jwt_provider_key: https://myorg-myenv.apigee.net.net/remote-token/token

Enregistrez le fichier.
Appliquez le fichier :
```
kubectl apply -f $CLI_HOME/config.yaml
```

Lorsque vous configurez le mode multi-environnement, vous devez également configurer Envoy pour qu'il envoie une valeur d'environnement appropriée à l'adaptateur en ajoutant les métadonnées suivantes dans la section virtual_hosts:routes du fichier envoy-config.yaml. Exemple :

Générez le fichier envoy-config.yaml à l'aide de la CLI. Exemple :

$CLI_HOME/apigee-remote-service-cli samples create \
  -t envoy-1.16 -c ./config.yaml --out myconfigs

Ouvrez le fichier généré (appelé envoy-config.yaml).

Ajoutez les métadonnées suivantes dans la section virtual_host ou routes du fichier :

typed_per_filter_config:
  envoy.filters.http.ext_authz:
    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
    check_settings:
      context_extensions:
        apigee_environment: test

L'exemple suivant illustre la configuration d'un virtual_host avec plusieurs routes définies, où chaque route envoie le trafic vers un environnement spécifique :

filter_chains:
    - filters:
      - name: envoy.filters.network.http_connection_manager
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
          stat_prefix: ingress_http
          route_config:
            virtual_hosts:
            - name: default
              domains: "*"
              routes:
              - match: { prefix: /test }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: test
              - match: { prefix: /prod }
                route:
                  cluster: httpbin
                typed_per_filter_config:
                  envoy.filters.http.ext_authz:
                    "@type": type.googleapis.com/envoy.extensions.filters.http.ext_authz.v3.ExtAuthzPerRoute
                    check_settings:
                      context_extensions:
                         apigee_environment: prod

Répétez la dernière étape pour ajouter d'autres environnements si nécessaire.
Enregistrez le fichier et appliquez-le.
Remarque : Si env_name dans config.yaml est défini sur une valeur autre que *, l'adaptateur renvoie une erreur à Envoy, et la requête sera refusée si la configuration de l'adaptateur de env_name n'est pas définie sur * ou si la propriété env_name ne correspond pas aux métadonnées apigee_environment transmises.

Configurer mTLS entre l'adaptateur et l'environnement d'exécution Apigee

Pour utiliser l'authentification mTLS entre l'adaptateur et l'environnement d'exécution Apigee, vous pouvez fournir des certificats TLS côté client dans la section tenant du fichier config.yaml de l'adaptateur. Cette modification s'applique à toutes les plates-formes Apigee compatibles. Elle active également mTLS pour l'analytique sur Apigee Edge pour Cloud Platform. Exemple :

tenant:
  tls:
    ca_file: path/ca.pem
    cert_file: path/cert.pem
    key_file: path/key.pem
    allow_unverified_ssl_cert: false