GSP844

Présentation

Apigee est une plate-forme de développement et de gestion des API qui peut vous aider à sécuriser l'accès à vos API et à en limiter le débit. Apigee fournit également des fonctionnalités permettant de sécuriser l'accès interne aux données d'API.

Dans cet atelier, vous allez créer une API dont l'accès exige des jetons OAuth. Vous allez utiliser la règle SpikeArrest pour limiter le débit des appels d'API par application, ainsi que des variables privées et le masquage des données afin de cacher les données sensibles pour les utilisateurs qui déboguent le trafic d'API.

Objectifs

Dans cet atelier, vous allez apprendre à effectuer les tâches suivantes :

• Sécuriser l'accès aux API en exigeant un jeton OAuth
• Limiter le débit global du trafic et le débit par application avec la règle SpikeArrest
• Utiliser des variables privées et le masquage des données afin de cacher les données sensibles pour les utilisateurs qui déboguent le trafic d'API
• Restreindre les appels au backend à des ressources spécifiques
• Réécrire les messages d'erreur du backend pour vous protéger contre les fuites de données

Préparation

Avant de cliquer sur le bouton "Démarrer l'atelier"

Lisez ces instructions. Les ateliers sont minutés, et vous ne pouvez pas les mettre en pause. Le minuteur, qui démarre lorsque vous cliquez sur Démarrer l'atelier, indique combien de temps les ressources Google Cloud resteront accessibles.

Cet atelier pratique vous permet de suivre les activités dans un véritable environnement cloud, et non dans un environnement de simulation ou de démonstration. Des identifiants temporaires vous sont fournis pour vous permettre de vous connecter à Google Cloud le temps de l'atelier.

Pour réaliser cet atelier :

• Vous devez avoir accès à un navigateur Internet standard (nous vous recommandons d'utiliser Chrome).

Remarque : Ouvrez une fenêtre de navigateur en mode incognito (recommandé) ou de navigation privée pour effectuer cet atelier. Vous éviterez ainsi les conflits entre votre compte personnel et le compte temporaire de participant, qui pourraient entraîner des frais supplémentaires facturés sur votre compte personnel.

• Vous disposez d'un temps limité. N'oubliez pas qu'une fois l'atelier commencé, vous ne pouvez pas le mettre en pause.

Remarque : Utilisez uniquement le compte de participant pour cet atelier. Si vous utilisez un autre compte Google Cloud, des frais peuvent être facturés à ce compte. Remarque : Nous vous recommandons d'utiliser une nouvelle fenêtre de navigation privée pour réaliser cet atelier.

Démarrer l'atelier et se connecter à la console Google Cloud

1. Cliquez sur le bouton Démarrer l'atelier. Si l'atelier est payant, une boîte de dialogue s'affiche pour vous permettre de sélectionner un mode de paiement. Sur la gauche, vous trouverez le panneau "Détails concernant l'atelier", qui contient les éléments suivants :

   • Le bouton "Ouvrir la console Google Cloud"
   • Le temps restant
   • Les identifiants temporaires que vous devez utiliser pour cet atelier
   • Des informations complémentaires vous permettant d'effectuer l'atelier

2. Cliquez sur Ouvrir la console Google Cloud (ou effectuez un clic droit et sélectionnez Ouvrir le lien dans la fenêtre de navigation privée si vous utilisez le navigateur Chrome).

   L'atelier lance les ressources, puis ouvre la page "Se connecter" dans un nouvel onglet.

   Conseil : Réorganisez les onglets dans des fenêtres distinctes, placées côte à côte.

   Remarque : Si la boîte de dialogue Sélectionner un compte s'affiche, cliquez sur Utiliser un autre compte.

3. Si nécessaire, copiez le nom d'utilisateur ci-dessous et collez-le dans la boîte de dialogue Se connecter.

   {{{user_0.username | "Username"}}}

   Vous trouverez également le nom d'utilisateur dans le panneau "Détails concernant l'atelier".

4. Cliquez sur Suivant.

5. Copiez le mot de passe ci-dessous et collez-le dans la boîte de dialogue Bienvenue.

   {{{user_0.password | "Password"}}}

   Vous trouverez également le mot de passe dans le panneau "Détails concernant l'atelier".

6. Cliquez sur Suivant.

   Important : Vous devez utiliser les identifiants fournis pour l'atelier. Ne saisissez pas ceux de votre compte Google Cloud. Remarque : Si vous utilisez votre propre compte Google Cloud pour cet atelier, des frais supplémentaires peuvent vous être facturés.

7. Accédez aux pages suivantes :

   • Acceptez les conditions d'utilisation.
   • N'ajoutez pas d'options de récupération ni d'authentification à deux facteurs (ce compte est temporaire).
   • Ne vous inscrivez pas à des essais sans frais.

Après quelques instants, la console Cloud s'ouvre dans cet onglet.

Remarque : Pour accéder aux produits et services Google Cloud, cliquez sur le menu de navigation ou saisissez le nom du service ou du produit dans le champ Recherche.

Activer Cloud Shell

Cloud Shell est une machine virtuelle qui contient de nombreux outils pour les développeurs. Elle comprend un répertoire d'accueil persistant de 5 Go et s'exécute sur Google Cloud. Cloud Shell vous permet d'accéder via une ligne de commande à vos ressources Google Cloud.

1. Cliquez sur Activer Cloud Shell  en haut de la console Google Cloud.

2. Passez les fenêtres suivantes :

   • Accédez à la fenêtre d'informations de Cloud Shell.
   • Autorisez Cloud Shell à utiliser vos identifiants pour effectuer des appels d'API Google Cloud.

Une fois connecté, vous êtes en principe authentifié et le projet est défini sur votre ID_PROJET : . Le résultat contient une ligne qui déclare l'ID_PROJET pour cette session :

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud est l'outil de ligne de commande pour Google Cloud. Il est préinstallé sur Cloud Shell et permet la complétion par tabulation.

3. (Facultatif) Vous pouvez lister les noms des comptes actifs à l'aide de cette commande :

gcloud auth list

4. Cliquez sur Autoriser.

Résultat :

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (Facultatif) Vous pouvez lister les ID de projet à l'aide de cette commande :

gcloud config list project

Résultat :

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} Remarque : Pour consulter la documentation complète sur gcloud, dans Google Cloud, accédez au guide de présentation de la gcloud CLI.

Ouvrir la console Apigee

Pour ouvrir la console Apigee :

• Dans la console Google Cloud, dans le champ Rechercher, saisissez Apigee, puis cliquez sur Apigee API Management dans les résultats de recherche.

La console Apigee s'ouvre. La page de destination propose des liens rapides vers des emplacements couramment utilisés.

• Dans le menu de navigation (), à côté de Apigee, cliquez sur Ajouter aux favoris ().

Apigee est désormais ajouté en tant que favori au menu de navigation.

Tâche 1 : Mettre en place un proxy pour le service de backend à l'aide d'un proxy d'API Apigee

Dans cette tâche, vous allez créer un proxy d'API Apigee qui fait office de façade pour un service de backend. Ce proxy d'API utilisera un compte de service pour présenter des jetons d'identité OpenID Connect au service Cloud Run.

Un service de backend nommé simplebank-rest a déjà été créé et déployé sur Cloud Run. Un compte de service a également été créé pour vous.

Créer le proxy Apigee

1. Dans Cloud Shell, exécutez la commande suivante pour récupérer l'URL du service de backend :

   gcloud run services describe simplebank-rest --platform managed --region {{{project_0.default_region |REGION}}} --format 'value(status.url)'

   Enregistrez cette URL, car elle sera utilisée lors de la création du proxy d'API.

