Sécuriser une API avec OAuth

Vous consultez la documentation d'Apigee X.
Consultez la documentation d'Apigee Edge.

Ce tutoriel explique comment :

• Télécharger et déployer un exemple de proxy d'API.
• Créer un proxy d'API protégé par OAuth.
• Créer un produit, un développeur et une application.
• Identifiants Exchange pour un jeton d'accès OAuth.
• Appeler une API avec un jeton d'accès.

OAuth est un protocole d'autorisation qui permet aux applications d'accéder aux informations pour le compte des utilisateurs sans qu'ils aient à divulguer leur nom d'utilisateur et leur mot de passe.

Avec OAuth, les identifiants de sécurité (tels que le nom d'utilisateur/mot de passe ou la clé/le secret) sont échangés contre un jeton d'accès. Exemple :

joe:joes_password (username:password) ou
Nf2moHOASMJeUmXVdDhlMbPaXm2U7eMc:unUOXYpPe74ZfLEb (key:secret)

prend une forme équivalente à :

b0uiYwjRZLEo4lEu7ky2GGxHkanN

Le jeton d'accès est une chaîne aléatoire de caractères et est temporaire (il arrive à expiration après un court laps de temps), si bien que sa transmission pour authentifier un utilisateur dans un flux d'applications est beaucoup plus sûre que la transmission de véritables informations d'identification.

La spécification OAuth 2.0 définit différents mécanismes, appelés "types d'attribution", pour la distribution des jetons d'accès pour les applications. Le type d'attribution défini par OAuth 2.0 est appelé "identifiants client". Dans ce type d'attribution, les jetons d'accès OAuth sont générés en échange d'identifiants client, qui sont des paires clé client/secret client, comme dans l'exemple ci-dessus.

Remarque : La clé client est également utilisée par les applications Apigee pour une clé API lors de la mise en œuvre de la sécurité de cette clé, souvent conjointement avec un type d'OAuth.

Le type d'attribution des identifiants client dans Apigee est mis en œuvre à l'aide de règles dans les proxys d'API. Un flux OAuth type implique deux étapes :

• Appeler le proxy d'API 1 pour générer un jeton d'accès OAuth à partir des identifiants client. Une règle OAuth v2.0 sur le proxy d'API gère cela.
• Appeler le proxy d'API 2 pour envoyer le jeton d'accès OAuth dans un appel d'API. Le proxy d'API vérifie le jeton d'accès à l'aide d'une règle OAuth v2.0.

Télécharger et déployer un proxy d'API générant des jetons

À cette étape, vous allez créer le proxy d'API qui génère un jeton d'accès OAuth à partir d'une clé client et d'un secret client envoyés dans un appel d'API. Apigee fournit un exemple de proxy d'API qui effectue cette opération. Vous allez maintenant télécharger et déployer le proxy, puis l'utiliser plus tard dans le tutoriel. (Vous pouvez facilement créer ce proxy d'API par vous-même). Cette étape de téléchargement et de déploiement est plus pratique et vous indique à quel point il est facile de partager des proxys qui ont déjà été créés.)

1. Téléchargez le fichier ZIP d'exemple de proxy d'API "oauth" dans un répertoire de votre système de fichiers.
2. Accédez à l'interface utilisateur d'Apigee et connectez-vous.
3. Sélectionnez Développer > Proxys API dans la barre de navigation de gauche.
   Remarque : Avant de continuer, faites défiler la liste des proxys d'API. Si vous avez déjà un proxy d'API appelé oauth, cliquez dessus et passez à la section suivante pour vous assurer qu'il est configuré de la même manière que ce qui est décrit. Si le vôtre est différent, supprimez-le et poursuivez cette procédure, ou modifiez-le pour qu'il corresponde à la configuration décrite.
4. Cliquez sur Créer.
   
5. Dans l'assistant de création de proxy, sélectionnez Upload proxy bundle (Importer le groupe de proxys).
6. Choisissez le fichier oauth.zip que vous avez téléchargé, puis cliquez sur Suivant.
7. Cliquez sur Create (Créer).
8. Une fois la compilation terminée, cliquez sur Modifier le proxy pour afficher le nouveau proxy dans l'éditeur de proxy d'API.
9. Cliquez sur la liste déroulante Revision (Révision) et sélectionnez le numéro de révision pour déployer le proxy.
   

Vous venez de télécharger et de déployer un proxy d'API générant des jetons d'accès pour votre organisation Apigee.

Afficher le flux et la règle OAuth

