Documentation de référence sur l'opération et la configuration d'Edge Micropasser

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

Edge Microgateway v. 2.5.x

Cet article explique comment gérer et configurer Edge Microgateway.

Mettre à niveau Edge Microgateway si vous disposez d'une connexion Internet

1. Exécutez la commande npm suivante pour passer à la dernière version d'Edge Microgateway :

   npm upgrade edgemicro -g

   Pour passer à une version spécifique d'Edge Microgateway, vous devez spécifier le numéro de version dans la commande de mise à niveau. Si vous ne spécifiez pas le numéro de version, la dernière version sera installée. Par exemple, pour passer à la version 2.5.26, utilisez la commande suivante :

   npm upgrade edgemicro@2.5.26 -g

2. Vérifiez le numéro de version. Par exemple, si vous avez installé la version 2.5.26 :

   edgemicro --version
   current nodejs version is v8.9.0
   current edgemicro version is 2.5.26
       

3. Enfin, passez à la dernière version du proxy edgemicro-auth :

   edgemicro upgradeauth -o org_name -e env_name -u username

Modifier la configuration

Voici les fichiers de configuration que vous devez connaître :

• Fichier de configuration système par défaut
• Fichier de configuration par défaut pour une instance Edge Microgateway nouvellement initialisée
• Fichier de configuration dynamique pour les instances en cours d'exécution

Cette section traite de ces fichiers et de ce que vous devez savoir pour les modifier.

Fichier de configuration système par défaut

Lorsque vous installez Edge Microgateway, un fichier de configuration système par défaut est placé ici :

prefix/lib/node_modules/edgemicro/config/default.yaml

Où prefix est le répertoire du préfixe npm. Si vous ne trouvez pas ce répertoire, consultez Où Edge Microgateway est-il installé ?.

Si vous modifiez le fichier de configuration du système, vous devez réinitialiser, reconfigurer et redémarrer Edge Microgateway :

edgemicro init
edgemicro configure [params]
edgemicro start [params]

Fichier de configuration par défaut pour les instances Edge Microgateway nouvellement initialisées

Lorsque vous exécutez edgemicro init, le fichier de configuration système (décrit ci-dessus), default.yaml, est placé dans le répertoire ~/.edgemicro.

Si vous modifiez le fichier de configuration dans ~/.edgemicro, vous devez reconfigurer et redémarrer Edge Microgateway :

edgemicro stop
edgemicro configure [params]
edgemicro start [params]

Fichier de configuration dynamique pour les instances en cours d'exécution

Lorsque vous exécutez edgemicro configure [params], un fichier de configuration dynamique est créé dans ~/.edgemicro. Le fichier est nommé selon le modèle suivant : org-env-config.yaml, où org et env sont les noms de votre organisation et de votre environnement Apigee Edge. Vous pouvez utiliser ce fichier pour modifier la configuration, puis la recharger sans temps d'arrêt. Par exemple, si vous ajoutez et configurez un plug-in, vous pouvez actualiser la configuration sans temps d'arrêt, comme expliqué ci-dessous.

Si Edge Microgateway est en cours d'exécution (option sans temps d'arrêt) :

