Vidéo : visionnez cette courte vidéo pour une introduction à la sécurisation de votre API.
Points abordés
Dans ce tutoriel, vous allez apprendre à effectuer les opérations suivantes :
Créer un proxy d'API qui nécessite une clé API
Créer un produit d'API, un développeur et une application de développeur
Appeler votre API avec une clé API
Il est important de protéger votre API contre tout accès non autorisé. Pour ce faire, vous pouvez utiliser des clés API.
Lorsqu'une application envoie une requête à un proxy d'API configuré pour valider une clé API, elle doit fournir une clé valide. Lors de l'exécution, la règle VerifyAPIKey vérifie que la clé API fournie :
est valide ;
n'a pas été révoquée ;
correspond à la clé API du produit d'API qui expose les ressources demandées.
Si la clé est valide, la requête est autorisée. Si elle n'est pas valide, la requête entraîne un échec d'autorisation.
Sélectionnez votre organisation dans le menu déroulant en haut à gauche de l'UI.
Cliquez sur Develop > API Proxies (Développer > Proxys d'API) pour afficher la liste des proxys d'API.
Cliquez sur Créer.
Dans l'assistant Créer un proxy, sélectionnez Proxy inverse (le plus courant).
Configurez le proxy comme suit :
Dans ce champ
procédez comme suit
Nom du proxy
Saisissez : helloworld_apikey
Chemin de base du projet
Remplacez par : /helloapikey
Le chemin de base du projet fait partie de l'URL utilisée pour envoyer des requêtes au proxy d'API.
Description
Saisissez : hello world protected by API key
Cible (API existante)
Saisissez : http://mocktarget.apigee.net
Cela définit l'URL cible qu'Apigee appelle sur une requête adressée au proxy d'API. Cette cible renvoie une réponse simple : Hello, Guest!.
Cliquez sur Suivant.
Sur la page Common policies (Règles communes), sélectionnez API Key (Clé API).
Cette option ajoute automatiquement deux règles à votre proxy d'API et crée un produit d'API nécessaire pour générer la clé API.
Cliquez sur Suivant.
Sur la page "Summary" (Résumé), assurez-vous qu'un environnement de déploiement est sélectionné, puis cliquez sur Create and deploy (Créer et déployer).
Cliquez sur Edit proxy (Modifier le proxy) pour afficher la page "Overview" (Présentation) du proxy d'API.
Afficher les règles
Dans l'éditeur de proxy d'API, cliquez sur l'onglet Développer. Vous verrez que deux règles ont été ajoutées au flux de requêtes du proxy d'API :
Vérifier la clé API : vérifie l'appel d'API pour s'assurer qu'une clé API valide est présente (envoyée en tant que paramètre de requête).
Supprimer le paramètre de requête apikey : règle AssignMessage qui supprime la clé API une fois la vérification terminée, afin qu'elle ne soit pas transmise et exposée inutilement.
Cliquez sur l'icône de la règle VerifyAPIKey dans la vue de flux, puis examinez la configuration XML de la règle dans la vue de code inférieure. L'élément <APIKey> indique à la règle où elle doit rechercher la clé API lors de l'appel. Par défaut, elle recherche la clé sous la forme d'un paramètre de requête appelé apikey dans la requête HTTP :
<APIKey ref="request.queryparam.apikey" />
Le nom apikey est arbitraire et peut être n'importe quelle propriété contenant la clé API.
Essayer d'appeler l'API
Au cours de cette étape, vous allez effectuer un appel d'API directement au service cible qui réussit, puis un appel infructueux au proxy d'API pour voir comment il est protégé par les règles.
Opération réussie
Dans un navigateur Web, accédez à l'adresse suivante. Le proxy d'API est configuré pour transférer la requête à ce service cible, mais vous allez l'appeler directement pour le moment :
http://mocktarget.apigee.net
Vous devriez obtenir cette réponse indiquant que l'opération a réussi : Hello, Guest!
Sans la règle VerifyAPIKey, cet appel fournirait la même réponse que l'appel précédent. Toutefois, dans ce cas, vous devriez obtenir le message d'erreur suivant :
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}
ce qui signifie que vous n'avez pas transmis de clé API valide (en tant que paramètre de requête).
Au cours des étapes suivantes, vous obtiendrez la clé API requise.
Ajouter un produit API
Pour ajouter un produit API à l'aide de l'interface utilisateur Apigee, procédez comme suit :
Sélectionnez Publier > Produits API.
Cliquez sur +Create (Créer).
Saisissez les détails du produit API.
Champ
Description
Nom
Nom interne du produit d'API. Ne spécifiez pas de caractères spéciaux dans le nom. Remarque : Vous ne pouvez pas modifier le nom une fois le produit d'API créé.
Nom à afficher
Nom à afficher du produit d'API. Le nom à afficher est utilisé dans l'UI et peut être modifié à tout moment. S'il n'est pas spécifié, la valeur du champ "Nom" est utilisée. Ce champ est renseigné automatiquement à l'aide de la valeur du champ "Name". Vous pouvez modifier ou supprimer son contenu. Le nom à afficher peut contenir des caractères spéciaux.
Description
Description du produit API.
Environnement
Environnements auxquels le produit d'API autorise l'accès. Par exemple, test ou prod.
Accès
Sélectionnez Public.
Approuver automatiquement les requêtes d'accès
Activez l'approbation automatique des requêtes de clé pour ce produit d'API depuis n'importe quelle application.
Quota
Ignorez ce champ dans ce tutoriel.
Champs d'application OAuth autorisés
Ignorez ce champ dans ce tutoriel.
Dans la section Opérations, cliquez sur AJOUTER UNE OPÉRATION.
Dans le champ Proxy d'API, ajoutez le proxy d'API que vous venez de créer.
Dans le champ "Chemin d'accès", saisissez "/". Ignorez les autres champs.
Cliquez sur Save (Enregistrer) pour enregistrer l'opération.
Cliquez sur Save (Enregistrer) pour enregistrer le produit d'API.
Ajouter un développeur et une application à votre organisation
Nous allons ensuite simuler le workflow d'un développeur qui s'inscrit pour utiliser vos API. Un développeur possède une ou plusieurs applications qui appellent vos API, et chaque application obtient une clé API unique.
En tant que fournisseur d'API, vous bénéficiez d'un contrôle plus précis de l'accès à vos API et de rapports plus détaillés sur le trafic des API par application.
Créer un développeur
Pour créer un développeur, procédez comme suit :
Sélectionnez Publier > Développeurs dans le menu. Remarque : Si vous êtes toujours dans l'écran "Développer", cliquez sur "<" à côté de DÉVELOPPER pour afficher le menu et sélectionnez Publier > Développeurs
Cliquez sur + Développeur.
Saisissez les informations suivantes dans la fenêtre "Nouveau développeur" :
Dans ce champ
entrée
Prénom
Keyser
Nom
Soze
Nom d'utilisateur
keyser
E-mail
keyser@example.com
Cliquez sur Créer.
Enregistrer une application
Pour enregistrer une application de développeur, procédez comme suit :
Sélectionnez Publier > Applications.
Cliquez sur + App (+ Application).
Saisissez les informations suivantes dans la fenêtre "Nouvelle application de développeur" :
Dans ce champ
procédez comme suit
Nom et Nom à afficher
Saisissez : keyser_app
Developer
Sélectionnez : Keyser Soze (keyser@example.com).
URL de rappel et Remarques
Laissez le champ vide
Dans la section "Credentials" (Identifiants), sélectionnez Never (Jamais).
Les identifiants de cette application n'expirent jamais.
Cliquez sur Ajouter un produit.
Sélectionnez le produit que vous venez de créer.
Cliquez sur Créer.
Obtenir la clé API
Pour obtenir la clé API, procédez comme suit :
Sur la page "Applications" (Publier > Applications), cliquez sur keyser_app.
Sur la page keyser_app, cliquez sur Show (Afficher) à côté de Key (Clé) dans la section Credentials (Identifiants). Notez que la clé est associée au produit que vous avez créé.
Sélectionnez et copiez la clé. Vous l'utiliserez à l'étape suivante.
Appeler l'API avec une clé
Maintenant que vous disposez d'une clé API, vous pouvez l'utiliser pour appeler le proxy d'API. Collez la clé API comme indiqué, en tant que paramètre de requête. Assurez-vous que le paramètre de requête ne comporte aucun espace supplémentaire.
Désormais, lorsque vous appelez le proxy d'API, vous obtenez la réponse suivante : Hello,
Guest!
Félicitations ! Vous avez créé un proxy d'API et l'avez protégé en exigeant qu'une clé API valide soit incluse dans l'appel.
Notez qu'il n'est généralement pas recommandé de transmettre une clé API en tant que paramètre de requête. Vous devriez plutôt envisager de la transmettre dans l'en-tête HTTP.
Bonne pratique : transmettre la clé dans l'en-tête HTTP
Au cours de cette étape, vous allez modifier le proxy pour rechercher la clé API dans un en-tête nommé x-apikey.
Modifiez le proxy d'API. Sélectionnez Développer > Proxys d'API > helloworld_apikey, puis accédez à la vue Développer.
Sélectionnez la règle VerifyAPIKey, puis modifiez son code XML pour lui indiquer de rechercher la clé API dans header plutôt que dans queryparam :
<APIKey ref="request.header.x-apikey"/>
Enregistrez le proxy d'API, puis utilisez Déployer.
Effectuez l'appel d'API suivant en utilisant cURL pour transmettre la clé API en tant qu'en-tête nommé x-apikey. N'oubliez pas de remplacer le nom de votre organisation.
Notez que pour finaliser la modification, vous devez également configurer la règle AssignMessage pour supprimer l'en-tête et non le paramètre de requête. Exemple :
La protection des API implique souvent une sécurité supplémentaire telle que OAuth, un protocole ouvert qui échange des identifiants (nom d'utilisateur et mot de passe, par exemple) contre des jetons d'accès. Les jetons d'accès sont de longues chaînes aléatoires qui peuvent être transmises via un pipeline de messages, y compris d'une application à une autre, sans compromettre les identifiants d'origine.
Pour obtenir une présentation des sujets liés à la sécurité, consultez la page Sécuriser un proxy.
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2025/09/04 (UTC).
[[["Facile à comprendre","easyToUnderstand","thumb-up"],["J'ai pu résoudre mon problème","solvedMyProblem","thumb-up"],["Autre","otherUp","thumb-up"]],[["Difficile à comprendre","hardToUnderstand","thumb-down"],["Informations ou exemple de code incorrects","incorrectInformationOrSampleCode","thumb-down"],["Il n'y a pas l'information/les exemples dont j'ai besoin","missingTheInformationSamplesINeed","thumb-down"],["Problème de traduction","translationIssue","thumb-down"],["Autre","otherDown","thumb-down"]],["Dernière mise à jour le 2025/09/04 (UTC)."],[[["\u003cp\u003eThis guide demonstrates how to secure APIs in Apigee and Apigee hybrid using API keys to prevent unauthorized access.\u003c/p\u003e\n"],["\u003cp\u003eThe tutorial walks through the process of creating an API proxy, configuring it to require API keys, and setting up policies to verify and remove the API key.\u003c/p\u003e\n"],["\u003cp\u003eIt explains how to create API products, developers, and developer apps, which are needed to generate API keys for accessing the protected API proxy.\u003c/p\u003e\n"],["\u003cp\u003eThe document illustrates how to test the API proxy by making calls with and without a valid API key, showcasing the security enforcement.\u003c/p\u003e\n"],["\u003cp\u003eIt highlights the best practice of passing API keys in the HTTP header (x-apikey) instead of as a query parameter for enhanced security, and details the required modifications to the API proxy.\u003c/p\u003e\n"]]],[],null,["# Secure an API by requiring API keys\n\n*This page\napplies to **Apigee** and **Apigee hybrid**.*\n\n\n*View [Apigee Edge](https://docs.apigee.com/api-platform/get-started/what-apigee-edge) documentation.*\n\n| **Note:** This video was recorded with a previous version of the Apigee UI; however, the concepts are still valid.\n\n\n**Video:** Check out this short video for an introduction on securing your API. \n**What you'll learn**\n\nThis tutorial explains how to:\n\n- Create an API proxy that requires an API key.\n- Create an API product, a developer, and a developer app.\n- Call your API with an API key. \nIt's important to protect your API from unauthorized access. One way to do that is with\nAPI keys.\n\nWhen an app makes a request to an API proxy that is configured to verify an API\nkey, the app must supply a valid key. At runtime, the\nVerify API Key policy checks that the supplied API key:\n\n- Is valid\n- Hasn't been revoked\n- Matches the API key for the API product that exposes the requested resources\n\nIf the key is valid, the request is allowed. If the key is invalid, the request results in\nan authorization failure. \n\nCreate the API proxy\n--------------------\n\n1. Go to the [Apigee UI](https://apigee.google.com) and sign in.\n2. Select your organization using the drop-down menu in the upper left corner of the UI.\n3. Click **Develop \\\u003e API Proxies** to display the API\n proxies list.\n\n4. Click **Create New** . \n5. In the Build a Proxy wizard, select **Reverse proxy (most common)**.\n6. Configure the proxy as follows: \n\n7. Click **Next**.\n8. On the **Common policies** page, select **API Key**. This option automatically adds two policies to your API proxy and creates an API product needed for generating the API key.\n9. Click **Next**.\n10. On the Summary page, make sure a deployment environment is selected, and click **Create and deploy**.\n11. Click **Edit proxy** to display the Overview page for the API proxy. \n\nView the policies\n-----------------\n\n1. In the API proxy editor, click the **Develop** tab. You'll see that two policies have been added to the request flow of the API proxy:\n - **Verify API Key** -- Checks the API call to make sure a valid API key is present (sent as a query parameter).\n - **Remove Query Param apikey** -- An Assign Message policy that removes the API key after it's checked, so that it doesn't get passed around and exposed unnecessarily.\n2. Click the Verify API Key policy icon in the flow view, and look at the policy's XML\n configuration in the lower code view. The `\u003cAPIKey\u003e` element tells the\n policy where it should look for the API key when the call is made. By default, it looks\n for the key as a query parameter called `apikey` in the HTTP request:\n\n ```text\n \u003cAPIKey ref=\"request.queryparam.apikey\" /\u003e\n ```\n\n The name `apikey` is arbitrary and can be any property that contains the\nAPI key. \n\nTry to call the API\n-------------------\n\nIn this step, you'll make a successful API call directly to the target service, then\nyou'll make an unsuccessful call to the API proxy to see how it's being protected by the\npolicies.\n\n1. **Success**\n\n In a web browser, go to the following address. This is the target service that the API\n proxy is configured to forward the request to, but you'll hit it directly for now: \n\n ```text\n http://mocktarget.apigee.net\n ```\n\n You should get this successful response: `Hello, Guest!`\n2. **Failure**\n\n Now try to call your API proxy: \n\n ```\n curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey\n ```\n\n where \u003cvar translate=\"no\"\u003eYOUR ENV_GROUP_HOSTNAME\u003c/var\u003e is the environment group hostname. See\n [Find the environment group hostname](/apigee/docs/api-platform/get-started/test-proxy#find-the-environment-group-hostname).\n | **Note:** If you have trouble calling the proxy, you may need to add the `Host` header, as described in [Deploy a sample proxy](/apigee/docs/api-platform/get-started/deploy-sample).\n\n Without the Verify API Key policy, this call would give you the same response as the\n previous call. But in this case, you should get the following error response: \n\n ```gdscript\n {\"fault\":{\"faultstring\":\"Failed to resolve API Key variable request.queryparam.apikey\",\"detail\":{\"errorcode\":\"steps.oauth.v2.FailedToResolveAPIKey\"}}}\n ```\n\n which means, correctly, that you didn't pass a valid API key (as a query\n parameter).\n\nIn the next steps, you'll get the required API key. \n\nAdding an API product\n---------------------\n\nTo add an API product using the Apigee UI:\n\n1. Select **Publish \\\u003e API Products**.\n2. Click **+Create**.\n3. Enter the Product Details for your API product. \n\n4. In the **Operations** section, click **ADD AN OPERATION**.\n5. In the API Proxy field, select the API proxy you just created.\n6. In the Path field, enter \"/\". Ignore the other fields.\n7. Click **Save** to save the Operation.\n8. Click **Save** to save the API product. \n\nAdd a developer and app to your\norganization\n--------------------------------------------\n\nNext, we're going to simulate the workflow of a developer signing up to use your APIs. A\ndeveloper will have one or more apps that call your APIs, and each app gets a unique API key.\nThis gives you, the API provider, more granular control over access to your APIs and more\ngranular reporting on API traffic by app.\n\n### Create a developer\n\nTo create a developer:\n\n1. Select **Publish \\\u003e Developers** in the menu. \n **Note** : If you are still in the Develop screen, click on the **\"\\\u003c\"** by **DEVELOP** to display the menu and select **Publish \\\u003e Developers**\n2. Click **+ Developer**.\n3. Enter the following in the New Developer window: \n\n4. Click **Create**.\n\n### Register an app\n\nTo register a developer app:\n\n1. Select **Publish \\\u003e Apps**.\n2. Click **+ App**.\n3. Enter the following in the New Developer App window: \n\n4. In the Credentials section, select **Never**. The credentials for this app will never expire.\n5. Click **Add product**.\n6. Select the product you just created.\n7. Click **Create**.\n\n### Get the API key\n\nTo get the API key:\n\n1. On the Apps page (Publish \\\u003e Apps), click **keyser_app**.\n2. On the **keyser_app** page, click **Show** next to **Key** in the **Credentials** section. Notice that the key is associated with the product you created. \n3. Select and copy the key. You'll use it in the next step. \n\nCall the API with a key\n-----------------------\n\nNow that you have an API key, you can use it to call the API proxy. Paste the API key as\nshown, as a query parameter. Make sure there are no extra\nspaces in the query parameter. \n\n```\ncurl -v -k https://YOUR_ENV_GROUP_HOSTNAME/helloapikey?apikey=your_api_key\n```\n\nNow when you call the API proxy, you should get this response: `Hello,\nGuest!`\n\nCongratulations! You've created an API proxy and protected it by requiring that a valid\nAPI key be included in the call.\n\nNote that in general it's not good practice to pass an API key as a query parameter. You\nshould consider [passing it in the HTTP\nheader instead](#extracreditpassingthekeyinthehttpheader). \n\nBest practice: Passing the key in the HTTP\nheader\n-------------------------------------------------\n\n| **Note:** It's a good practice to pass the API key in a header rather than in a query parameter. Query parameters appear in the browser history and network logs, which could present a security risk. Headers do not appear in the browser history and network logs.\n\nIn this step, you will modify the proxy to look for the API key in a header called `x-apikey`.\n\n1. Edit the API proxy. Select **Develop \\\u003e API Proxies \\\u003e\n helloworld_apikey** , and go to the **Develop** view.\n2. Select the **Verify API Key** policy, and modify the policy XML to tell\n the policy to look in the `header` rather than in the\n `queryparam`:\n\n ```text\n \u003cAPIKey ref=\"request.header.x-apikey\"/\u003e\n ```\n3. **Save** the API proxy and use **Deploy** to deploy it.\n4. Make the following API call using cURL to pass the API key as a header called\n `x-apikey`. Don't forget to substitute your organization name.\n\n ```scdoc\n curl -v -H \"x-apikey: {api_key_goes_here}\" http://YOUR_ENV_GROUP_HOSTNAME/helloapikey\n ```\n\nNote that to fully complete the change, you'd also need to configure the Assign Message\npolicy to remove the header instead of the query parameter. For example: \n\n```\n\u003cRemove\u003e\n \u003cHeaders\u003e\n \u003cHeader name=\"x-apikey\"/\u003e\n \u003c/Headers\u003e\n\u003c/Remove\u003e\n```\n| **Note:** You could also pass the API key as a form parameter. If you did, the Verify API Key policy would be configured like this: \n|\n| ```scdoc\n| \u003cAPIKey ref=\"request.formparam.{api_key_goes_here}\"/\u003e\n``` \n\nRelated topics\n--------------\n\nHere are some topics related to API products and keys:\n\n- [Managing API products](/apigee/docs/api-platform/publish/create-api-products)\n- [API keys](/apigee/docs/api-platform/security/api-keys)\n- [Registering app\n developers](/apigee/docs/api-platform/publish/adding-developers-your-api-product)\n- [Register apps and\n manage API keys](/apigee/docs/api-platform/publish/creating-apps-surface-your-api)\n- [Verify API Key\n policy](/apigee/docs/api-platform/reference/policies/verify-api-key-policy)\n\nAPI protection often involves additional security such as [OAuth](/apigee/docs/api-platform/security/oauth/oauth-home), an\nopen protocol that exchanges credentials (like username and password) for\naccess tokens. Access tokens are long, random strings that can be passed through a message\npipeline, including from app to app, without compromising the original credentials.\n\nFor an overview of security-related topics, see\n[Securing a proxy](https://cloud.google.com/apigee/docs/api-platform/security/api-security)."]]