Remarque : Apigee introduit une nouvelle version de l'éditeur de proxys, qui facilite la gestion des proxys. Le nouvel éditeur de proxys remplacera l'éditeur de proxys classique d'ici fin 2022.

Nous vous encourageons à essayer le nouvel éditeur de proxys. Pour ce faire, cliquez simplement sur le bouton Essayer lorsque celui-ci s'affiche dans l'éditeur. Vous pouvez toujours revenir à l'éditeur de proxys classique si vous le souhaitez.

Les instructions des deux premiers onglets ci-dessous expliquent comment utiliser le nouvel éditeur de proxys ou l'éditeur de proxys classique.

Nouvel éditeur de proxys

Examinez ensuite de plus près le contenu du proxy d'API.

1. Dans l'éditeur de proxy d'API, cliquez sur l'onglet Développer. Si le bouton Essayer s'affiche, cliquez dessus pour afficher la nouvelle page Développer.

   À propos du bouton Essayer

   Si c'est la première fois que vous utilisez la nouvelle version de l'éditeur de proxy, la bannière suivante s'affiche en haut de la vue Développer :

   

   Cliquez sur le bouton Essayer pour afficher la nouvelle version de la vue Développer :

   Remarque : Si vous avez précédemment cliqué sur le bouton Essayer, celui-ci ne s'affiche pas.

   La vue Développer est présentée ci-dessous.

   

   Le volet de gauche affiche deux règles. Vous verrez également deux flux POST dans la section Points de terminaison du proxy.

2. Cliquez sur AccessTokenClientCredential sous Points de terminaison du Proxy.
3. Cliquez sur Passer à l'éditeur de texte. Le code XML du flux conditionnel AccessTokenClientCredential s'affiche :

   <Flow name="AccessTokenClientCredential">
       <Description/>
       <Request>
           <Step>
               <Name>GenerateAccessTokenClient</Name>
           </Step>
       </Request>
       <Response/>
       <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
   </Flow>
   

   Un flux est une étape de traitement dans un proxy d'API. Dans le cas présent, le flux est déclenché lorsqu'une certaine condition est remplie (appelée "flux conditionnel"). La condition, définie dans l'élément <Condition>, indique que si l'appel du proxy d'API est effectué vers la ressource /accesstoken, et que le verbe de requête est POST, elle exécute alors la règle GenerateAccessTokenClient, qui génère le jeton d'accès.

4. Examinons maintenant la règle que le flux conditionnel va déclencher. Cliquez sur Passer à l'éditeur visuel.
5. Cliquez sur la règle GenerateAccessTokenClient dans le volet Requête :
6. Cliquez sur Passer à l'éditeur de texte.

Éditeur de proxy classique

Examinez ensuite de plus près le contenu du proxy d'API.

1. Dans l'éditeur de proxy d'API, cliquez sur l'onglet Développer. Le volet de navigation de gauche affiche deux règles. Vous verrez également deux flux POST dans la section Points de terminaison du proxy.

2. Cliquez sur AccessTokenClientCredential sous "Points de terminaison du Proxy".
   

   Dans la vue Code XML, un Flow appelé AccessTokenClientCredential s'affiche :

   <Flow name="AccessTokenClientCredential">
       <Description/>
       <Request>
           <Step>
               <Name>GenerateAccessTokenClient</Name>
           </Step>
       </Request>
       <Response/>
       <Condition>(proxy.pathsuffix MatchesPath "/accesstoken") and (request.verb = "POST")</Condition>
   </Flow>
   

   Un flux est une étape de traitement dans un proxy d'API. Dans le cas présent, le flux est déclenché lorsqu'une certaine condition est remplie (appelée "flux conditionnel"). La condition, définie dans l'élément <Condition>, indique que si l'appel du proxy d'API est effectué vers la ressource /accesstoken, et que le verbe de requête est POST, elle exécute alors la règle GenerateAccessTokenClient, qui génère le jeton d'accès.

3. Examinons maintenant la règle que le flux conditionnel va déclencher. Cliquez sur l'icône de la règle GenerateAccessTokenClient dans le schéma de flux.
   

La configuration XML suivante s'affiche :

<OAuthV2 name="GenerateAccessTokenClient">
    <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
    <Operation>GenerateAccessToken</Operation>
    <!-- This is in milliseconds, so expire in an hour -->
    <ExpiresIn>3600000</ExpiresIn>
    <SupportedGrantTypes>
        <!-- This part is very important: most real OAuth 2.0 apps will want to use other
         grant types. In this case it is important to NOT include the "client_credentials"
         type because it allows a client to get access to a token with no user authentication -->
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GrantType>request.queryparam.grant_type</GrantType>
    <GenerateResponse/>
