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

  1. Ouvrez l'interface utilisateur Apigee dans un navigateur.
  2. 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 :

  1. Sélectionnez Publier > Développeurs dans le menu de navigation latéral.
  2. Cliquez sur + Développeur.
  3. 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.

  1. Dans le menu de navigation latéral, sélectionnez Publier > Produits API.
  2. Cliquez sur + Produit API.
  3. Renseignez la page d'informations détaillées sur le produit comme suit.
  4. 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.

  5. Dans la section Cibles de services distants Apigee, cliquez sur Ajouter une cible de service distant Apigee.
  6. 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.
  7. Cliquez sur Enregistrer.

4. Créer une application de développeur

  1. Sélectionnez Publier > Applications dans le menu de navigation latéral.
  2. Cliquez sur + App (+ Application).
  3. Renseignez la page "Application de développeur" comme suit. Ne procédez pas à l'enregistrement tant que vous n'y êtes pas invité.
  4. 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.
  5. Ajoutez ensuite le produit API à l'application: <ph type="x-smartling-placeholder">
      </ph>
    1. Dans la section "Identifiants", cliquez sur + Ajouter un produit et sélectionnez le produit que vous venez de configurer : httpbin-product.
    2. Cliquez sur Create (Créer).
    3. Sous "Identifiants", cliquez sur Afficher à côté de la Clé.
    4. 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

    ou

    $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 :

    1. Ouvrez le fichier config.yaml dans un éditeur.
    2. 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
    3. Enregistrez le fichier.
    4. 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 :

    1. 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
    2. Ouvrez le fichier généré (appelé envoy-config.yaml).
    3. 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
    4. Répétez la dernière étape pour ajouter d'autres environnements si nécessaire.
    5. Enregistrez le fichier et appliquez-le.

    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