2. Accédez à l'interface utilisateur Apigee dans la console Cloud.

3. Dans le menu de navigation de gauche, sélectionnez Proxy development > API Proxies (Développement de proxys > Proxys d'API).

4. Pour créer un proxy à l'aide de l'assistant de proxy, cliquez sur + Create (+ Créer).

   Vous allez créer un proxy inverse pour votre service de backend. Ce proxy d'API utilisera une spécification OpenAPI afin de créer un squelette pour l'API.

5. Dans la zone Proxy template (Modèle de proxy), pour OpenAPI spec template (Modèle de spécification OpenAPI), sélectionnez Reverse proxy (Most common) (Proxy inverse (le plus courant)).

6. Pour OpenAPI File (Fichier OpenAPI), ouvrez l'URL ci-dessous dans un navigateur. Le fichier YAML de spécification OpenAPI sera alors téléchargé sur votre ordinateur :

   https://storage.googleapis.com/spls/gsp844/simplebank-backend.yaml

7. Cliquez sur Browse (Parcourir), sélectionnez le fichier OpenAPI sur l'ordinateur, puis cliquez sur Next (Suivant).

8. Spécifiez les informations suivantes pour les détails du proxy :

   Propriété	Valeur
   Proxy name (Nom du proxy)	bank-v1
   Base path (Chemin de base)	/bank/v1
   Description	API SimpleBank en lecture seule
   Target (Existing API) (Cible (API existante))	URL du backend

   Remarque : Vérifiez que vous utilisez "/bank/v1" comme chemin de base, et non "/bank-v1".

   La cible doit être l'URL du backend que vous avez récupérée précédemment au cours de cette tâche. Elle doit ressembler à ceci :

   https://simplebank-rest-nu7rb74j5a-uw.a.run.app

9. Cliquez sur Next (Suivant).

10. Conservez les autres paramètres par défaut, puis cliquez sur Create (Créer).

11. Cliquez sur l'onglet Develop (Développer).

    Remarque : Des flux ont été ajoutés au point de terminaison du proxy. Chacun d'eux spécifie un verbe et une condition de chemin d'accès pour l'une des opérations de la spécification OpenAPI.

Modifier la cible pour envoyer un jeton d'identité OpenID Connect

Le service de backend est déployé de manière à exiger un accès authentifié. Vous ne pouvez donc pas appeler le service sans jeton d'identité OpenID Connect valide.

La section HTTPTargetConnection spécifie la cible de backend du service.

1. Dans le menu de navigation du proxy, dans la section Target Endpoints (Points de terminaison cibles), cliquez sur PreFlow.

2. Recherchez le code suivant (votre URL sera différente) :

   <HTTPTargetConnection> <URL>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</URL> </HTTPTargetConnection> Remarque : Si la section "HTTPTargetConnection" n'apparaît pas, assurez-vous d'avoir cliqué sur "PreFlow" dans la section "Target Endpoints" (Points de terminaison cibles), et non dans la section "Proxy Endpoints" (Points de terminaison du proxy).

3. Sous l'URL, ajoutez une section Authentication qui ressemble à ceci :

   <Authentication> <GoogleIDToken> <Audience>AUDIENCE</Audience> </GoogleIDToken> </Authentication>

4. Remplacez AUDIENCE par la valeur d'URL déjà présente dans la section HTTPTargetConnection. Votre code doit maintenant ressembler à ceci, à la différence près que votre URL spécifique apparaît dans les éléments "URL" et "Audience" :

   <TargetEndpoint name="default"> <PreFlow name="PreFlow"> <Request/> <Response/> </PreFlow> <Flows/> <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <HTTPTargetConnection> <URL>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</URL> <Authentication> <GoogleIDToken> <Audience>https://simplebank-rest-zce6j3rjwq-uw.a.run.app</Audience> </GoogleIDToken> </Authentication> </HTTPTargetConnection> </TargetEndpoint>

5. Cliquez sur Save (Enregistrer).

Cliquez sur Vérifier ma progression pour valider l'objectif. Créer le proxy d'API

Tâche 2 : Ajouter OAuth au proxy d'API

Dans cette tâche, vous allez ajouter une règle OAuthV2 au proxy d'API. Une règle OAuthV2 utilisant l'opération VerifyJWTAccessToken applique la vérification des jetons d'accès lors de l'exécution. Ainsi, elle n'autorise l'accès à l'API que pour les applications qui disposent d'un jeton d'accès OAuth valide.

La règle OAuthV2 peut créer et valider aussi bien des jetons opaques que des jetons Web JSON (JWT). Ce proxy d'API utilisera des JWT comme jetons d'accès.

Un ensemble de propriétés sera utilisé pour stocker la signature secrète utilisée lors de la création et de la validation du jeton JWT.

Créer la signature secrète dans l'ensemble de propriétés

Le jeton JWT sera signé à l'aide d'un code d'authentification de message HMAC (Hash-based Message Authentication Code). Ce type de signature cryptographique nécessite un secret.

1. Dans le menu de navigation du proxy, cliquez sur + à côté de Resources (Ressources).

2. Dans le menu déroulant Resource type (Type de ressource), sélectionnez Property Set (Ensemble de propriétés).

3. Pour Resource Name (Nom de ressource), spécifiez oauth.properties, puis cliquez sur Add (Ajouter).

4. Dans le volet de code oauth.properties, ajoutez la propriété suivante :

   secret=thisisnotagoodsecret,useabettersecretinproduction

   Cette valeur est accessible dans le code à l'aide de la variable de flux propertyset.oauth.secret.

   Remarque : Les valeurs de l'ensemble de propriétés sont stockées en texte brut. Dans un environnement de production, vous choisiriez probablement de stocker le secret HMAC dans un emplacement chiffré, et il faudrait assurément utiliser un secret plus sécurisé (aléatoire).

Ajouter une règle AssignMessage pour récupérer la valeur de l'ensemble de propriétés

La signature secrète doit être fournie à la règle OAuth dans une variable privée, mais la variable propertyset.oauth.secret n'est pas privée. Cette règle AssignMessage créera une variable privée à partir de la variable de l'ensemble de propriétés.

1. Dans le menu de navigation du proxy, dans la section Proxy Endpoints (Points de terminaison du proxy), sous default (par défaut), cliquez sur PreFlow.

   Le PreFlow de requête dans le point de terminaison de proxy par défaut est le premier flux exécuté lorsqu'une requête parvient au proxy d'API.

   La règle OAuthV2 exige le secret et elle est exécutée très tôt dans le proxy d'API.

2. Dans le volet Flow (Flux), cliquez sur le bouton + juste à côté de PreFlow dans le flux de requête.

3. Sélectionnez Create new policy (Créer une règle), puis, dans le menu déroulant Select policy (Sélectionner une règle), choisissez Assign Message (Attribuer un message) dans la section Mediation (Médiation). Définissez ensuite les valeurs de Display Name (Nom à afficher) et Name (Nom) sur AM-GetSecret.

4. Cliquez sur Add (Ajouter). Dans le menu de navigation, cliquez sur AM-GetSecret sous Policies (Règles).

   La configuration de la règle AssignMessage s'affiche dans le volet Code.

5. Modifiez la configuration de la règle comme suit :

   <AssignMessage name="AM-GetSecret"> <AssignVariable> <Name>private.secretkey</Name> <Ref>propertyset.oauth.secret</Ref> </AssignVariable> <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables> </AssignMessage>

   Le paramètre AssignVariable copie la variable propertyset.oauth.secret dans la variable private.secretkey.

   Le paramètre IgnoreUnresolvedVariables entraîne la génération d'une erreur par la règle AssignMessage s'il n'est pas possible de résoudre propertyset.oauth.secret.

Ajouter la règle OAuthV2 servant à vérifier un jeton

1. Dans le menu de navigation du proxy, dans la section Proxy Endpoints (Points de terminaison du proxy), sous default (par défaut), cliquez sur PreFlow.

   La règle OAuthV2 doit s'exécuter après la règle AssignMessage.

2. Dans le volet Flow (Flux), cliquez sur le bouton + juste à côté de PreFlow dans le flux de requête.

3. Sélectionnez Create new policy (Créer une règle), puis, dans le menu déroulant Select policy (Sélectionner une règle), choisissez OAuth v2.0 dans la section Security (Sécurité). Définissez ensuite les valeurs de Display Name (Nom à afficher) et Name (Nom) sur OA-VerifyToken.

4. Cliquez sur Add (Ajouter), puis sur OA-VerifyToken dans la section Policies (Règles) du menu de navigation.

   La configuration de la règle OAuthV2 s'affiche dans le volet Code.

5. Modifiez la configuration de la règle OAuthV2 comme suit :

   <OAuthV2 name="OA-VerifyToken"> <Operation>VerifyJWTAccessToken</Operation> <Algorithm>HS256</Algorithm> <SecretKey> <Value ref="private.secretkey"/> </SecretKey> </OAuthV2>

   La configuration spécifie que le jeton d'accès JWT utilise l'algorithme HS256 (HMAC-SHA256) avec comme clé secrète la variable privée créée dans la règle AssignMessage.

6. Cliquez sur Save (Enregistrer).

Cliquez sur Vérifier ma progression pour valider l'objectif. Ajouter des règles pour valider les jetons

Tâche 3 : Ajouter des règles pour générer des jetons

Vous allez également ajouter un point de terminaison de proxy distinct au proxy d'API afin de permettre la création des jetons JWT.

Ajouter un point de terminaison de proxy pour les opérations liées aux jetons

Dans un environnement de production, un proxy distinct est généralement créé pour la génération des jetons. Pour cet atelier, vous allez créer le flux de génération de jetons dans un point de terminaison de proxy distinct au sein du même proxy d'API.

1. Dans le menu de navigation du proxy, dans la section Proxy Endpoints (Points de terminaison du proxy), cliquez sur le bouton +.

   Remarque : Ne cliquez pas sur le bouton "+" à côté de "default" (par défaut).

   Cette opération permet de créer un point de terminaison de proxy, qui sera utilisé lors de la création d'un jeton JWT.

2. Pour Name (Nom), spécifiez token, puis cliquez sur Add (Ajouter).

   Le nouveau point de terminaison de proxy nommé token s'affiche dans le volet Code.

3. Remplacez l'intégralité de la configuration du flux token, qui se présente actuellement ainsi :

   <ProxyEndpoint name="token"> . . . </ProxyEndpoint>

   par :

   <ProxyEndpoint name="token"> <PreFlow name="PreFlow"> <Request/> <Response/> </PreFlow> <PostFlow name="PostFlow"> <Request/> <Response/> </PostFlow> <Flows/> <HTTPProxyConnection> <BasePath>/token</BasePath> </HTTPProxyConnection> <RouteRule name="noTarget"/> </ProxyEndpoint>

4. Cliquez sur Save (Enregistrer).

   Cette modification de la configuration entraîne deux changements spécifiques :

   • La valeur de BasePath est définie sur /token. Il s'agit du chemin de base qui sera utilisé lors de la création d'un jeton.
   • La règle RouteRule ne référence plus de point de terminaison cible. Le proxy d'API crée un jeton sans appeler le service de backend.

Créer un flux pour générer un jeton

1. Dans le flux du proxy, à la section Proxy Endpoints: token (Points de terminaison du proxy : jeton), cliquez sur + juste à côté de /token.

2. Pour le nouveau flux conditionnel, spécifiez les valeurs suivantes :

   Propriété	Valeur
   Flow Name (Nom du flux)	generateToken
   Condition Type (Type de condition)	sélectionnez Custom (Personnalisée)

3. Pour Condition, spécifiez la valeur suivante :

   (proxy.pathsuffix MatchesPath "/") and (request.verb = "POST") and (request.formparam.grant_type = "client_credentials")

   Seules les demandes de jetons d'identifiants client valides seront autorisées.

4. Cliquez sur Add (Ajouter).

Associer la règle AssignMessage pour récupérer la valeur de l'ensemble de propriétés

La règle OAuthV2 qui générera les jetons devra également avoir accès à la variable private.secretkey.

1. Dans le menu de navigation du proxy, dans la section Proxy Endpoints (Points de terminaison du proxy), sous token (jeton), cliquez sur generateToken.

2. Dans le volet Flow (Flux), cliquez sur le bouton + juste à côté de generateToken dans le flux de requête.

3. Pour Select Policy (Sélectionner une règle), choisissez Select existing policy (Sélectionner une règle existante), puis cliquez sur AM-GetSecret.

4. Cliquez sur Add (Ajouter).

   La même règle AssignMessage est associée au PreFlow du point de terminaison du proxy de jeton.

Ajouter une règle OAuthV2 pour générer un jeton

1. Dans le menu de navigation du proxy, dans la section Proxy Endpoints (Points de terminaison du proxy), sous token (jeton), cliquez sur generateToken.

2. Dans le volet Flow (Flux), cliquez sur le bouton + juste à côté de generateToken dans le flux de requête.

3. Pour Select policy (Sélectionner une règle), choisissez Create new policy (Créer une règle), puis OAuth v2.0 dans la section Security (Sécurité). Définissez ensuite les valeurs de Display Name (Nom à afficher) et Name (Nom) sur OA-GenerateToken.

4. Cliquez sur Add (Ajouter), puis sur OA-GenerateToken dans Policies (Règles).

   La configuration de la règle OAuthV2 s'affiche dans le volet Code.

5. Modifiez la configuration de la règle OAuthV2 comme suit :

   <OAuthV2 name="OA-GenerateToken"> <Operation>GenerateJWTAccessToken</Operation> <Algorithm>HS256</Algorithm> <SecretKey> <Value ref="private.secretkey"/> </SecretKey> <SupportedGrantTypes> <!-- pass client_id and client_secret via basic auth header --> <GrantType>client_credentials</GrantType> </SupportedGrantTypes> <!-- 1800000 ms = 1800 s = 30 min --> <ExpiresIn>1800000</ExpiresIn> <GenerateResponse enabled="true"/> <RFCCompliantRequestResponse>true</RFCCompliantRequestResponse> </OAuthV2>

   Cette configuration permettra de créer un jeton JWT OAuth qui expire au bout de 30 minutes.

Générer une erreur en cas de demande de jeton non valide

1. Dans le flux du proxy, à la section Proxy Endpoints: token (Points de terminaison du proxy : jeton), cliquez sur + juste à côté de /token.

2. Pour le nouveau flux conditionnel, spécifiez les valeurs suivantes :

   Propriété	Valeur
   Flow Name (Nom du flux)	invalidRequest
   Condition Type (Type de condition)	sélectionnez Custom (Personnalisée)
   Condition	DELETETHIS

   La condition sera supprimée une fois le flux ajouté, car toute requête generateToken non valide doit passer par ce flux.

3. Cliquez sur Add (Ajouter).

4. Dans le flux invalidRequest, supprimez la ligne suivante :

   <Condition>DELETETHIS</Condition>

5. Dans le menu de navigation du proxy, dans la section Proxy Endpoints (Points de terminaison du proxy), sous token (jeton), cliquez sur invalidRequest.

6. Dans le volet Flow (Flux), cliquez sur le bouton + juste à côté de invalidRequest pour le flux de requête.

7. Sélectionnez Create new policy (Créer une règle), puis, dans la section Mediation (Médiation), sélectionnez Raise Fault (Générer une erreur). Définissez ensuite les valeurs de Display Name (Nom à afficher) et Name (Nom) sur RF-InvalidTokenRequest.

8. Cliquez sur Add (Ajouter), puis sur RF-InvalidTokenRequest dans Policies (Règles).

   La configuration de la règle RaiseFault s'affiche dans le volet Code.

9. Modifiez la configuration de la règle RaiseFault comme suit :

   <RaiseFault name="RF-InvalidTokenRequest"> <FaultResponse> <Set> <StatusCode>400</StatusCode> <ReasonPhrase>Bad Request</ReasonPhrase> <Payload contentType="application/json">{ "error":"Bad request: use POST /token" }</Payload> </Set> </FaultResponse> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </RaiseFault>

   Une réponse 400 Bad Request (Requête erronée) sera générée si la requête n'est pas valide.

10. Cliquez sur Save (Enregistrer).

Cliquez sur Vérifier ma progression pour valider l'objectif. Ajouter des règles pour générer des jetons

Tâche 4 : Déployer le proxy OAuth

Dans cette tâche, vous allez déployer le proxy d'API et confirmer que l'accès nécessite un jeton OAuth.

Vérifier que l'instance d'exécution est disponible

1. Dans Cloud Shell, collez et exécutez l'ensemble de commandes ci-dessous :

   export INSTANCE_NAME=eval-instance; export ENV_NAME=eval; export PREV_INSTANCE_STATE=; echo "waiting for runtime instance ${INSTANCE_NAME} to be active"; while : ; do export INSTANCE_STATE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${GOOGLE_CLOUD_PROJECT}/instances/${INSTANCE_NAME}" | jq "select(.state != null) | .state" --raw-output); [[ "${INSTANCE_STATE}" == "${PREV_INSTANCE_STATE}" ]] || (echo; echo "INSTANCE_STATE=${INSTANCE_STATE}"); export PREV_INSTANCE_STATE=${INSTANCE_STATE}; [[ "${INSTANCE_STATE}" != "ACTIVE" ]] || break; echo -n "."; sleep 5; done; echo; echo "instance created, waiting for environment ${ENV_NAME} to be attached to instance"; while : ; do export ATTACHMENT_DONE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${GOOGLE_CLOUD_PROJECT}/instances/${INSTANCE_NAME}/attachments" | jq "select(.attachments != null) | .attachments[] | select(.environment == \"${ENV_NAME}\") | .environment" --join-output); [[ "${ATTACHMENT_DONE}" != "${ENV_NAME}" ]] || break; echo -n "."; sleep 5; done; echo "***ORG IS READY TO USE***";

   Cette série de commandes utilise l'API Apigee pour déterminer quand l'instance d'exécution Apigee a été créée et l'environnement d'évaluation associé.