</OAuthV2>

La configuration comprend les éléments suivants :

• Le champ <Operation>, qui peut être l'une des valeurs prédéfinies, définit ce que la règle fera. Dans le cas présent, elle va générer un jeton d'accès.
• Le jeton expirera 1 heure (360 000 millisecondes) après sa génération.
• Dans <SupportedGrantTypes>, le protocole OAuth <GrantType> qui devrait être utilisé est client_credentials (échange d'une clé client et d'un secret client pour un jeton OAuth).
• Le deuxième élément <GrantType> indique à la règle où rechercher le paramètre de type d'attribution dans l'appel d'API, comme requis par la spécification OAuth 2.0. (Vous verrez cela plus tard dans l'appel d'API). Le type d'attribution peut également être envoyé dans l'en-tête HTTP (request.header.grant_type) ou en tant que paramètre de formulaire (request.formparam.grant_type).

Vous n'avez rien d'autre à faire concernant le proxy d'API pour le moment. Dans les étapes suivantes, vous utiliserez ce proxy d'API pour générer un jeton d'accès OAuth. Avant cela, vous devez effectuer d'autres opérations :

• Créez le proxy d'API que vous souhaitez sécuriser avec OAuth.
• Créez quelques autres artefacts qui renverront la clé client et le secret client que vous devrez échanger contre un jeton d'accès.

Remarque : Le flux et la règle RefreshAccessToken dans le proxy d'API ne sont pas utilisés dans ce tutoriel et ne sont pas compatibles avec le type d'attribution d'identifiants client OAuth.

Créer le proxy d'API protégé par OAuth

Vous allez maintenant créer le proxy d'API que vous souhaitez protéger. Il s'agit de l'appel d'API qui renvoie ce que vous souhaitez. Dans ce cas, le proxy d'API appelle le service Mocktarget d'Apigee pour renvoyer votre adresse IP. CEPENDANT, vous ne la verrez que si vous transmettez un jeton d'accès OAuth valide avec l'appel d'API.

Le proxy d'API que vous créez ici inclut une règle qui vérifie la présence d'un jeton OAuth dans la requête.

1. Sélectionnez Développer > Proxys API dans la barre de navigation de gauche.
2. Cliquez sur Créer.
   
3. Dans l'assistant Créer un proxy, sélectionnez Proxy inverse (le plus courant).
4. Configurez le proxy comme suit :
   

   Dans ce champ	procédez comme suit
   Nom du proxy	Saisissez : helloworld_oauth2
   Chemin de base du projet	Remplacez par : /hellooauth2 Le chemin de base du projet fait partie de l'URL utilisée pour envoyer des requêtes au proxy d'API.
   API existante	Saisissez : https://mocktarget.apigee.net/ip Cela définit l'URL cible qu'Apigee appelle sur une requête adressée au proxy d'API.
   Description	Saisissez : hello world protected by OAuth

5. Cliquez sur Next (Suivant).
6. Sur la page Règles courantes :

   Dans ce champ	procédez comme suit
   Sécurité : Autorisation	Sélectionnez : OAuth 2.0 Ces options sont très utiles. Elles ajouteront automatiquement deux règles à votre proxy d'API et créeront un produit d'API.

7. Cliquez sur Next (Suivant).
8. Sur la page Résumé, sous Déploiement facultatif, sélectionnez un environnement, puis cliquez sur Créer.
9. Cliquez sur Edit proxy (Modifier le proxy) pour afficher la page "Overview" (Présentation) du proxy d'API.
   Le proxy d'API est automatiquement déployé. (Le déploiement peut prendre quelques instants.)

Afficher les règles

Examinons en détail ce que vous avez créé.

Nouvel éditeur de proxys

1. 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 le jeton d'accès OAuth v2.0 : vérifie l'appel d'API pour s'assurer qu'un jeton OAuth valide est présent.
   • Supprimer l'autorisation d'en-tête : règle d'attribution de messages qui supprime le jeton d'accès après vérification, afin qu'il ne soit pas transmis au service cible. (Si le service cible a besoin du jeton d'accès OAuth, cette règle ne serait pas utilisée.)

2. Cliquez sur l'icône Vérifier le jeton d'accès OAuth v2.0 dans le volet de droite.

