Sécuriser une API avec OAuth 2.0

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Ce tutoriel montre comment sécuriser un proxy d'API à l'aide d'un jeton d'accès OAuth 2.0.

Avant de commencer

Pour suivre ce tutoriel, vous devez avoir accès à une organisation Apigee dans laquelle vous disposez des autorisations pour :

  • Créer et déployer des proxys d'API
  • Créer des produits API
  • Créer des applications développeur

Vous devez également disposer d'un nom d'hôte de groupe d'environnement correctement configuré avec lequel vous pouvez effectuer des appels de proxy d'API Apigee. Si vous ne savez pas quel nom d'hôte de groupe d'environnements utiliser, contactez votre administrateur Apigee.

Déployer le proxy OAuth 2.0

Nous fournissons un proxy d'API sur GitHub configuré pour générer des jetons d'accès OAuth 2.0. Pour télécharger et déployer ce proxy d'API dans votre environnement, procédez comme suit :

  1. Téléchargez l'exemple de proxy d'API oauth dans un répertoire de votre système de fichiers.
  2. Accédez à l'interface utilisateur d'Apigee, connectez-vous, puis sélectionnez votre organisation Apigee.
  3. Sélectionnez Développer > Proxys API dans la barre de navigation de gauche.
  4. Cliquez sur Créer.
    Bouton "Créer un proxy"
  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 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 Déployer.
  10. Sélectionnez la révision et l'environnement dans lesquels effectuer le déploiement. Vous pouvez laisser le champ Compte de service vide.
  11. Cliquez sur Déployer.

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 2.0

Prenez quelques instants pour examiner la configuration de la règle OAuth 2.0.

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.

    Les règles sont affichées dans l'onglet "Développer".

    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. L'éditeur de texte affiche le code XML du flux conditionnel AccessTokenClientCredential : 
    <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 la règle GenerateAccessTokenClient dans le volet Requête : Cliquez sur GenerateAccessTokenClient sous AccessTokenClientCredential.

É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".
    Code XML pour le flux conditionnel.

    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 ce cas, le flux est déclenché lorsqu'une certaine condition est remplie. La condition, définie dans l'élément <Condition>, est 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.

    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 (3 600 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 2.0).
  • 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 2.0. Avant cela, vous devez effectuer d'autres opérations :

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

Créer un proxy d'API protégé

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 2.0 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 2.0 dans la requête.

  1. Sélectionnez Développer > Proxys API dans la barre de navigation de gauche.
  2. Cliquez sur Créer.
    Bouton &quot;Créer un proxy&quot;
  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 2.0
  5. Cliquez sur 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 Suivant.
  8. Sur la page Résumé, sous Déploiement facultatif, sélectionnez un environnement, puis cliquez sur Créer et déployer.
  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 2.0 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 2.0 dans le volet de droite, et consultez le code XML situé en dessous dans l'éditeur de texte.

É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 2.0 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.

    Vérifier le code du jeton d&#39;accès OAuth v2.0

<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 2.0 valide dans la requête.

Ajouter un produit d'API

Pour obtenir un jeton d'accès OAuth 2.0, vous devez créer trois entités Apigee : un produit d'API, un développeur et une application de développeur. Commencez par créer le produit d'API :

  1. Sélectionnez Publier > Produits API.
  2. Cliquez sur +Create (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.
    Environnement 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 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 2.0 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 2.0.

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 Entrée
    Prénom Nigel
    Nom Tufnel
    Nom d'utilisateur nigel
    E-mail nigel@example.com
  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 (nigel@example.com)
    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 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 2.0.

  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 2.0.

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 2.0 dans l'appel.

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 2.0 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 2.0 valide peuvent appeler cette API.

Obtenir un jeton d'accès OAuth 2.0

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 2.0. 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=CLIENT_KEY&client_secret=CLIENT_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" : "nigel@example.com",
  "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 2.0 ! 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 2.0 GenerateAccessTokenClient qui génère un jeton d'accès ? Votre commande cURL a rempli ces conditions, et la règle OAuth 2.0 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 2.0 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.

curl https://YOUR ENV_GROUP_HOSTNAME/hellooauth2 -H "Authorization: Bearer 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 2.0 valide soit inclus dans l'appel.

Articles associés