1. Rechargez la configuration d'Edge Microgateway :

   edgemicro reload -o org_name -e env_name -k key -s secret

   Où :

   • org_name est le nom de votre organisation Edge (vous devez être un administrateur de l'organisation).
   • env_name est un environnement de votre organisation (par exemple, "test" ou "prod").
   • key est la clé renvoyée précédemment par la commande de configuration.
   • secret est la clé renvoyée précédemment par la commande de configuration.

   Exemple

   edgemicro reload -o docs -e test -k 701e70ee718ce6dc188...78b6181d000723 \
     -s 05c14356e42ed1...4e34ab0cc824

Si Edge Microgateway est arrêté :

1. Redémarrez Edge Microgateway :

   edgemicro start -o org_name -e env_name -k key -s secret

   Où :

   • org_name est le nom de votre organisation Edge (vous devez être un administrateur de l'organisation).
   • env_name est un environnement de votre organisation (par exemple, "test" ou "prod").
   • key est la clé renvoyée précédemment par la commande de configuration.
   • secret est la clé renvoyée précédemment par la commande de configuration.

   Exemple :

   edgemicro start -o docs -e test -k 701e70ee718ce...b6181d000723 \
     -s 05c1435...e34ab0cc824

Voici un exemple de fichier de configuration. Pour en savoir plus sur les paramètres du fichier de configuration, consultez la documentation de référence sur la configuration d'Edge Microgateway.

edge_config:
  bootstrap: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/bootstrap/organization/docs/environment/test
  jwt_public_key: 'https://docs-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://docs-test.apigee.net/edgemicro-auth/products'
edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
headers:
  x-forwarded-for: true
  x-forwarded-host: true
  x-request-id: true
  x-response-time: true
  via: true
oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  verify_api_key_url: 'https://docs-test.apigee.net/edgemicro-auth/verifyApiKey'
analytics:
  uri: >-
    https://edgemicroservices-us-east-1.apigee.net/edgemicro/axpublisher/organization/docs/environment/test

Définir des variables d'environnement

Les commandes de l'interface de ligne de commande qui nécessitent des valeurs pour votre organisation et votre environnement Edge, ainsi que la clé et le secret nécessaires au démarrage d'Edge Microgateway, peuvent être stockées dans ces variables d'environnement :

• EDGEMICRO_ORG
• EDGEMICRO_ENV
• EDGEMICRO_KEY
• EDGEMICRO_SECRET

La définition de ces variables est facultative. Si vous les définissez, vous n'avez pas besoin de spécifier leurs valeurs lorsque vous utilisez l'interface de ligne de commande (CLI) pour configurer et démarrer Edge Microgateway.

Configurer SSL sur le serveur Edge Microgateway

Vous pouvez configurer le serveur Microgateway pour qu'il utilise SSL. Par exemple, lorsque SSL est configuré, vous pouvez appeler des API via Edge Microgateway avec le protocole "https", comme suit :

https://localhost:8000/myapi

Pour configurer SSL sur le serveur Microgateway, procédez comme suit :

1. Générez ou obtenez un certificat SSL et une clé à l'aide de l'utilitaire openssl ou de la méthode de votre choix.
2. Ajoutez l'attribut edgemicro:ssl au fichier de configuration Edge Microgateway. Pour obtenir la liste complète des options, consultez le tableau ci-dessous. Exemple :
   

   edgemicro:
     ssl:
      key: <absolute path to the SSL key file>
      cert: <absolute path to the SSL cert file>
      passphrase: admin123 #option added in v2.2.2
      rejectUnauthorized: true #option added in v2.2.2
      requestCert: true

3. Redémarrez Edge Microgateway. Suivez les étapes décrites dans Apporter des modifications de configuration en fonction du fichier de configuration que vous avez modifié : le fichier par défaut ou le fichier de configuration de l'environnement d'exécution.

Voici un exemple de la section edgemicro du fichier de configuration, avec SSL configuré :

edgemicro:
  port: 8000
  max_connections: 1000
  max_connections_hard: 5000
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24
  plugins:
    sequence:
      - oauth
  ssl:
    key: /MyHome/SSL/em-ssl-keys/server.key
    cert: /MyHome/SSL/em-ssl-keys/server.crt
    passphrase: admin123 #option added in v2.2.2
    rejectUnauthorized: true #option added in v2.2.2

Voici la liste de toutes les options de serveur compatibles :

Utiliser les options SSL/TLS du client

Vous pouvez configurer Edge Microgateway pour qu'il agisse en tant que client TLS ou SSL lors de la connexion aux points de terminaison cibles. Dans le fichier de configuration de Microgateway, utilisez l'élément targets pour définir les options SSL/TLS.

Cet exemple fournit des paramètres qui seront appliqués à tous les hôtes :

edgemicro:
...
targets:
  ssl:
    client:
      key: /Users/jdoe/nodecellar/twowayssl/ssl/client.key
      cert: /Users/jdoe/nodecellar/twowayssl/ssl/ca.crt
      passphrase: admin123
      rejectUnauthorized: true

Dans cet exemple, les paramètres ne sont appliqués qu'à l'hôte spécifié :

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    ssl:
      client:
        key: /Users/myname/twowayssl/ssl/client.key
        cert: /Users/myname/twowayssl/ssl/ca.crt
        passphrase: admin123
        rejectUnauthorized: true

Voici un exemple pour TLS :

edgemicro:
...
targets:
  - host: 'myserver.example.com'
    tls:
      client:
        pfx: /Users/myname/twowayssl/ssl/client.pfx
        passphrase: admin123
        rejectUnauthorized: true

Voici la liste de toutes les options client compatibles :

Personnaliser le proxy edgemicro-auth

Par défaut, Edge Microgateway utilise un proxy déployé sur Apigee Edge pour l'authentification OAuth2. Ce proxy est déployé lorsque vous exécutez edgemicro configure pour la première fois. Vous pouvez modifier la configuration par défaut de ce proxy pour ajouter la prise en charge des revendications personnalisées à un jeton Web JSON (JWT), configurer l'expiration des jetons et générer des jetons d'actualisation. Pour en savoir plus, consultez la page edgemicro-auth sur GitHub.

Utiliser un service d'authentification personnalisé

Par défaut, Edge Microgateway utilise un proxy déployé sur Apigee Edge pour l'authentification OAuth2. Ce proxy est déployé lorsque vous exécutez edgemicro configure pour la première fois. Par défaut, l'URL de ce proxy est spécifiée dans le fichier de configuration d'Edge Microgateway comme suit :

authUri: https://myorg-myenv.apigee.net/edgemicro-auth

Si vous souhaitez utiliser votre propre service personnalisé pour gérer l'authentification, modifiez la valeur authUri dans le fichier de configuration pour qu'elle pointe vers votre service. Par exemple, vous pouvez avoir un service qui utilise LDAP pour valider l'identité.

Gérer les fichiers journaux

Edge Microgateway consigne des informations sur chaque requête et réponse. Les fichiers journaux fournissent des informations utiles pour le débogage et le dépannage.

Emplacement de stockage des fichiers journaux

Par défaut, les fichiers journaux sont stockés dans /var/tmp.

Modifier le répertoire des fichiers journaux par défaut

Le répertoire dans lequel les fichiers journaux sont stockés est spécifié dans le fichier de configuration d'Edge Microgateway. Consultez également Modifier la configuration.

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Modifiez la valeur dir pour spécifier un autre répertoire de fichiers journaux.

Envoyer les journaux à la console

Vous pouvez configurer la journalisation de sorte que les informations de journal soient envoyées vers la sortie standard plutôt que vers un fichier journal. Définissez l'option to_console sur "true" comme suit :

edgemicro:
  logging:
    to_console: true

Avec ce paramètre, les journaux seront envoyés vers la sortie standard. Pour le moment, vous ne pouvez pas envoyer de journaux à la fois vers stdout et vers un fichier journal.

Définir le niveau de journalisation

Vous pouvez définir les niveaux de journalisation suivants : info, warn et error. Le niveau d'information est recommandé. Il consigne toutes les requêtes et réponses d'API. Il s'agit de l'option par défaut.

Modifier les intervalles de journalisation

Vous pouvez configurer ces intervalles dans le fichier de configuration d'Edge Microgateway. Consultez également Modifier la configuration.

Les attributs configurables sont les suivants :

• stats_log_interval : (par défaut : 60) intervalle, en secondes, entre l'écriture de l'enregistrement de statistiques dans le fichier journal de l'API.
• rotate_interval (par défaut : 24) : intervalle, en heures, entre les rotations des fichiers journaux. Exemple :

edgemicro:
  home: ../gateway
  port: 8000
  max_connections: -1
  max_connections_hard: -1
  logging:
    level: info
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Bonnes pratiques de maintenance des fichiers journaux

À mesure que les données des fichiers journaux s'accumulent au fil du temps, Apigee vous recommande d'adopter les pratiques suivantes :

• Les fichiers journaux pouvant devenir assez volumineux, assurez-vous que le répertoire des fichiers journaux dispose d'un espace suffisant. Consultez les sections Où sont stockés les fichiers journaux et Comment modifier le répertoire par défaut des fichiers journaux.
• Supprimez ou déplacez les fichiers journaux vers un répertoire d'archive distinct au moins une fois par semaine.
• Si votre règle consiste à supprimer les journaux, vous pouvez utiliser la commande CLI edgemicro log -c pour supprimer (nettoyer) les anciens journaux.

Convention d'attribution de noms aux fichiers journaux

Chaque instance Edge Microgateway produit trois types de fichiers journaux :

• api : consigne toutes les requêtes et réponses qui transitent par Edge Microgateway. Les compteurs d'API (statistiques) et les erreurs sont également consignés dans ce fichier.
• err : consigne tout ce qui est envoyé à stderr.
• out : consigne tout ce qui est envoyé à stdout.

Voici la convention d'attribution de noms :

edgemicro-<Host Name>-<Instance ID>-<Log Type>.log

Exemple :

edgemicro-mymachine-local-MTQzNTgNDMxODAyMQ-api.log
edgemicro-mymachine-local-MTQzNTg1NDMODAyMQ-err.log
edgemicro-mymachine-local-mtqzntgndmxodaymq-out.log

À propos du contenu des fichiers journaux

Ajouté dans la version 2.3.3

Par défaut, le service de journalisation omet le JSON des proxys et produits téléchargés, ainsi que le jeton Web JSON (JWT). Si vous souhaitez générer ces objets dans les fichiers journaux, définissez DEBUG=* lorsque vous démarrez Edge Microgateway. Exemple :

DEBUG=* edgemicro start -o docs -e test -k abc123 -s xyz456

Contenu du fichier journal "api"

Le fichier journal "api" contient des informations détaillées sur le flux de requêtes et de réponses via Edge Microgateway. Les fichiers journaux "api" sont nommés comme suit :

edgemicro-mymachine-local-MTQzNjIxOTk0NzY0Nw-api.log

Pour chaque requête envoyée à Edge Microgateway, quatre événements sont capturés dans le fichier journal "api" :

• Requête entrante du client
• Requête sortante envoyée à la cible
• Réponse entrante de la cible
• Réponse sortante au client

Chacune de ces entrées distinctes est représentée par une notation abrégée pour rendre les fichiers journaux plus compacts. Voici quatre exemples d'entrées représentant chacun des quatre événements. Dans le fichier journal, elles se présentent comme suit (les numéros de ligne sont fournis à titre indicatif uniquement et n'apparaissent pas dans le fichier journal).

(1) 1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0
(2) 1436403888665 info treq m=GET, u=/, h=127.0.0.18080, i=0
(3) 1436403888672 info tres s=200, d=7, i=0
(4) 1436403888676 info res s=200, d=11, i=0

Examinons-les un par un :

1. Exemple de requête entrante du client :

1436403888651 info req m=GET, u=/, h=localhost:8000, r=::1:59715, i=0

• 1436403888651 : date Unix
• info : dépend du contexte. Peut être "info", "warn" ou "error", selon le niveau de journalisation. Il peut s'agir de "stats" pour un enregistrement de statistiques, de "warn" pour les avertissements ou de "error" pour les erreurs.
• req : identifie l'événement. Dans ce cas, demandez-le au client.
• m : verbe HTTP utilisé dans la requête.
• u : partie de l'URL qui suit le chemin de base.
• h : hôte et numéro de port sur lesquels Edge Microgateway écoute.
• r : hôte et port distants d'où provient la requête du client.
• i : ID de la requête. Les quatre entrées d'événement partageront cet ID. Chaque requête se voit attribuer un ID de requête unique. La corrélation des enregistrements de journaux par ID de requête peut fournir des informations précieuses sur la latence de la cible.
• d : durée en millisecondes depuis la réception de la requête par Edge Microgateway. Dans l'exemple ci-dessus, la réponse de la cible à la requête 0 a été reçue après 7 millisecondes (ligne 3), et la réponse a été envoyée au client après 4 millisecondes supplémentaires (ligne 4). En d'autres termes, la latence totale de la requête était de 11 millisecondes, dont 7 millisecondes ont été prises par la cible et 4 millisecondes par Edge Microgateway lui-même.

2. Exemple de requête sortante envoyée à la cible :

1436403888665 info treq m=GET, u=/, h=127.0.0.1:8080, i=0

• 1436403888651 : date Unix
• info : dépend du contexte. Peut être "info", "warn" ou "error", selon le niveau de journalisation. Il peut s'agir de "stats" pour un enregistrement de statistiques, de "warn" pour les avertissements ou de "error" pour les erreurs.
• treq : identifie l'événement. Dans ce cas, la requête cible.
• m : verbe HTTP utilisé dans la requête cible.
• u : partie de l'URL qui suit le chemin de base.
• h : hôte et numéro de port de la cible backend.
• i : ID de l'entrée de journal. Les quatre entrées d'événement partageront cet ID.

3. Exemple de réponse entrante de la cible

1436403888672 info tres s=200, d=7, i=0

1436403888651 : date Unix

• info : dépend du contexte. Peut être "info", "warn" ou "error", selon le niveau de journalisation. Il peut s'agir de "stats" pour un enregistrement de statistiques, de "warn" pour les avertissements ou de "error" pour les erreurs.
• tres : identifie l'événement. Dans ce cas, la réponse cible.
• s : état de la réponse HTTP.
• d : durée en millisecondes. Temps nécessaire à l'appel d'API par la cible.
• i : ID de l'entrée de journal. Les quatre entrées d'événement partageront cet ID.

4. Exemple de réponse sortante au client

1436403888676 info res s=200, d=11, i=0

1436403888651 : date Unix

• info : dépend du contexte. Peut être "info", "warn" ou "error", selon le niveau de journalisation. Il peut s'agir de "stats" pour un enregistrement de statistiques, de "warn" pour les avertissements ou de "error" pour les erreurs.
• res : identifie l'événement. Dans ce cas, la réponse au client.
• s : état de la réponse HTTP.
• d : durée en millisecondes. Il s'agit du temps total pris par l'appel d'API, y compris le temps pris par l'API cible et le temps pris par Edge Microgateway lui-même.
• i : ID de l'entrée de journal. Les quatre entrées d'événement partageront cet ID.

Planification du fichier journal

La rotation des fichiers journaux est effectuée à l'intervalle spécifié par l'attribut de configuration rotate_interval. Les entrées continueront d'être ajoutées au même fichier journal jusqu'à l'expiration de l'intervalle de rotation. Cependant, chaque fois qu'Edge Microgateway est redémarré, il reçoit un nouvel UID et crée un nouvel ensemble de fichiers journaux avec cet UID. Consultez également Bonnes pratiques de maintenance des fichiers journaux.

Messages d'erreur

Certaines entrées de journal contiennent des messages d'erreur. Pour identifier où et pourquoi les erreurs se produisent, consultez la documentation de référence sur les erreurs Edge Microgateway.

Documentation de référence sur la configuration d'Edge Microgateway

Emplacement du fichier de configuration

Les attributs de configuration décrits dans cette section se trouvent dans le fichier de configuration Edge Microgateway. Consultez également Modifier la configuration.

Attributs edge_config

Ces paramètres permettent de configurer l'interaction entre l'instance Edge Microgateway et Apigee Edge.

• bootstrap : (par défaut : aucun) URL pointant vers un service spécifique à Edge Microgateway s'exécutant sur Apigee Edge. Edge Microgateway utilise ce service pour communiquer avec Apigee Edge. Cette URL est renvoyée lorsque vous exécutez la commande pour générer la paire de clés publique/privée : edgemicro genkeys. Pour en savoir plus, consultez Configurer Edge Microgateway.
• jwt_public_key : (par défaut : aucune) URL qui pointe vers le proxy Edge Microgateway déployé sur Apigee Edge. Ce proxy sert de point de terminaison d'authentification pour émettre des jetons d'accès signés pour les clients. Cette URL est renvoyée lorsque vous exécutez la commande pour déployer le proxy : edgemicro configure. Pour en savoir plus, consultez Configurer Edge Microgateway.

Attributs edgemicro

Ces paramètres configurent le processus Edge Microgateway.

• port : (par défaut : 8000) numéro de port sur lequel le processus Edge Microgateway écoute.
• max_connections : (par défaut : -1) spécifie le nombre maximal de connexions entrantes simultanées qu'Edge Microgateway peut recevoir. Si ce nombre est dépassé, l'état suivant est renvoyé :
  
  res.statusCode = 429; // Too many requests
  
• max_connections_hard : (par défaut : -1) Nombre maximal de requêtes simultanées qu'Edge Microgateway peut recevoir avant d'arrêter la connexion. Ce paramètre est destiné à déjouer les attaques par déni de service. En règle générale, définissez-le sur un nombre supérieur à max_connections.
• logging :
  • level : (par défaut : error)
    • info : consigne toutes les requêtes et réponses qui transitent par une instance Edge Microgateway.
    • warn : ne consigne que les messages d'avertissement.
    • error : consigne uniquement les messages d'erreur.
  • dir (par défaut : /var/tmp) : répertoire dans lequel les fichiers journaux sont stockés.
  • stats_log_interval : (par défaut : 60) intervalle, en secondes, entre l'écriture de l'enregistrement des statistiques dans le fichier journal de l'API.
  • rotate_interval (par défaut : 24) : intervalle, en heures, entre les rotations des fichiers journaux.

• plug-ins : les plug-ins ajoutent des fonctionnalités à Edge Microgateway. Pour en savoir plus sur le développement de plug-ins, consultez Développer des plug-ins personnalisés.

• dir : chemin relatif du répertoire ./gateway au répertoire ./plugins, ou chemin absolu.
• sequence : liste des modules de plug-in à ajouter à votre instance Edge Microgateway. Les modules s'exécuteront dans l'ordre dans lequel ils sont spécifiés ici.

• debug : ajoute le débogage à distance au processus Edge Microgateway.
  • port : numéro de port sur lequel écouter. Par exemple, configurez votre débogueur IDE pour qu'il écoute sur ce port.
  • args : arguments du processus de débogage. Exemple :args --nolazy
    
• config_change_poll_interval: (par défaut : 600 secondes) : Edge Microgateway charge régulièrement une nouvelle configuration et l'exécute si des modifications ont été apportées. L'interrogation récupère toutes les modifications apportées sur Edge (modifications apportées aux produits, aux proxys compatibles avec Microgateway, etc.) ainsi que les modifications apportées au fichier de configuration local.
  
• disable_config_poll_interval (par défaut : false) : définissez cette option sur true pour désactiver l'interrogation automatique des modifications.
• request_timeout : définit un délai avant expiration pour les requêtes cibles. Le délai avant expiration est défini en secondes. Si un délai avant expiration est atteint, Edge Microgateway répond avec un code d'état 504. (Ajouté dans la version 2.4.x)

attributs d'en-tête

Ces paramètres configurent la manière dont certains en-têtes HTTP sont traités.

• x-forwarded-for : (valeur par défaut : true) Définissez cette option sur "false" pour empêcher la transmission des en-têtes x-forwarded-for à la cible. Notez que si un en-tête x-forwarded-for est présent dans la requête, sa valeur sera définie sur la valeur client-ip dans Edge Analytics.
• x-forwarded-host : (par défaut : true) Définissez cette option sur "false" pour empêcher la transmission des en-têtes x-forwarded-host à la cible.
• x-request-id : (par défaut : true) Définissez cette option sur "false" pour empêcher la transmission des en-têtes x-request-id à la cible.
• x-response-time : (par défaut : true) Définissez cette option sur "false" pour empêcher la transmission des en-têtes x-response-time à la cible.
• via : (par défaut : true) définissez cette option sur "false" pour empêcher la transmission des en-têtes "via" à la cible.

attributs oauth

Ces paramètres configurent la manière dont l'authentification du client est appliquée par Edge Microgateway.

• allowNoAuthorization : (par défaut : false) si la valeur est définie sur true, les appels d'API sont autorisés à passer par Edge Microgateway sans aucun en-tête d'autorisation. Définissez cette option sur "false" pour exiger un en-tête d'autorisation (par défaut).
• allowInvalidAuthorization : (par défaut : false) si la valeur est définie sur "true", les appels d'API sont autorisés à passer si le jeton transmis dans l'en-tête Authorization n'est pas valide ou a expiré. Définissez cette option sur "false" pour exiger des jetons valides (par défaut).
• authorization-header : (par défaut : Authorization: Bearer) en-tête utilisé pour envoyer le jeton d'accès à Edge Microgateway. Vous pouvez modifier la valeur par défaut si la cible doit utiliser l'en-tête Authorization à d'autres fins.
• api-key-header : (par défaut : x-api-key) nom de l'en-tête ou du paramètre de requête utilisé pour transmettre une clé API à Edge Microgateway. Consultez également Utiliser une clé API.
• keep-authorization-header (par défaut : false) : si la valeur est définie sur "true", l'en-tête Authorization envoyé dans la requête est transmis à la cible (il est conservé).
• allowOAuthOnly : si la valeur est définie sur "true", chaque API doit comporter un en-tête d'autorisation avec un jeton d'accès de support. Permet d'autoriser uniquement le modèle de sécurité OAuth (tout en maintenant la rétrocompatibilité). (Ajouté dans la version 2.4.x)
• allowAPIKeyOnly : si la valeur est définie sur "true", chaque API doit comporter un en-tête x-api-key (ou un emplacement personnalisé) avec une clé API.Vous pouvez ainsi n'autoriser que le modèle de sécurité de clé API (tout en conservant la rétrocompatibilité). (Ajouté à la version 2.4.x)
• gracePeriod : ce paramètre permet d'éviter les erreurs causées par de légères différences entre l'horloge de votre système et les heures "Not Before" (nbf) ou "Issued At" (iat) spécifiées dans le jeton d'autorisation JWT. Définissez ce paramètre sur le nombre de secondes à autoriser pour de tels écarts. (Ajouté dans la version 2.5.7)

Attributs spécifiques au plug-in

Pour en savoir plus sur les attributs configurables de chaque plug-in, consultez la section "Utiliser des plug-ins".

Filtrer les proxys

Vous pouvez filtrer les proxys compatibles avec Microgateway qu'une instance Edge Microgateway traitera. Lorsque Edge Microgateway démarre, il télécharge tous les proxys compatibles avec Microgateway dans l'organisation à laquelle il est associé. Utilisez la configuration suivante pour limiter les proxys que la micro-passerelle traitera. Par exemple, cette configuration limite à trois le nombre de proxys que la microgateway traitera : edgemicro_proxy-1, edgemicro_proxy-2 et edgemicro_proxy-3 :

proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

Configurer la fréquence d'envoi des données analytiques

Utilisez ces paramètres de configuration pour contrôler la fréquence à laquelle Edge Microgateway envoie des données d'analyse à Apigee :

• bufferSize (facultatif) : nombre maximal d'enregistrements d'analyse que le tampon peut contenir avant de commencer à supprimer les enregistrements les plus anciens. Par défaut : 10000
• batchSize (facultatif) : taille maximale d'un lot d'enregistrements d'analyse envoyés à Apigee. Par défaut : 500
• flushInterval (facultatif) : nombre de millisecondes entre chaque vidage d'un lot d'enregistrements d'analyse envoyés à Apigee. Valeur par défaut : 5000

Exemple :

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Masquer les données d'analyse

La configuration suivante empêche l'affichage des informations sur le chemin de la requête dans Edge Analytics. Ajoutez les éléments suivants à la configuration de la micro-passerelle pour masquer l'URI de la demande et/ou le chemin d'accès de la requête. Notez que l'URI se compose du nom d'hôte et du chemin d'accès de la requête.

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

Séparer les appels d'API dans Edge Analytics

Vous pouvez configurer le plug-in d'analyse pour séparer un chemin d'API spécifique afin qu'il apparaisse en tant que proxy distinct dans les tableaux de bord Edge Analytics. Par exemple, vous pouvez séparer une API de vérification d'état dans le tableau de bord pour éviter de la confondre avec les appels de proxy d'API réels. Dans le tableau de bord Analytics, les proxys séparés suivent le format de nommage suivant :

edgemicro_proxyname-health

L'image suivante montre deux proxys distincts dans le tableau de bord Analytics : edgemicro_hello-health et edgemicro_mock-health :

Utilisez ces paramètres pour séparer les chemins d'accès relatifs et absolus dans le tableau de bord Analytics en tant que proxys distincts :

• relativePath (facultatif) : spécifie un chemin relatif à séparer dans le tableau de bord Analytics. Par exemple, si vous spécifiez /healthcheck, tous les appels d'API contenant le chemin d'accès /healthcheck s'afficheront dans le tableau de bord sous la forme edgemicro_proxyname-health. Notez que cette option ignore le chemin de base du proxy. Pour séparer les données en fonction d'un chemin d'accès complet, y compris le chemin d'accès de base, utilisez l'option proxyPath.
• proxyPath (facultatif) : spécifie un chemin d'accès complet au proxy d'API, y compris le chemin de base du proxy, à séparer dans le tableau de bord d'analyse. Par exemple, si vous spécifiez /mocktarget/healthcheck, où /mocktarget est le chemin de base du proxy, tous les appels d'API avec le chemin d'accès /mocktarget/healthcheck apparaîtront dans le tableau de bord sous la forme edgemicro_proxyname-health.

Par exemple, dans la configuration suivante, tout chemin d'API contenant /healthcheck sera séparé par le plug-in d'analyse. Cela signifie que /foo/healthcheck et /foo/bar/healthcheck seront séparés en tant que proxy distinct appelé edgemicro_proxyname-health dans le tableau de bord d'analyse.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  relativePath: /healthcheck

Dans la configuration suivante, toute API dont le chemin d'accès au proxy est /mocktarget/healthcheck sera séparée en tant que proxy distinct appelé edgemicro_proxyname-health dans le tableau de bord d'analyse.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  proxyPath: /mocktarget/healthcheck

Configurer Edge Microgateway derrière un pare-feu d'entreprise

Version 2.4.x compatible

Si Edge Microgateway est installé derrière un pare-feu, il se peut que la passerelle ne puisse pas communiquer avec Apigee Edge. Dans ce cas, deux options s'offrent à vous :

Option 1 :

La première option consiste à définir l'option edgemicro: proxy_tunnel sur "true" dans le fichier de configuration de Microgateway :

edge_config:

    proxy: http://10.224.16.85:3128
    proxy_tunnel: true

Lorsque proxy_tunnel est défini sur true, Edge Microgateway utilise la méthode HTTP CONNECT pour tunneliser les requêtes HTTP sur une seule connexion TCP. (Il en va de même si les variables d'environnement permettant de configurer le proxy sont compatibles avec TLS.)

Option 2 :

La deuxième option consiste à spécifier un proxy et à définir proxy_tunnel sur "false" dans le fichier de configuration de microgateway. Exemple :

edge_config:
     proxy: http://10.224.16.85:3128
     proxy_tunnel: false

Dans ce cas, vous pouvez définir les variables suivantes pour contrôler les hôtes de chaque proxy HTTP que vous souhaitez utiliser, ou les hôtes qui ne doivent pas gérer les proxys Edge Microgateway : HTTP_PROXY, HTTPS_PROXY et NO_PROXY.

Vous pouvez définir NO_PROXY comme une liste de domaines séparés par une virgule vers lesquels Edge Microgateway ne doit pas envoyer de proxy. Exemple :

export NO_PROXY='localhost,localhost:8080'

Définissez HTTP_PROXY et HTTPS_PROXY sur le point de terminaison du proxy HTTP auquel Edge Microgateway peut envoyer des messages. Exemple :

export HTTP_PROXY='http://localhost:3786'

export HTTPS_PROXY='https://localhost:3786'

Pour en savoir plus sur ces variables, consultez https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables.

Voir aussi

How to set up Edge Microgateway behind a company firewall (Comment configurer Edge Microgateway derrière un pare-feu d'entreprise) sur la communauté Apigee.

Utiliser des caractères génériques dans les proxys compatibles avec Microgateway

Vous pouvez utiliser un ou plusieurs caractères génériques "*" dans le chemin de base d'un proxy edgemicro_* (compatible avec Microgateway). Par exemple, un chemin de base /team/*/members permet aux clients d'appeler https://[host]/team/blue/members et https://[host]/team/green/members sans que vous ayez besoin de créer des proxys d'API pour prendre en charge de nouvelles équipes. Notez que /**/ n'est pas accepté.

Important : Apigee n'accepte PAS l'utilisation d'un caractère générique "*" comme premier élément d'un chemin de base. Par exemple, la recherche /*/ n'est PAS acceptée.

Effectuer une rotation des clés JWT

Après avoir généré un jeton JWT, vous devrez peut-être modifier la paire de clés publique/privée stockée dans la KVM chiffrée Edge. Ce processus de génération d'une nouvelle paire de clés est appelé "rotation des clés".

Comment Edge Microgateway utilise les jetons JWT

Le jeton Web JSON (JWT) est une norme de jeton décrite dans la RFC7519. Le jeton JWT permet de signer un ensemble de revendications, qui peuvent être vérifiées de manière fiable par le destinataire du jeton JWT.

Edge Microgateway utilise des jetons JWT comme jetons de support pour la sécurité OAuth. Lorsque vous générez un jeton OAuth pour Edge Microgateway, vous recevez un jeton JWT. Vous pouvez ensuite utiliser le jeton JWT dans l'en-tête Authorization des appels d'API. Exemple :

curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"

Générer un nouveau jeton JWT

Vous pouvez générer un jeton JWT pour Edge Microgateway à l'aide de la commande edgemicro token ou d'une API. Exemple :

edgemicro token get -o docs -e test -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Cette commande demande à Apigee Edge de générer un jeton JWT qui peut ensuite être utilisé pour vérifier les appels d'API. Les paramètres -i et -s sont l'ID client et les valeurs de code secret d'une application de développeur dans votre organisation Apigee Edge.

Vous pouvez également générer un jeton JWT à l'aide de l'API Management :

curl -i -X POST "http://org-env.apigee.net/edgemicro-auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your consumer key",
    "client_secret": "your consumer secret",
    "grant_type": "client_credentials"
  }'

Où :

• org est le nom de votre organisation Edge (vous devez être un administrateur de l'organisation).
• env est un environnement de votre organisation (par exemple, "test" ou "prod").
• client_id est l'ID client de l'application de développeur que vous avez créée précédemment.
• client_secret est le code secret du client dans l'application de développeur que vous avez créée précédemment.

Qu'est-ce que la rotation des clés ?

Après avoir généré un jeton JWT, vous devrez peut-être modifier la paire de clés publique/privée stockée dans la KVM chiffrée Edge. Ce processus de génération d'une nouvelle paire de clés est appelé "rotation des clés". Lorsque vous effectuez une rotation des clés, une nouvelle paire de clés privée/publique est générée et stockée dans la KVM "microgateway" de votre organisation/environnement Apigee Edge. De plus, l'ancienne clé publique est conservée avec sa valeur d'ID de clé d'origine.

Pour générer un jeton JWT, Edge utilise les informations stockées dans le KVM chiffré. Un KVM appelé microgateway a été créé et renseigné avec des clés lors de la configuration initiale d'Edge Microgateway. Les clés de la KVM sont utilisées pour signer et chiffrer un jeton JWT.

Les clés KVM incluent :

• private_key : dernière clé privée RSA (la plus récemment créée) utilisée pour signer les jetons JWT.

• public_key : dernier certificat (le plus récemment créé) utilisé pour valider les jetons JWT signés avec la clé private_key.

• private_key_kid : ID de la clé privée la plus récente (créée le plus récemment). Cet ID de clé est associé à la valeur private_key et est utilisé pour la rotation des clés.

• public_key1_kid : ID de la clé publique la plus récente (créée le plus récemment). Cette clé est associée à la valeur public_key1 et permet d'assurer la rotation des clés. Cette valeur est identique au kid de la clé privée.

• public_key1 : clé publique la plus récente (créée le plus récemment).

Lorsque vous effectuez une rotation des clés, les valeurs de clé existantes sont remplacées dans le mappage et de nouvelles clés sont ajoutées pour conserver les anciennes clés publiques. Exemple :

• public_key2_kid : ID de l'ancienne clé publique. Cette clé est associée à la valeur public_key2 et permet d'assurer la rotation des clés.

• public_key2 : l'ancienne clé publique.

Les jetons JWT présentés pour validation seront validés à l'aide de la nouvelle clé publique. Si la validation échoue, l'ancienne clé publique sera utilisée jusqu'à son expiration (après 30 minutes). De cette façon, vous pouvez effectuer une rotation des clés sans perturber immédiatement le trafic de l'API.

Effectuer une rotation des clés

Cette section explique comment effectuer une rotation des clés.

Si vous avez configuré votre instance Edge Microgateway avant la version 2.5.2

Si vous avez configuré votre instance Edge Microgateway avant la version 2.5.2, vous devez exécuter les deux commandes suivantes pour mettre à niveau la KVM et la règle d'authentification :

upgradekvm -o org -e env -u username

Pour en savoir plus sur cette commande, consultez Mettre à niveau KVM.

La commande suivante met à niveau le proxy edgemicro-oauth qui a été déployé dans votre organisation Apigee lorsque vous avez configuré Edge Microgateway. Ce proxy fournit les services requis pour générer des jetons.

upgradeauth -o org -e env -u username

Pour en savoir plus sur cette commande, consultez Mettre à niveau le proxy edgemicro-auth.

Effectuer une rotation des clés

Ajoutez la ligne suivante à votre fichier ~/.edgemicro/org-env-config.yaml, où vous devez spécifier l'organisation et l'environnement que vous avez configurés pour l'utilisation de la micro-passerelle :

jwk_public_keys: 'https://org-env.apigee.net/edgemicro-auth/jwkPublicKeys'

Exécutez la commande de rotation des clés pour effectuer la rotation des clés. (Pour en savoir plus sur cette commande, consultez Effectuer la rotation des clés.)

edgemicro rotatekey -o org -e env -u username -k kid_value

Exemple :

edgemicro rotatekey -o jdoe -e test -u jdoe@google.com -k 2
current nodejs version is v6.9.1
current edgemicro version is 2.5.7
password:
Checking if private key exists in the KVM...
Checking for certificate...
Found Certificate
Generating New key/cert pair...
Extract new public key
Key Rotation successfully completed!

Le paramètre -k spécifie un ID de clé (kid). Cet ID permet de faire correspondre une clé spécifique. Edge Microgateway utilise cette valeur pour choisir parmi un ensemble de clés lors de la rotation des clés. Pour en savoir plus, consultez la section 4.5 de la spécification JSON Web Key.

Après la rotation des clés, Edge renvoie plusieurs clés à Edge Microgateway. Notez que dans l'exemple suivant, chaque clé possède une valeur "kid" (ID de clé) unique. La micro-passerelle utilise ensuite ces clés pour valider les jetons d'autorisation. Si la validation du jeton échoue, la micro-passerelle vérifie s'il existe une clé plus ancienne dans l'ensemble de clés et l'essaie. Le format des clés renvoyées est JSON Web Key (JWK). Pour en savoir plus sur ce format, consultez la RFC 7517.

{
  "keys": [
    {
      "kty": "RSA",
      "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ",
      "e": "AQAB",
      "kid": "2"
    },
    {
      "kty": "RSA",
      "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw",
      "e": "AQAB",
      "kid": "1"
    }
  ]
}

Filtrage des proxys téléchargés…

Par défaut, Edge Microgateway télécharge tous les proxys de votre organisation Edge qui commencent par le préfixe de nom "edgemicro_". Vous pouvez modifier cette valeur par défaut pour télécharger des proxys dont les noms correspondent à un modèle.

1. Ouvrez votre fichier de configuration Edge Micro : ~/.edgemicro/org-env-config.yaml.
2. Ajoutez l'élément proxyPattern sous edge_config. Par exemple, le modèle suivant télécharge des proxys tels que edgemicro_foo, edgemicro_fast et edgemicro_first.

   edge_config:
   …
   proxyPattern: edgemicro_f*

Spécifier des produits sans proxys d'API

Dans Apigee Edge, vous pouvez créer un produit d'API qui ne contient aucun proxy d'API. Cette configuration de produit permet à une clé API associée à ce produit de fonctionner avec n'importe quel proxy déployé dans votre organisation. À partir de la version 2.5.4, Edge Microgateway est compatible avec cette configuration de produit.

Débogage et dépannage

Se connecter à un débogueur

Vous pouvez exécuter Edge Microgateway avec un débogueur, tel que node-inspector. Cela s'avère utile pour résoudre les problèmes et déboguer les plug-ins personnalisés.

1. Redémarrez Edge Microgateway en mode débogage. Pour ce faire, ajoutez DEBUG=* au début de la commande start. Exemple :

   DEBUG=* edgemicro start -o  myorg -e test -k
         db4e9e8a95aa7fabfdeacbb1169d0a8cbe42bec19c6b98129e02 -s
         6e56af7c1b26dfe93dae78a735c8afc9796b077d105ae5618ce7ed

2. Démarrez votre débogueur et configurez-le pour qu'il écoute sur le numéro de port du processus de débogage.
3. Vous pouvez maintenant parcourir le code Edge Microgateway, définir des points d'arrêt, surveiller des expressions, etc.

Vous pouvez spécifier des options Node.js standards liées au mode débogage. Par exemple, --nolazy permet de déboguer du code asynchrone.

Vérifier les fichiers journaux

Si vous rencontrez des problèmes, veillez à examiner les fichiers journaux pour obtenir des détails sur l'exécution et des informations sur les erreurs. Pour en savoir plus, consultez Gérer les fichiers journaux.

Utiliser la sécurité des clés API

Les clés API fournissent un mécanisme simple pour authentifier les clients qui envoient des requêtes à Edge Microgateway. Vous pouvez obtenir une clé API en copiant la valeur de la clé client (également appelée ID client) à partir d'un produit Apigee Edge qui inclut le proxy d'authentification Edge Microgateway.

Mise en cache des clés

Les clés API sont échangées contre des jetons de support, qui sont mis en cache. Vous pouvez désactiver la mise en cache en définissant l'en-tête Cache-Control: no-cache sur les requêtes entrantes vers Edge Microgateway.

Utiliser une clé API

Vous pouvez transmettre la clé API dans une requête API, soit en tant que paramètre de requête, soit dans un en-tête. Par défaut, le nom de l'en-tête et celui du paramètre de requête sont tous deux x-api-key.

Exemple de paramètre de requête :

curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz

Exemple d'en-tête :

curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Configurer le nom de la clé API

Par défaut, x-api-key est le nom utilisé pour l'en-tête de la clé API et le paramètre de requête. Vous pouvez modifier cette valeur par défaut dans le fichier de configuration, comme expliqué dans Apporter des modifications à la configuration. Par exemple, pour remplacer le nom par apiKey :

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  api-key-header: apiKey

Dans cet exemple, le nom du paramètre de requête et celui de l'en-tête sont tous deux remplacés par apiKey. Le nom x-api-key ne fonctionnera plus dans les deux cas. Consultez également Modifier la configuration.

Exemple :

curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Pour en savoir plus sur l'utilisation de clés API avec des requêtes de proxy, consultez Sécuriser Edge Microgateway.

Utiliser la sécurité des jetons OAuth2

Cette section explique comment obtenir des jetons d'accès et d'actualisation OAuth2. Les jetons d'accès sont utilisés pour effectuer des appels d'API sécurisés via la micro-passerelle. Les jetons d'actualisation permettent d'obtenir de nouveaux jetons d'accès.

Obtenir un jeton d'accès

Cette section explique comment utiliser le proxy edgemicro-auth pour obtenir un jeton d'accès.

Vous pouvez également obtenir un jeton d'accès à l'aide de la commande CLI edgemicro token. Pour en savoir plus sur la CLI, consultez Gérer les jetons.

API 1

Remplacez les noms de votre organisation et de votre environnement dans l'URL, puis remplacez les valeurs de l'ID client et du code secret du client obtenues à partir d'une application de développeur sur Apigee Edge par les paramètres de corps client_id et client_secret :

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2

http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

Exemple de résultat

{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": "108000"
}

Obtenir un jeton d'actualisation

Pour obtenir un jeton d'actualisation, envoyez un appel d'API au point de terminaison /token du proxy edgemicro-auth. Vous DEVEZ effectuer cet appel d'API avec le type d'autorisation password. Les étapes suivantes décrivent le processus.

1. Obtenez un jeton d'accès et un jeton d'actualisation avec l'API /token. Notez que le type d'autorisation est password :

   curl -X POST \
     https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
      "client_secret":"bUdDcFgv3nXffnU",
      "grant_type":"password",
      "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
      "password":"bUdD2FvnMsXffnU"
   }'

   L'API renvoie un jeton d'accès et un jeton d'actualisation. La réponse ressemble à ceci :

   {
       "token": "your-access-token",
       "access_token": "your-access-token",
       "token_type": "bearer",
       "expires_in": "108000",
       "refresh_token": "your-refresh-token",
       "refresh_token_expires_in": "431999",
       "refresh_token_issued_at": "1562087304302",
       "refresh_token_status": "approved"
   }

2. Vous pouvez maintenant utiliser le jeton d'actualisation pour obtenir un nouveau jeton d'accès en appelant le point de terminaison /refresh de la même API. Exemple :

   curl -X POST \
     https://willwitman-test.apigee.net/edgemicro-auth/refresh \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq",
      "client_secret":"bUdDc2Fv3nMXffnU",
      "grant_type":"refresh_token",
      "refresh_token":"your-refresh-token"
   }'

   L'API renvoie un nouveau jeton d'accès. La réponse ressemble à ce qui suit :

   {
       "token": "your-new-access-token"
       }

Surveillance permanente

Forever est un outil Node.js qui redémarre automatiquement une application Node.js en cas d'arrêt ou d'erreur du processus. Edge Microgateway dispose d'un fichier forever.json que vous pouvez configurer pour contrôler le nombre de fois et les intervalles auxquels Edge Microgateway doit être redémarré. Ce fichier configure un service Forever appelé forever-monitor, qui gère Forever de manière programmatique.

Vous trouverez le fichier forever.json dans le répertoire d'installation racine d'Edge Microgateway. Consultez la section Où Edge Microgateway est-il installé ?. Pour en savoir plus sur les options de configuration, consultez la documentation de forever-monitor.

La commande edgemicro forever inclut des options qui vous permettent de spécifier l'emplacement du fichier forever.json (option -f) et de démarrer/arrêter le processus de surveillance Forever (option -a). Exemple :

edgemicro forever -f ~/mydir/forever.json -a start

Pour en savoir plus, consultez la section Surveillance permanente dans la documentation de référence de la CLI.

Spécifier un point de terminaison de fichier de configuration

Si vous exécutez plusieurs instances Edge Microgateway, vous pouvez gérer leurs configurations à partir d'un seul emplacement. Pour ce faire, spécifiez un point de terminaison HTTP à partir duquel Edge Micro peut télécharger son fichier de configuration. Vous pouvez spécifier ce point de terminaison lorsque vous démarrez Edge Micro à l'aide de l'option -u.

Exemple :

edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key

où le point de terminaison mgconfig renvoie le contenu de votre fichier de configuration. Il s'agit du fichier qui, par défaut, se trouve dans ~/.edgemicro et suit la convention d'attribution de noms org-env-config.yaml.

Désactiver la mise en mémoire tampon des données de connexion TCP

Vous pouvez utiliser l'attribut de configuration nodelay pour désactiver la mise en mémoire tampon des données pour les connexions TCP utilisées par Edge Microgateway.

Par défaut, les connexions TCP utilisent l'algorithme de Nagle pour mettre en mémoire tampon les données avant de les envoyer. Définir nodelay sur true désactive ce comportement (les données sont immédiatement envoyées chaque fois que socket.write() est appelé). Pour en savoir plus, consultez également la documentation Node.js.

Pour activer nodelay, modifiez le fichier de configuration Edge Micro comme suit :

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Exécuter Edge Microgateway en mode autonome

Vous pouvez exécuter Edge Microgateway complètement déconnecté de toute dépendance Apigee Edge. Ce scénario, appelé mode autonome, vous permet d'exécuter et de tester Edge Microgateway sans connexion Internet.

En mode autonome, les fonctionnalités suivantes ne fonctionnent pas, car elles nécessitent une connexion à Apigee Edge :

• OAuth et clé API
• Quota
• Analytics

En revanche, les plug-ins personnalisés et l'arrêt des pics fonctionnent normalement, car ils ne nécessitent pas de connexion à Apigee Edge. De plus, un nouveau plug-in appelé extauth vous permet d'autoriser les appels d'API vers la micro-passerelle avec un jeton JWT en mode autonome.

Configurer et démarrer la passerelle

Pour exécuter Edge Microgateway en mode autonome :

1. Assurez-vous que la version 2.5.25 ou ultérieure d'Edge Microgateway est installée. Si ce n'est pas le cas, vous devez exécuter la commande suivante pour passer à la dernière version :

   npm install -g edgemicro

   Si vous avez besoin d'aide, consultez Installer Edge Microgateway.

2. Créez un fichier de configuration nommé comme suit : $HOME/.edgemicro/org_name-env_name-config.yaml

   Exemple :

   vi $HOME/.edgemicro/foo-bar-config.yaml

3. Collez le code suivant dans le fichier :

   edgemicro:
     port: 8000
     max_connections: 1000
     config_change_poll_interval: 600
     logging:
       level: error
       dir: /var/tmp
       stats_log_interval: 60
       rotate_interval: 24
     plugins:
       sequence:
         - extauth
         - spikearrest
   headers:
     x-forwarded-for: true
     x-forwarded-host: true
     x-request-id: true
     x-response-time: true
     via: true
   extauth:
     publickey_url: https://www.googleapis.com/oauth2/v1/certs
   spikearrest:
     timeUnit: second
     allow: 10
     buffersize: 0

4. Exportez la variable d'environnement suivante avec la valeur "1" :

   export EDGEMICRO_LOCAL=1

5. Exécutez la commande start suivante, en fournissant des valeurs pour instancier le proxy local :

   edgemicro start -o org_name -e environment_name -a local_proxy_name \
     -v local_proxy_version -t target_url -b base_path

   Où :

   • your_org est le nom de l'organisation que vous avez utilisé dans le nom du fichier de configuration.
   • your_environment est le nom "env" que vous avez utilisé dans le nom du fichier de configuration.
   • local_proxy_name est le nom du proxy local qui sera créé. Vous pouvez utiliser n'importe quel nom.
   • local_proxy_version est le numéro de version du proxy.
   • target_url est l'URL de la cible du proxy. (La cible est le service appelé par le proxy.)
   • base_path est le chemin de base du proxy. Cette valeur doit commencer par une barre oblique. Pour un chemin de base racine, spécifiez simplement une barre oblique, par exemple "/".

   Exemple :

   edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. Tester la configuration

   curl http://localhost:8000/echo  { "error" : "missing_authorization" }

   Comme le plug-in extauth se trouve dans le fichier foo-bar-config.yaml, vous obtenez une erreur "missing_authorization". Ce plug-in valide un jeton JWT qui doit être présent dans l'en-tête Authorization de l'appel d'API. Dans la section suivante, vous allez obtenir un jeton JWT qui permettra aux appels d'API d'aboutir sans erreur.

Exemple : Obtenir un jeton d'autorisation

L'exemple suivant montre comment obtenir un jeton JWT à partir du point de terminaison JWT d'Edge Microgateway sur Apigee Edge (edgemicro-auth/jwkPublicKeys). Ce point de terminaison est déployé lorsque vous effectuez une configuration standard d'Edge Microgateway. Pour obtenir le jeton JWT à partir du point de terminaison Apigee, vous devez d'abord effectuer la configuration standard d'Edge Microgateway et être connecté à Internet. Le point de terminaison Apigee est utilisé ici à titre d'exemple uniquement et n'est pas obligatoire. Vous pouvez utiliser un autre point de terminaison de jeton JWT si vous le souhaitez. Si vous le faites, vous devrez obtenir le jeton JWT à l'aide de l'API fournie pour ce point de terminaison.

Les étapes suivantes expliquent comment obtenir un jeton à l'aide du point de terminaison edgemicro-auth/jwkPublicKeys :

1. Vous devez effectuer une configuration standard d'Edge Microgateway pour déployer le proxy edgemicro-auth dans votre organisation/environnement sur Apigee Edge. Si vous avez déjà effectué cette étape, vous n'avez pas besoin de la répéter.
2. Si vous avez déployé Edge Microgateway sur Apigee Cloud, vous devez être connecté à Internet pour pouvoir obtenir un jeton JWT à partir de ce point de terminaison.
3. Arrêtez Edge Microgateway :

   edgemicro stop

4. Dans le fichier de configuration que vous avez créé précédemment ($HOME/.edgemicro/org-env-config.yaml), faites pointer l'attribut extauth:publickey_url vers le point de terminaison edgemicro-auth/jwkPublicKeys de votre organisation/environnement Apigee Edge. Exemple :

   extauth:
     publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'

5. Redémarrez Edge Microgateway comme vous l'avez fait précédemment, en utilisant les noms d'organisation et d'environnement que vous avez utilisés dans le nom du fichier de configuration. Exemple :

   edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. Obtenez un jeton JWT à partir du point de terminaison d'autorisation. Comme vous utilisez le point de terminaison edgemicro-auth/jwkPublicKeys, vous pouvez utiliser cette commande CLI :

Vous pouvez générer un jeton JWT pour Edge Microgateway à l'aide de la commande edgemicro token ou d'une API. Exemple :

edgemicro token get -o your_org -e your_env \
  -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Où :

• your_org est le nom de l'organisation Apigee pour laquelle vous avez précédemment configuré Edge Microgateway.
• your_env est un environnement de l'organisation.
• L'option i spécifie la clé client d'une application de développeur qui possède un produit incluant le proxy edgemicro-auth.
• L'option s spécifie le code secret du client d'une application de développeur qui dispose d'un produit incluant le proxy edgemicro-auth.

Cette commande demande à Apigee Edge de générer un jeton JWT qui peut ensuite être utilisé pour vérifier les appels d'API.

Tester la configuration autonome

Pour tester la configuration, appelez l'API avec le jeton ajouté dans l'en-tête Authorization comme suit :

curl http://localhost:8000/echo -H "Authorization: Bearer your_token

Exemple :

curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"

Exemple de résultat :

{
   "headers":{
      "user-agent":"curl/7.54.0",
      "accept":"*/*",
      "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
      "client_received_start_timestamp":"1535134472699",
      "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==",
      "target_sent_start_timestamp":"1535134472702",
      "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
      "x-forwarded-proto":"http",
      "x-forwarded-host":"localhost:8000",
      "host":"mocktarget.apigee.net",
      "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
      "via":"1.1 localhost, 1.1 google",
      "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
      "connection":"Keep-Alive"
   },
   "method":"GET",
   "url":"/",
   "body":""
}

Utiliser le mode proxy local

En mode proxy local, Edge Microgateway ne nécessite pas le déploiement d'un proxy compatible avec Microgateway sur Apigee Edge. À la place, vous configurez un "proxy local" en fournissant un nom de proxy local, un chemin de base et une URL cible lorsque vous démarrez la micro-passerelle. Les appels d'API vers la microgateway sont ensuite envoyés à l'URL cible du proxy local. À tous les autres égards, le mode proxy local fonctionne exactement de la même manière que l'exécution d'Edge Microgateway en mode normal. L'authentification fonctionne de la même manière, tout comme la protection contre les pics de trafic, l'application des quotas, les plug-ins personnalisés, etc.

Cas d'utilisation et exemple

Le mode proxy local est utile lorsque vous n'avez besoin d'associer qu'un seul proxy à une instance Edge Microgateway. Par exemple, vous pouvez injecter Edge Microgateway dans Kubernetes en tant que proxy side-car, où une micro-passerelle et un service s'exécutent chacun dans un seul pod, et où la micro-passerelle gère le trafic vers et depuis son service associé. La figure suivante illustre cette architecture dans laquelle Edge Microgateway fonctionne comme un proxy side-car dans un cluster Kubernetes. Chaque instance de micro-passerelle ne communique qu'avec un seul point de terminaison sur son service associé :

L'un des avantages de ce style d'architecture est qu'Edge Microgateway fournit une gestion des API pour les services individuels déployés dans un environnement de conteneur, tel qu'un cluster Kubernetes.

Configurer le mode proxy local

Pour configurer Edge Microgateway afin qu'il s'exécute en mode proxy local, procédez comme suit :

1. Assurez-vous que la version 2.5.25 ou ultérieure d'Edge Microgateway est installée. Si ce n'est pas le cas, vous devez exécuter la commande suivante pour passer à la dernière version :

   npm install -g edgemicro

   Si vous avez besoin d'aide, consultez Installer Edge Microgateway.

2. Exécutez edgemicro init pour configurer votre environnement de configuration local, exactement comme vous le feriez dans une configuration Edge Microgateway classique. Consultez également Configurer Edge Microgateway.
3. Exécutez edgemicro configure, comme vous le feriez dans une procédure de configuration Edge Microgateway classique. Exemple :

   edgemicro configure -o your_org -e your_env -u your_apigee_username

   Cette commande déploie la règle edgemicro-auth sur Edge et renvoie une clé et un secret dont vous aurez besoin pour démarrer la micro-passerelle. Si vous avez besoin d'aide, consultez Configurer Edge Microgateway.

4. Sur Apigee Edge, créez un produit d'API avec les exigences de configuration obligatoires suivantes (vous pouvez gérer toutes les autres configurations comme vous le souhaitez) :
   • Vous devez ajouter le proxy edgemicro-auth au produit. Ce proxy a été déployé automatiquement lorsque vous avez exécuté edgemicro configure.
   • Vous devez fournir un chemin d'accès à la ressource. Apigee recommande d'ajouter ce chemin d'accès au produit : /**. Pour en savoir plus, consultez Configurer le comportement du chemin d'accès à la ressource. Consultez également Créer des produits d'API dans la documentation Edge.

5. Sur Apigee Edge, créez un développeur ou utilisez un développeur existant si vous le souhaitez. Pour obtenir de l'aide, consultez Ajouter des développeurs à l'aide de l'interface utilisateur de gestion Edge.

6. Sur Apigee Edge, créez une application de développeur. Vous devez ajouter le produit d'API que vous venez de créer à l'application. Pour obtenir de l'aide, consultez la section Enregistrer une application dans l'interface utilisateur de gestion Edge.
7. Sur la machine où Edge Microgateway est installé, exportez la variable d'environnement suivante avec la valeur "1".

   export EDGEMICRO_LOCAL_PROXY=1

8. Exécutez la commande start suivante :

   edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
       -a local_proxy_name -v local_proxy_version -t target_url -b base_path

   Où :

   • your_org est votre organisation Apigee.
   • your_environment est un environnement de votre organisation.
   • your_key est la clé renvoyée lorsque vous avez exécuté edgemicro configure.
   • your_secret est le secret renvoyé lorsque vous avez exécuté edgemicro configure.
   • local_proxy_name est le nom du proxy local qui sera créé.
   • local_proxy_version est le numéro de version du proxy.
   • target_url est l'URL de la cible du proxy (le service que le proxy appellera).
   • base_path est le chemin de base du proxy. Cette valeur doit commencer par une barre oblique. Pour un chemin de base racine, spécifiez simplement une barre oblique, par exemple "/".

   Exemple :

   edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
     -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
     -t http://mocktarget.apigee.net -b /echo

Tester la configuration

Vous pouvez tester la configuration du proxy local en appelant le point de terminaison du proxy. Par exemple, si vous avez spécifié un chemin de base /echo, vous pouvez appeler le proxy comme suit :

curl  http://localhost:8000/echo
{
  "error" : "missing_authorization",
  "error_description" : "Missing Authorization header"
}

Cet appel d'API initial a généré une erreur, car vous n'avez pas fourni de clé API valide. Vous trouverez la clé dans l'application de développement que vous avez créée précédemment. Ouvrez l'application dans l'interface utilisateur Edge, copiez la clé client et utilisez-la comme suit :

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

Exemple :

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

Exemple de résultat :

{
  "headers":{
    "user-agent":"curl/7.54.0",
    "accept":"*/*",
    "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
    "client_received_start_timestamp":"1535134472699",
    "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==",
    "target_sent_start_timestamp":"1535134472702",
    "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
    "x-forwarded-proto":"http",
    "x-forwarded-host":"localhost:8000",
    "host":"mocktarget.apigee.net",
    "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
    "via":"1.1 localhost, 1.1 google",
    "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
    "connection":"Keep-Alive"
  },
  "method":"GET",
  "url":"/",
  "body":""
}