3. Cliquez sur Passer à l'éditeur de texte et consultez le code XML situé en dessous dans le volet de code.

Éditeur de proxy classique

1. 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 le jeton d'accès OAuth v2.0 : vérifie l'appel d'API pour s'assurer qu'un jeton OAuth valide est présent.
   • Supprimer l'autorisation d'en-tête : règle d'attribution de messages qui supprime le jeton d'accès après vérification, afin qu'il ne soit pas transmis au service cible. (Si le service cible a besoin du jeton d'accès OAuth, cette règle ne serait pas utilisée.)

2. Cliquez sur l'icône Vérifier le jeton d'accès OAuth v2.0 dans la vue du flux et consultez le code XML situé en dessous dans le volet de code.

   

<OAuthV2 async="false" continueOnError="false" enabled="true" name="verify-oauth-v2-access-token">
    <DisplayName>Verify OAuth v2.0 Access Token</DisplayName>
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Notez que <Operation> est VerifyAccessToken. L'opération définit ce que la règle est censée faire. Dans le cas présent, elle va rechercher un jeton OAuth valide dans la requête.

Ajouter un produit d'API

Pour ajouter un produit API à l'aide de l'interface utilisateur Apigee, procédez comme suit :

1. Sélectionnez Publier > Produits API.
2. Cliquez sur +CRÉER.
3. 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.
   Environment	Environnements auxquels le produit d'API autorise l'accès. Sélectionnez l'environnement dans lequel vous avez déployé le proxy d'API.
   Accès	Sélectionnez Publique.
   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.

4. Dans la section Opérations, cliquez sur AJOUTER UNE OPÉRATION.
5. Dans le champ Proxy d'API, ajoutez le proxy d'API que vous venez de créer.
6. Dans le champ "Chemin d'accès", saisissez "/". Ignorez les autres champs.
7. Cliquez sur Save (Enregistrer) pour enregistrer l'opération.
8. Cliquez sur Save (Enregistrer) pour enregistrer le produit d'API.

Ajouter un développeur et une application à votre organisation

Vous allez ensuite simuler le workflow d'un développeur qui se connecte pour utiliser vos API. Idéalement, les développeurs s'inscrivent et leurs applications via votre portail de développeur. Toutefois, à ce stade, vous allez ajouter un développeur et une application en tant qu'administrateur.

Un développeur possède une ou plusieurs applications qui appellent vos API, et chaque application obtient une clé client et un secret client uniques. Cette clé/secret par application vous offre également, en tant que fournisseur d'API, un contrôle plus précis de l'accès à vos API et des rapports d'analyse plus précis sur le trafic des API, car Apigee sait quel développeur et quelle application appartient à quel jeton OAuth.

Créer un développeur

Créons maintenant un développeur nommé Nigel Tufnel.

1. Sélectionnez Publier > Développeurs dans le menu.
2. Cliquez sur + Développeur.
3. Saisissez les informations suivantes dans la fenêtre "Nouveau développeur" :
   

   Dans ce champ	OK
   Prénom	Nigel
   Nom	Tufnel
   Nom d'utilisateur	nigel
   E-mail	[e-mail]

4. Cliquez sur Enregistrer.

Enregistrer une application

Créons une application pour Nigel.

1. Sélectionnez Publier > Applications.
2. Cliquez sur + App (+ Application).
3. Saisissez les informations suivantes dans la fenêtre "Nouvelle application" :
   

   Dans ce champ	procédez comme suit
   Nom et Nom à afficher	Saisissez : nigel_app
   Développeur	Cliquez sur Développeur et sélectionnez : Nigel Tufnel ([e-mail])
   URL de rappel et Remarques	Laissez le champ vide

4. Sous Produits, cliquez sur Ajouter un produit.
5. Ajoutez le produit d'API que vous venez de créer.
6. Cliquez sur Create (Créer).

Obtenir la clé client et le secret client

Vous allez maintenant obtenir la clé client et le secret client qui seront échangés contre un jeton d'accès OAuth.

1. Assurez-vous que la page nigel_app s'affiche. Dans le cas contraire, sur la page Applications (Publier > Applications), cliquez sur nigel_app.

2. Sur la page "nigel_app", cliquez sur Afficher dans les colonnes Clé et Secret. Notez que la clé/le secret sont associés au produit d'API que vous avez créé précédemment.

3. Sélectionnez et copiez la clé et le secret. Collez-les dans un fichier texte temporaire. Vous en aurez besoin lors d'une prochaine étape, dans laquelle vous appelez le proxy d'API qui échangera ces identifiants contre un jeton d'accès OAuth.