2. Attendez que l'instance soit prête.

   Lorsque le texte ***ORG IS READY TO USE*** s'affiche, l'instance est prête. Il se peut que l'organisation Apigee ait été créée avant le début de l'atelier. Dans ce cas, vous n'aurez pas à attendre la création de l'instance.

   Pendant que vous patientez, vous pouvez en apprendre davantage sur OAuth, sur la règle SpikeArrest, sur les solutions pour masquer et ne pas afficher des données, ainsi que sur les jetons opaques et les JWT.

Déployer le proxy d'API

1. Accédez à Apigee dans la console Cloud.

2. Dans le menu de navigation de gauche, sélectionnez Proxy development > API Proxies (Développement de proxys > Proxys d'API), puis cliquez sur bank-v1.

3. Cliquez sur l'onglet Develop (Développer).

4. Cliquez sur Deploy (Déployer), puis sélectionnez eval pour Environment (Environnement).

   Une boîte de dialogue vous invite à confirmer le déploiement.

5. Pour Service account (Compte de service), spécifiez l'adresse e-mail du compte de service :

   apigee-internal-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

6. Cliquez sur Deploy (Déployer), puis sur Confirm (Confirmer).

7. Cliquez sur l'onglet Overview (Vue d'ensemble) et attendez que l'état du déploiement eval indique que le proxy a été déployé.

