Guide d'utilisation

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

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.

REMARQUE : Si vous êtes un utilisateur Apigee expérimenté, les étapes suivantes vous seront familières, car il s'agit de configurations Apigee standards. Toutefois, veuillez suivre attentivement ces instructions, car elles vous obligent à insérer des configurations spécifiques aux produits et applications de développement.

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 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 les champs de 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. Ne cliquez pas sur Enregistrer tant que vous n'y êtes pas invité.

Champ	Valeur
Nom	httpbin-product
Nom à afficher	httpbin product
Environment	your_environment Définissez cette valeur sur l'environnement que vous avez utilisé lors du provisionnement d'Apigee Adapter for Envoy avec apigee-remote-service-cli.
Accès	Private
Quota	5 requêtes toutes les minutes Consultez également la section À propos des produits API.

4. Dans la section Cibles de services distants Apigee, cliquez sur Ajouter une cible de service distant Apigee.
5. 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.
   proxy d'API	remote-service	Proxy remote-service qui a été provisionné sur Apigee lors de l'installation de Envoy Adapter.
   Chemin d'accès	Saisissez un /resource_path correspondant à un chemin spécifique. Par exemple, /httpbin.	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.

6. 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é.

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.

4. Ensuite, ajoutez deux produits à l'application :
   1. Tout d'abord, dans la section "Identifiants", cliquez sur + Ajouter un produit et sélectionnez le produit que vous venez de configurer : httpbin-product.
   2. Ajoutez ensuite le produit remote-service. Ce produit a été créé automatiquement lorsque vous avez provisionné Apigee.
5. Cliquez sur Créer.
6. Sous "Identifiants", cliquez sur Afficher à côté de la Clé.
7. 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. Cela signifie que les quotas ne sont pas précisés et risquent d'être surchargés si vous gérez plusieurs quotas à partir de plusieurs services distants. 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. Pour l'environnement hybride Apigee, vous pouvez utiliser cette commande pour créer un secret Kubernetes contenant le(s) jeton(s) JWT.

Aperçu

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 :

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-service/token -d '{"client_id":"myclientid","client_secret":"myclientsecret","grant_type":"client_credentials"}' -H "Content-type: application/json"

REMARQUE : L'en-tête Content-Type est obligatoire.

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 --http1.1 https://myorg-eval-test.apigee.net/remote-service/certs

REMARQUE : L'option --http1.1 est requise pour Apigee hybrid.

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

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

ou

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. Toutes les données de journalisation sont envoyées à stderr.

Élément	Obligatoire	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 :

• Journalisation des applications
• Journaux d'accès
• Stackdriver Logging avec GKE

Modifier le nom du secret de règle

Un secret Kubernetes déployé sur le cluster contient les identifiants dont l'adaptateur a besoin pour authentifier la communication avec le proxy du service distant. Ce secret requiert un point d'installation de volume, qui peut être configuré. Par défaut, le point d'installation est /policy-secret. Pour modifier le point d'installation, procédez comme suit :

1. Exécutez la commande suivante :

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/new-mount_point_name

   Exemple :

   $REMOTE_SERVICE_HOME/apigee-remote-service-envoy --policy-secret '/my-mount-point

2. Ouvrez $REMOTE_SERVICE_HOME/samples/istio/hybrid-apigee-remote-service-envoy.yaml dans un éditeur.
3. Remplacez le nom du point d'installation par le nouveau nom :

   volumeMounts:
     - mountPath: /config
       name: apigee-remote-service-envoy
       readOnly: true
     - mountPath: /opt/apigee/tls
       name: tls-volume
       readOnly: true
     - mountPath: /my-mount-point
       name: policy-secret
       readOnly: true

4. Enregistrez le fichier et appliquez-le au maillage de services :

   kubectl apply -f $REMOTE_SERVICE_HOME/samples/istio/hybrid-apigee-remote-service-envoy.yaml

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 :

• Interface d'administration
• Stats
• Statistiques du cluster

Analyses Istio

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

• Tâches d'observabilité
• Configuration de la télémétrie

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.