Essayez d'appeler l'API pour obtenir votre adresse IP (échec !).

Essayez d'appeler le proxy d'API protégé que vous venez de créer. Notez que vous ne transmettez pas de jeton d'accès OAuth dans l'appel.

curl -v -k https://YOUR_ENV_GROUP_HOSTNAME/hellooauth2

où YOUR ENV_GROUP_HOSTNAME est le nom d'hôte du groupe d'environnements. Consultez la page Rechercher le nom d'hôte du groupe d'environnements.

Étant donné que le proxy d'API dispose de la règle Vérifier le jeton d'accès OAuth v2.0 qui vérifie s'il existe un jeton OAuth valide dans la requête, l'appel doit échouer avec le message suivant :

{"fault":{"faultstring":"Invalid access token","detail":{"errorcode":"oauth.v2.InvalidAccessToken"}}}

Dans ce cas, l'échec est normal. Cela signifie que votre proxy d'API est bien plus sécurisé. Seules les applications approuvées avec un jeton d'accès OAuth valide peuvent appeler cette API.

Obtenir un jeton d'accès OAuth

Vous utiliserez ensuite la clé et le secret que vous avez copiés et collés dans un fichier texte et les échangerez pour obtenir un jeton d'accès OAuth. Vous allez maintenant effectuer un appel d'API vers l'exemple de proxy d'API que vous avez importé, oauth, qui va générer un jeton d'accès à l'API.

À l'aide de cette clé et de ce secret, effectuez l'appel cURL suivant (notez que le protocole est https) :

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
"https://YOUR ENV_GROUP_HOSTNAME/oauth/client_credential/accesstoken?grant_type=client_credentials" \
-d "client_id={key}&client_secret={secret}"

Notez que si vous utilisez un client tel que Postman pour effectuer l'appel, client_id et client_secret se placent dans le corps de la requête et doivent être x-www-form-urlencoded.

Vous devriez obtenir une réponse semblable à la suivante :

{
  "issued_at" : "1466025769306",
  "application_name" : "716bbe61-f14a-4d85-9b56-a62ff8e0d347",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[helloworld_oauth2-Product]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "[e-mail]",
  "token_type" : "BearerToken",
  "client_id" : "xNnREu1DNGfiwzQZ5HUN8IAUwZSW1GZW",
  "access_token" : "GTPY9VUHCqKVMRB0cHxnmAp0RXc0",
  "organization_name" : "myOrg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

Vous avez obtenu votre jeton d'accès OAuth ! Copiez la valeur access_token (sans les guillemets) et collez-la dans votre fichier texte. Vous l'utiliserez dans un instant.

Que s'est-il passé ?

Vous rappelez-vous, lorsque vous avez vu ce "flux conditionnel" dans le proxy oauth, celui qui indique que l'URI de la ressource est /accesstoken et que le verbe de la requête est POST, pour exécuter la règle OAuth GenerateAccessTokenClient qui génère un jeton d'accès ? Votre commande cURL a rempli ces conditions, et la règle OAuth a donc été exécutée. Elle a vérifié votre clé client et votre secret client, et les a échangé contre un jeton OAuth qui expire dans 1 heure.

Appeler l'API avec un jeton d'accès (réussi !)

Maintenant que vous disposez d'un jeton d'accès, vous pouvez l'utiliser pour appeler le proxy d'API. Effectuez l'appel cURL suivant. Remplacez le nom de votre organisation Apigee et le jeton d'accès (supprimez les accolades).

curl https://YOUR ENV_GROUP_HOSTNAME/hellooauth2 -H "Authorization: Bearer {access-token}"

Vous devriez maintenant obtenir un appel réussi au proxy d'API qui renvoie votre adresse IP. Exemple :

{"ip":"::ffff:192.168.14.136"}

Vous pouvez répéter cet appel d'API pendant près d'une heure, après quoi le jeton d'accès expirera. Pour effectuer l'appel après plus d'une heure, vous devez générer un nouveau jeton d'accès à l'aide des étapes précédentes.

Félicitations ! Vous avez créé un proxy d'API et l'avez protégé en exigeant qu'un jeton d'accès OAuth valide soit inclus dans l'appel.

Articles associés

• Accueil OAuth
• Règle OAuthV2
• Télécharger des proxys d'API (montre comment regrouper un proxy d'API dans un fichier ZIP semblable à celui que vous avez téléchargé)