Cliquez sur Vérifier ma progression pour valider l'objectif. Déployer le proxy d'API

Tester le proxy d'API

L'environnement d'évaluation de l'organisation Apigee peut être appelé à l'aide du nom d'hôte eval.example.com. L'entrée DNS pour ce nom d'hôte a été créée dans votre projet et elle est résolue en adresse IP de l'instance d'exécution Apigee. Cette entrée DNS a été créée dans une zone privée, ce qui signifie qu'elle n'est visible que sur le réseau interne.

Cloud Shell ne réside pas sur le réseau interne. Par conséquent, les commandes Cloud Shell ne peuvent pas résoudre cette entrée DNS. Une machine virtuelle (VM) de votre organisation peut accéder au DNS de la zone privée. Une VM nommée apigeex-test-vm a été créée automatiquement : vous pouvez l'utiliser pour appeler le proxy d'API.

1. Dans Cloud Shell, ouvrez une connexion SSH vers votre VM de test :

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   Si vous êtes invité à donner votre autorisation, cliquez sur Autoriser.

2. Pour chaque question posée dans Cloud Shell, cliquez sur Entrée ou Retour pour spécifier la valeur par défaut.

   L'identité avec laquelle vous êtes connecté est propriétaire du projet. La connexion SSH à cette machine est donc autorisée.

   Votre session Cloud Shell s'exécute désormais dans la VM.

