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.

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 +Create (Créer).
  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 "Attributs personnalisés", cliquez sur + AJOUTER UN ATTRIBUT PERSONNALISÉ.
  5. Saisissez cette paire nom/valeur :
    • Nom : saisissez le nom de cet attribut : apigee-remote-service-targets
    • Valeur : saisissez le nom du service cible. Par exemple : httpbin.org
  6. Cliquez sur OK.
  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.
  4. Dans la section "Identifiants", cliquez sur + Ajouter un produit et sélectionnez le produit que vous venez de configurer : httpbin-product.
  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.

Définition d'une limite de quota dans l'interface utilisateur d'Apigee.>

É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"

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

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 :

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 $CLI_HOME/samples/apigee-envoy-adapter.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/apigee-envoy-adapter.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 :

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.