3. Appelez le proxy d'API bank-v1 déployé dans l'environnement eval :

   curl -i -k -X GET "https://eval.example.com/bank/v1/customers"

   L'option -k indique à curl d'ignorer la vérification du certificat TLS. Pour cet atelier, l'environnement d'exécution Apigee utilise un certificat autosigné au lieu d'un certificat créé par une autorité de certification (CA) de confiance.

   Remarque : Vous ne devez pas utiliser l'option -k pour contourner la vérification des certificats dans les cas d'utilisation en production.

   Cette API tente de récupérer une liste de clients. Vous devriez maintenant voir une réponse 401 Unauthorized (non autorisé) semblable à celle-ci :

   HTTP/2 401 content-type: application/json www-authenticate: Bearer realm="null",error="invalid_token",error_description="oauth.v2.InvalidAccessToken: Invalid access token" x-request-id: 99263881-d0f7-4495-b886-0253f28a2e05 content-length: 101 date: Tue, 11 Jan 2022 18:59:01 GMT via: 1.1 google {"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}

   Cette réponse indique que le proxy d'API a bloqué l'accès au service de backend, car le jeton d'accès n'a pas été fourni.

4. Saisissez la commande exit pour quitter la session SSH et revenir à Cloud Shell.

Tâche 5 : Ajouter un produit d'API, un développeur et une application

Dans cette tâche, vous allez ajouter un produit d'API qui fournira l'accès à votre API. Vous allez également créer un développeur, puis une application qui sera associée à votre produit d'API.

Créer un produit d'API

1. Accédez à Apigee dans la console Cloud.

2. Dans le menu de navigation de gauche, sélectionnez Distribution > API Products (Distribution > Produits d'API).

3. Pour créer un produit d'API, cliquez sur +Create (+ Créer).

4. Dans le volet Product details (Informations sur le produit), spécifiez les éléments suivants :

   Propriété	Valeur
   Name (Nom)	bank-readonly
   Display Name (Nom à afficher)	bank (accès en lecture)
   Environment (Environnement)	sélectionnez eval
   Access (Accès)	sélectionnez Public

   Laissez l'option Automatically approve access requests (Approuver automatiquement les demandes d'accès) sélectionnée.

5. Dans la section Operations (Opérations), cliquez sur +Add an Operation (+ Ajouter une opération).

   Les opérations permettent de spécifier les requêtes dans lesquelles les proxys d'API sont autorisés pour une application associée au produit d'API.

   Remarque : Assurez-vous que le bouton se trouve dans la section "Operations" (Opérations) et non dans la section "GraphQL Operations" (Opérations GraphQL).

6. Renseignez les champs suivants :

   Propriété	Valeur
   Proxy d'API	sélectionnez le proxy d'API bank-v1
   Path (Chemin)	/**
   Methods (Méthodes)	sélectionnez GET

   L'expression de chemin /\*\* indique que toute requête correspondant au chemin de base sera autorisée.

   Dans un environnement de production, vous pouvez choisir d'ajouter chaque opération autorisée séparément, plutôt que d'utiliser cette expression de chemin avec caractère générique.

7. Cliquez sur Save (Enregistrer) pour enregistrer l'opération.

8. Pour enregistrer le produit d'API, cliquez sur Save (Enregistrer) en haut de la page Products Detail (Informations sur le produit).

9. Revenez à la page Distribution > API Products (Distribution > Produits d'API).

   Le produit d'API s'affiche.

Créer un développeur d'applications

Avant de créer une application, vous devez créer un développeur d'applications.

1. Dans le menu de navigation de gauche, cliquez sur Distribution > Developers (Distribution > Développeurs).

2. Pour créer un développeur d'applications, cliquez sur +Create (+ Créer).

3. Renseignez les champs suivants :

   Propriété	Valeur
   First Name (Prénom)	Joe
   Last Name (Nom)	Developer
   Username (Nom d'utilisateur)	joe
   Email (E-mail)	joe@example.com

4. Cliquez sur Add (Ajouter) pour créer le développeur d'applications.

Créer une application avec accès à bank-v1

1. Dans le menu de navigation de gauche, cliquez sur Distribution > Apps (Distribution > Applications).

2. Pour créer une application, cliquez sur +Create (+ Créer).

3. Dans le volet App details (Informations sur l'application), spécifiez les éléments suivants :

   Propriété	Valeur
   Name (Nom)	readonly-app
   Developer (Développeur)	selectionnez joe@example.com

4. Dans le volet Credentials (Identifiants), cliquez sur Add credentials > Add products (Ajouter des identifiants > Ajouter des produits). Dans le menu déroulant, sélectionnez bank (read access) (bank (accès en lecture)), puis cliquez sur Add (Ajouter).

5. En haut à droite, cliquez sur Create (Créer) pour créer l'application.

   La clé et le secret de l'application sont désormais configurés.

6. Cliquez sur les icônes Show (Afficher) à côté de Key (Clé) et Secret.

   Cette API exige un jeton d'accès OAuth. La clé et le secret serviront d'identifiants pour l'application, ce qui lui permettra de créer un jeton d'accès OAuth.

Cliquez sur Vérifier ma progression pour valider l'objectif. Ajouter le produit d'API et créer une application

Tester l'API

1. Dans Cloud Shell, ouvrez une connexion SSH vers votre VM de test :

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   Si vous êtes invité à donner votre autorisation, cliquez sur Autoriser.

   Votre session Cloud Shell s'exécute désormais dans la VM.

2. Afin d'obtenir la clé et le secret client de l'application, exécutez les commandes suivantes :

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null); echo "PROJECT_ID=${PROJECT_ID}" export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output); echo "CONSUMER_KEY=${CONSUMER_KEY}" export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output); echo "CONSUMER_SECRET=${CONSUMER_SECRET}"

   La première commande lit la configuration gcloud pour obtenir le projet actuel. Les deuxième et troisième commandes récupèrent la clé et le secret client à l'aide de l'API Apigee. La requête est autorisée, car vous envoyez un jeton d'accès qui dispose des autorisations de l'utilisateur connecté.

   Pour le type d'attribution des identifiants client OAuth, l'application cliente doit envoyer la clé et le secret client dans un en-tête d'autorisation afin de générer un jeton d'accès.

3. Pour générer un jeton d'accès JWT, exécutez la commande suivante :

   export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials"); echo ${TOKEN_RESPONSE} export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output); echo "JWT_TOKEN=${JWT_TOKEN}"

   La première commande appelle le point de terminaison du jeton et enregistre la réponse. Le jeton est ensuite extrait de la réponse JSON et stocké dans JWT_TOKEN.

4. Pour tester une requête utilisant ce jeton JWT, exécutez la commande suivante :

   curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/customers"

   L'appel d'API devrait maintenant renvoyer une liste de clients.

   Remarque : Si vous obtenez comme réponse "Your client does not have permission to the requested URL" (Votre client n'est pas autorisé à accéder à l'URL demandée), vérifiez que l'audience a été correctement définie lors de la tâche 1.

5. Saisissez la commande exit pour quitter la session SSH et revenir à Cloud Shell.

Tâche 6 : Ajouter une limitation du débit

Dans cette tâche, vous allez ajouter une règle SpikeArrest qui utilisera la configuration de quota du produit d'API pour limiter le débit des appels d'API.

La règle SpikeArrest protège vos API et vos backends contre les surcharges de trafic en vous permettant de spécifier un débit de trafic maximal autorisé. Vous pouvez utiliser cette règle pour veiller à ce que votre backend ne soit pas submergé par un volume de trafic qu'il n'est pas en mesure de gérer.

Ajouter une règle SpikeArrest pour la génération de jetons

Cette règle SpikeArrest spécifiera une limite de débit globale pour le trafic correspondant aux appels à l'API /token.

1. Accédez à Apigee dans la console Cloud.

2. Dans le menu de navigation de gauche, sélectionnez Proxy development > API Proxies (Développement de proxys > Proxys d'API), puis cliquez sur bank-v1.

3. Cliquez sur l'onglet Develop (Développer).

4. Dans le menu de navigation du proxy, dans la section Proxy Endpoints (Points de terminaison du proxy), sous token (jeton), cliquez sur PreFlow.

   La règle SpikeArrest doit s'exécuter avant les règles de flux conditionnel.

5. Dans le volet Flow (Flux), cliquez sur le bouton + juste à côté de PreFlow dans le flux de requête.

6. Sélectionnez Create new policy (Créer une règle), puis, dans la section Traffic Management (Gestion du trafic), sélectionnez SpikeArrest. Définissez ensuite les valeurs de Display Name (Nom à afficher) et Name (Nom) sur SA-LimitTokenRate.

7. Cliquez sur Add (Ajouter), puis sur SA-LimitTokenRate dans la section Policies (Règles).

   La configuration de la règle SpikeArrest s'affiche dans le volet Code.

8. Modifiez la configuration de la règle SpikeArrest comme suit :

   <SpikeArrest name="SA-LimitTokenRate"> <Rate>5pm</Rate> <UseEffectiveCount>false</UseEffectiveCount> </SpikeArrest>

   La configuration spécifie un débit de requêtes maximal autorisé de cinq par minute. Tout le trafic sera limité par cette règle SpikeArrest.

   Remarque : Nous utilisons ici une limite de cinq requêtes par minute pour faciliter les tests. Les limites SpikeArrest utilisées dans cet atelier sont typiquement trop faibles pour des scénarios réels.

   Si UseEffectiveCount est défini sur "false", cela signifie que la règle SpikeArrest utilise l'algorithme Token Bucket (seau à jetons). Le trafic est lissé en rapportant le débit à des intervalles plus courts : un débit de cinq requêtes par minute correspond à une requête par cinquième de minute, soit une requête toutes les 12 secondes. Si une deuxième requête est envoyée à un processeur de messages moins de 12 secondes après la précédente, elle peut être refusée.

Ajouter une règle SpikeArrest pour les requêtes API

Cette règle SpikeArrest spécifie une limite de débit pour le trafic correspondant aux appels à l'API /bank/v1. Ce débit sera appliqué individuellement à chaque application.

1. Dans le menu de navigation du proxy, dans la section Proxy Endpoints (Points de terminaison du proxy), sous default (par défaut), cliquez sur PreFlow.

   La règle SpikeArrest doit s'exécuter au début de l'appel, mais après la règle OAuthV2 VerifyJWTAccessToken afin de limiter le débit en fonction de l'application.

2. Dans le volet Flow (Flux), cliquez sur le bouton + juste à côté de PreFlow dans le flux de requête.

3. Sélectionnez Create new policy (Créer une règle), puis, dans la section Traffic Management (Gestion du trafic), sélectionnez SpikeArrest. Définissez ensuite les valeurs de Display Name (Nom à afficher) et Name (Nom) sur SA-LimitRateByApp.

4. Cliquez sur Add (Ajouter), puis sur SA-LimitRateByApp dans la section Policies (Règles).

   La configuration de la règle SpikeArrest s'affiche dans le volet Code.

5. Modifiez la configuration de la règle SpikeArrest comme suit :

   <SpikeArrest name="SA-LimitRateByApp"> <Rate>5pm</Rate> <Identifier ref="client_id" /> <UseEffectiveCount>true</UseEffectiveCount> </SpikeArrest>

   Comme pour la règle précédente, la configuration spécifie un débit de requêtes maximal autorisé de cinq par minute. Toutefois, cette règle spécifie un élément Identifier (Identifiant), qui gère une valeur de débit SpikeArrest distincte pour chaque client_id. L'ID client est renseigné par la règle OA-VerifyToken et est unique pour chaque application de développeur.

   Si UseEffectiveCount est défini sur "true", cela signifie que le débit est calculé pour l'ensemble du trafic de la région. La règle gère un compteur des requêtes reçues au cours d'une période, dont la durée est d'une minute lorsque vous utilisez un débit de requêtes par minute. Le calcul du débit est basé sur une fenêtre glissante.

   

   Dans l'exemple ci-dessus, supposons que nous utilisons un débit de 50 requêtes par minute. Les compteurs sont ici basés sur une période d'une minute. Notons que, si le débit avait été spécifié par seconde, la période du compteur serait alors d'une seconde. Supposons que 10 secondes se soient déjà écoulées dans la minute en cours, représentée par la flèche. Pour la minute précédente, le décompte était de 48 requêtes, et la période actuelle en compte jusqu'à présent 5.

   Pour autoriser une autre requête, le débit doit rester inférieur à 50 requêtes par minute. Le calcul du débit s'effectue comme suit :

   request_rate = (48 * (60-10)/60) + 6 = 46

   Seulement 10 secondes sur 60 se sont écoulées au cours de la période actuelle. Par conséquent, les 50 autres secondes sont calculées à partir du débit de la période précédente. 5/6 de 48 nous donne 40. Si une requête était autorisée, le décompte de requêtes pour la période actuelle serait de 5 + 1, soit 6. Le calcul du débit de requêtes request_rate, dont la valeur vaut 46, indique que la requête est autorisée, car le débit reste inférieur à 50 requêtes par minute.

6. Cliquez sur Save > Save as New Revision (Enregistrer > Enregistrer en tant que nouvelle révision).

7. Cliquez sur Deploy (Déployer), puis sélectionnez eval pour Environment (Environnement).

8. Pour Service account (Compte de service), spécifiez l'adresse e-mail du compte de service :

apigee-internal-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

9. Cliquez sur Deploy (Déployer), puis sur Confirm (Confirmer).
10. Cliquez sur l'onglet Overview (Vue d'ensemble) et attendez que l'état du déploiement eval indique que le proxy a été déployé.

Cliquez sur Vérifier ma progression pour valider l'objectif. Ajouter la règle SpikeArrest

Tester la limitation du débit

1. Dans Cloud Shell, ouvrez une connexion SSH vers votre VM de test :

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   Si vous êtes invité à donner votre autorisation, cliquez sur Autoriser.

   Votre session Cloud Shell s'exécute désormais dans la VM.

2. Afin d'obtenir la clé et le secret client de l'application, exécutez les commandes suivantes :

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null); echo "PROJECT_ID=${PROJECT_ID}" export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output); echo "CONSUMER_KEY=${CONSUMER_KEY}" export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output); echo "CONSUMER_SECRET=${CONSUMER_SECRET}"

3. Générez plusieurs jetons d'accès en exécutant plusieurs fois la commande suivante :

   curl -i -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials"

   Vous devriez rapidement recevoir une réponse 429 Too Many Requests (Trop de requêtes), indiquant que le débit maximal a été dépassé. Comme UseEffectiveCount est défini sur "false" pour cette règle, le lissage du trafic s'effectue à l'aide de l'algorithme Token Bucket (seau à jetons). L'erreur déclenchée pour l'arrêt de pics interviendra probablement avant votre cinquième requête.

4. Pour enregistrer un jeton d'accès JWT, exécutez la commande suivante :

   export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials"); echo ${TOKEN_RESPONSE} export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output); echo "JWT_TOKEN=${JWT_TOKEN}"

5. Afin de tester la règle SpikeArrest pour les appels d'API, envoyez à plusieurs reprises la commande suivante :

   curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/customers"

   Comme UseEffectiveCount est défini sur "true", cette règle utilise l'algorithme de fenêtre glissante. Vous devriez pouvoir envoyer cinq requêtes qui seront acceptées avant qu'un blocage intervienne.

6. Saisissez la commande exit pour quitter la session SSH et revenir à Cloud Shell.

Tâche 7 : Masquage des données

Dans cette tâche, vous allez créer un masque de données afin de cacher certains champs dans une session de débogage.

Démarrer une session de débogage

Debug est un outil permettant de dépanner et de surveiller les proxys d'API exécutés sur Apigee. Vous pouvez l'utiliser pour examiner les détails de chaque étape lors d'un appel d'API.

1. Dans le menu de navigation de gauche, sélectionnez Proxy development > API Proxies (Développement de proxys > Proxys d'API), puis cliquez sur bank-v1.

2. Cliquez sur l'onglet Debug (Débogage).

3. Dans le volet Start debug session (Démarrer une session de débogage), cliquez sur Start debug session (Démarrer une session de débogage). Dans le menu déroulant de l'environnement, sélectionnez eval.

4. Cliquez sur Start (Démarrer).

   Il peut s'écouler un court laps de temps avant que la session de débogage ne commence à capturer les requêtes.

   Remarque : Si des messages d'erreur s'affichent dans des encadrés rouges en haut de l'écran, avec des descriptions telles que "Error fetching debug transactions" (Erreur lors de la récupération des transactions de débogage) ou "List debug session transaction error" (Erreur de transaction List Debug Session), il est possible que votre session de débogage fonctionne toujours correctement.

   Vous allez envoyer des requêtes d'API, puis examiner la session de débogage.

Déboguer une requête

1. Dans Cloud Shell, ouvrez une connexion SSH vers votre VM de test :

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   Si vous êtes invité à donner votre autorisation, cliquez sur Autoriser.

   Votre session Cloud Shell s'exécute désormais dans la VM.

2. Afin d'obtenir le jeton pour l'application, exécutez les commandes suivantes :

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null); echo "PROJECT_ID=${PROJECT_ID}" export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output); echo "CONSUMER_KEY=${CONSUMER_KEY}" export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output); echo "CONSUMER_SECRET=${CONSUMER_SECRET}" export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials"); echo ${TOKEN_RESPONSE} export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output); echo "JWT_TOKEN=${JWT_TOKEN}"

3. Envoyez la requête suivante à l'API :

   curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/customers/abe@example.org/accounts"

4. Revenez à la page de l'interface utilisateur d'Apigee.

   La page "Debug" (Debogage) doit afficher deux requêtes : une requête POST (génération du jeton) et une requête GET (récupération des comptes d'un utilisateur).

5. Cliquez sur la requête GET.

   Les détails de la requête GET s'affichent.

6. Cliquez sur la première règle, c'est-à-dire la règle AM-GetSecret qui copie la variable propertyset.oauth.secret dans la variable private.secretkey.

   

   Les détails de la phase n'affichent pas la variable privée, car les variables incluant le préfixe "private." sont masquées dans la session de débogage. Toutefois, la variable de l'ensemble de propriétés contient les mêmes données sensibles. Il peut donc être judicieux de la masquer pour les utilisateurs qui effectuent le débogage du trafic.

7. Cliquez sur la réponse du backend, indiquée par le cercle à gauche de l'icône d'usine.

   

   La réponse contient les comptes (y compris leur solde) de l'utilisateur.

Créer un masque de débogage

1. Ouvrez un nouvel onglet dans la même fenêtre de navigateur et accédez à la documentation de référence de l'API Apigee.

   La documentation de référence de l'API Apigee fournit des informations détaillées sur les différents appels d'API pouvant être utilisés pour gérer Apigee, mais aussi pour appeler l'API Apigee elle-même. Cette page affiche les appels à l'API organization.environments.

2. Faites défiler la page jusqu'en bas, puis cliquez sur updateDebugmask.

   Cet appel d'API mettra à jour le masque de débogage pour l'environnement.

3. Dans le volet Try this API (Essayer cette API), pour le paramètre de requête name (nom), utilisez l'élément suivant :

   organizations/{{{ project_0.project_id | PROJECT }}}/environments/eval/debugmask

4. Comme corps de la requête, saisissez les éléments suivants :

   { "responseJSONPaths": [ "$[*].balance" ], "variables": [ "propertyset.oauth.secret" ] }

   Cette définition assure le masquage de la variable propertyset.oauth.secret, ainsi que de chaque champ balance dans le tableau d'objets de la charge utile de la réponse.

5. Cliquez sur Execute (Exécuter).

   Si une fenêtre pop-up vous demande de choisir votre compte, sélectionnez le compte étudiant.

6. Cliquez sur Allow (Autoriser) pour autoriser la page à utiliser les identifiants de l'élève.

Tester le masque de débogage

1. Dans le menu de navigation de gauche de l'UI Apigee, sélectionnez Proxy development > API Proxies (Développement de proxys > Proxys d'API), puis cliquez sur bank-v1.

2. Cliquez sur l'onglet Debug (Débogage).

3. Dans le volet Start debug session (Démarrer une session de débogage), dans le menu déroulant de l'environnement, sélectionnez eval.

4. Cliquez sur Start (Démarrer).

5. Dans Cloud Shell, si la connexion SSH a été fermée, ouvrez une connexion SSH vers votre VM de test :

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

6. Obtenez un jeton et envoyez à nouveau la requête API :

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null) export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output) export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output) export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials") export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output) curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/customers/abe@example.org/accounts"

7. Revenez à la page "Debug" (Debogage) dans l'interface utilisateur d'Apigee, puis cliquez sur la requête GET.

8. Cliquez sur la règle AM-GetSecret.

   La variable propertyset.oauth.secret est masquée.

   

9. Cliquez sur Proxy Response Flow Started (Flux de réponse du proxy démarré) pour afficher la réponse du backend.

   Chaque champ balance est masqué.

   

Tâche 8 : Gestion des exceptions

Dans cette tâche, vous allez créer un flux conditionnel par défaut afin de restreindre les appels à des ressources de backend spécifiques et vous réécrirez un message d'erreur de backend.

Tester l'API

1. Dans Cloud Shell, si la connexion SSH a été fermée, ouvrez une connexion SSH vers votre VM de test :

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

2. Saisissez Y pour continuer, puis appuyez deux fois sur ENTRÉE pour laisser la phrase secrète vide.

3. Obtenez un jeton et envoyez une requête GET à /users :

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null) export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output) export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output) export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials") export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output) curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/users"

   Le service de backend ne reconnaît pas la requête GET /users. Il renvoie donc une réponse 404 semblable à celle-ci :

   HTTP/2 404 x-powered-by: Express content-security-policy: default-src 'none' x-content-type-options: nosniff content-type: text/html; charset=utf-8 x-cloud-trace-context: 7e96528757cc5053ba4fc8853037b02d;o=1 date: Wed, 19 Jan 2022 01:49:53 GMT server: Google Frontend content-length: 144 x-request-id: 2d8c8002-3152-4fc2-a60b-1729dd5483d8 via: 1.1 google <!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <title>Error</title> </head> <body> <pre>Cannot GET /users</pre> </body> </html>

   La réponse renvoie une charge utile HTML, qui ne correspond pas au format de la charge utile RF-InvalidTokenRequest. De plus, une réponse de backend peut contenir des données sensibles. C'est pourquoi il est recommandé de réécrire les réponses d'erreur obtenues des services de backend.

Réécrire une erreur 404 "Not Found"

Les règles d'erreur peuvent être utilisées pour détecter les erreurs et réécrire les messages d'erreur.

Une règle RaiseFault sera utilisée pour définir la nouvelle réponse.

1. Accédez à Apigee dans la console Cloud.

2. Dans le menu de navigation de gauche, sélectionnez Proxy development > API Proxies (Développement de proxys > Proxys d'API), puis cliquez sur bank-v1.

3. Cliquez sur l'onglet Develop (Développer).

4. Dans le menu de navigation du proxy, cliquez sur + à côté de Policies (Règles).

5. Dans la section Mediation (Médiation), sélectionnez Raise Fault (Générer une erreur), puis définissez les valeurs de Display Name (Nom à afficher) et Name (Nom) sur RF-404NotFound.

6. Cliquez sur Create (Créer). Cliquez sur RF-404NotFound dans la section Policies (Règles).

7. Modifiez la configuration de la règle RaiseFault comme suit :

   <RaiseFault name="RF-404NotFound"> <FaultResponse> <Remove> <Headers/> </Remove> <Set> <StatusCode>404</StatusCode> <ReasonPhrase>Not Found</ReasonPhrase> <Headers> <Header name="FaultName">{fault.name}</Header> </Headers> <Payload contentType="application/json">{ "error": "{request.verb} {proxy.pathsuffix} not found" }</Payload> </Set> </FaultResponse> <AssignTo createNew="true" type="response"/> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </RaiseFault>

   La section Remove supprime d'abord tous les en-têtes qui peuvent provenir du service de backend, puis la section Set crée la réponse. L'en-tête FaultName a été ajouté pour afficher la valeur de la variable fault.name lorsque l'erreur est générée. La variable fault.name spécifie le nom de l'erreur.

Créer la règle d'erreur FaultRule

1. Dans le menu de navigation du proxy, dans la section Target Endpoints (Points de terminaison cibles), cliquez sur default (par défaut).

   Le point de terminaison cible par défaut contient l'appel cible du backend qui renvoie la réponse 404. Un code 404 est traité comme un code d'échec. Le point de terminaison génère une erreur, et les règles FaultRule spécifiées dans le point de terminaison cible peuvent être utilisées pour réécrire la réponse de l'API.

2. Dans la configuration TargetEndpoint, immédiatement sous la balise TargetEndpoint, ajoutez la section FaultRules suivante :

   <FaultRules> <FaultRule name="404"> <Step> <Name>RF-404NotFound</Name> </Step> <Condition>response.status.code == 404</Condition> </FaultRule> </FaultRules>

   Le début de l'élément TargetEndpoint doit maintenant ressembler à ceci :

   <TargetEndpoint name="default"> <FaultRules> <FaultRule name="404"> <Step> <Name>RF-404NotFound</Name> </Step> <Condition>response.status.code == 404</Condition> </FaultRule> </FaultRules>

3. Cliquez sur Save > Save as New Revision (Enregistrer > Enregistrer en tant que nouvelle révision).

4. Cliquez sur Deploy (Déployer), puis sélectionnez eval pour Environment (Environnement).

5. Pour Service account (Compte de service), spécifiez l'adresse e-mail du compte de service :

   apigee-internal-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

6. Cliquez sur Deploy (Déployer), puis sur Confirm (Confirmer).

7. Cliquez sur l'onglet Overview (Vue d'ensemble) et attendez que l'état du déploiement eval indique que le proxy a été déployé.

Tester l'erreur de réponse du point de terminaison

1. Dans Cloud Shell, si la connexion SSH a été fermée, ouvrez une connexion SSH vers votre VM de test :

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

2. Obtenez un jeton et envoyez une requête GET à /users :

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null) export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output) export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output) export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials") export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output) curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/users"

   La réponse a été réécrite et ressemble désormais à ceci :

   HTTP/2 404 faultname: ErrorResponseCode content-type: application/json x-request-id: 8d9db301-b3c7-4957-816d-93e796306dfb content-length: 39 date: Tue, 18 Jan 2022 06:42:23 GMT via: 1.1 google { "error": "GET /users not found" }

   La réponse est désormais au format JSON. Notez que l'en-tête faultname possède la valeur ErrorResponseCode, qui correspond à la valeur de la variable fault.name spécifiée lorsque la cible renvoie un code d'échec. Dès que la réponse 404 est renvoyée par le service de backend, une erreur est générée et les règles d'erreur du point de terminaison cible sont évaluées. La règle d'erreur 404 a ensuite réécrit la réponse.

Ajouter un flux conditionnel 404

Au lieu de compter sur le backend pour renvoyer une réponse lorsqu'une requête inattendue est envoyée, un nouveau flux conditionnel peut être ajouté à la fin des flux conditionnels du point de terminaison du proxy pour générer une erreur lorsqu'il n'y a aucune correspondance avec les conditions des autres flux conditionnels. Cela garantit que seules les opérations listées dans les flux conditionnels seront transmises au backend. Ce modèle vous permet d'autoriser l'accès à un sous-ensemble des ressources du service de backend uniquement.

1. Dans le menu de navigation du proxy, accédez à Proxy endpoint: default (Point de terminaison du proxy : par défaut) puis, dans la section du flux, cliquez sur + à côté de /bank/v1.

2. Pour le nouveau flux conditionnel, spécifiez les valeurs suivantes :

   Propriété	Valeur
   Flow name (Nom du flux)	404NotFound
   Condition type (Type de condition)	sélectionnez Custom (Personnalisée)
   Condition	DELETETHIS

3. Cliquez sur Add (Ajouter).

4. Dans le flux 404NotFound, supprimez la ligne suivante :

   <Condition>DELETETHIS</Condition>

   Si aucune des conditions de flux conditionnel précédentes ne correspond, le flux 404NotFound s'exécute.

5. Dans le menu de navigation du proxy, dans la section Proxy Endpoints (Points de terminaison du proxy), sous default (par défaut), cliquez sur 404NotFound.

6. Dans le volet Flow (Flux), cliquez sur le bouton + juste à côté du flux de requête 404NotFound.

7. Pour Select Policy (Sélectionner une règle), choisissez Select existing policy (Sélectionner une règle existante), puis cliquez sur RF-404NotFound.

8. Cliquez sur Add (Ajouter).

9. Cliquez sur Save > Save as New Revision (Enregistrer > Enregistrer en tant que nouvelle révision).

10. Cliquez sur Deploy (Déployer), puis sélectionnez eval pour Environment (Environnement).

11. Pour Service account (Compte de service), spécifiez l'adresse e-mail du compte de service :

    apigee-internal-access@{{{ project_0.project_id | PROJECT }}}.iam.gserviceaccount.com

12. Cliquez sur Deploy (Déployer), puis sur Confirm (Confirmer).

13. Cliquez sur l'onglet Overview (Vue d'ensemble) et attendez que l'état du déploiement eval indique que le proxy a été déployé.

Cliquez sur Vérifier ma progression pour valider l'objectif. Ajouter la gestion des exceptions

Tester le flux conditionnel 404

1. Dans Cloud Shell, si la connexion SSH a été fermée, ouvrez une connexion SSH vers votre VM de test :

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

2. Obtenez un jeton et envoyez une requête GET à /users :

   export PROJECT_ID=$(gcloud config list --format 'value(core.project)' 2>/dev/null) export CONSUMER_KEY=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerKey" --raw-output) export CONSUMER_SECRET=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/developers/joe@example.com/apps/readonly-app" | jq ".credentials[0].consumerSecret" --raw-output) export TOKEN_RESPONSE=$(curl -k -u "${CONSUMER_KEY}:${CONSUMER_SECRET}" -X POST "https://eval.example.com/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials") export JWT_TOKEN=$(echo ${TOKEN_RESPONSE} | jq ".access_token" --raw-output) curl -i -k -H "Authorization: Bearer ${JWT_TOKEN}" -X GET "https://eval.example.com/bank/v1/users"

   La réponse a été réécrite et ressemble désormais à ceci :

   HTTP/2 404 faultname: RaiseFault content-type: application/json x-request-id: d6bbd48f-65bd-4551-9236-636fad03a609 content-length: 39 date: Tue, 18 Jan 2022 07:07:58 GMT via: 1.1 google alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000 { "error": "GET /users not found" }

   L'en-tête faultname a désormais la valeur RaiseFault, qui correspond à la valeur fault.name utilisée lorsqu'une règle RaiseFault a provoqué l'erreur. La réponse a été générée par la règle RaiseFault dans le flux conditionnel 404NotFound.

Félicitations !

Dans cet atelier, vous avez sécurisé une API en exigeant un jeton OAuth JWT. Vous avez limité le trafic en ajoutant des règles SpikeArrest. Vous avez utilisé des variables privées et le masquage des données afin de cacher les données sensibles dans les sessions de débogage. Vous avez également réécrit un message d'erreur de backend et utilisé un flux conditionnel 404 pour limiter à des ressources spécifiques les appels au backend.

Étapes suivantes et informations supplémentaires

• OAuth
• Règle SpikeArrest
• Masquer et ne pas afficher des données
• Jetons opaques et JWT
• Gestion des erreurs

Dernière mise à jour du manuel : 6 août 2025

Dernier test de l'atelier : 6 août 2025

Copyright 2026 Google LLC. Tous droits réservés. Google et le logo Google sont des marques de Google LLC. Tous les autres noms d'entreprises et de produits peuvent être des marques des entreprises auxquelles ils sont associés.