Sécurisez une API avec OAuth

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X.
en savoir plus

Points abordés

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

Ce tutoriel vous explique comment sécuriser une API avec OAuth 2.0.

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 le plus simple 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.

Le type d'attribution des identifiants client dans Edge 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.

Ce dont vous avez besoin

  • Un compte Apigee Edge. Si vous n'en avez pas encore, vous pouvez vous inscrire à l'aide des instructions de la section Créer un compte Apigee Edge.
  • cURL installé sur votre ordinateur pour effectuer des appels d'API à partir de la ligne de commande.

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 à la page https://apigee.com/edge et connectez-vous.
  3. Sélectionnez Développer > Proxys API dans la barre de navigation de gauche.
  4. Cliquez sur + Proxy.
    Bouton "Créer un proxy"
  5. Dans l'assistant Créer un proxy, cliquez sur Importer un groupe de proxys.
  6. Sélectionnez 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 proxys d'API.
  9. Sur la page de présentation de l'éditeur de proxy d'API, cliquez sur la liste déroulante Déploiement, puis sélectionnez test. Il s'agit de l'environnement de test de votre organisation.

    Dans l'invite de confirmation, cliquez sur Déployer.
    Lorsque vous cliquez à nouveau sur la liste déroulante "Déploiement", une icône verte indique que le proxy est déployé dans l'environnement de test.

Bravo ! Vous avez téléchargé et déployé un proxy d'API de génération de jetons pour votre organisation Edge.

Afficher le flux et la règle OAuth

Examinons de plus près ce que contient le proxy d'API.

  1. Dans l'éditeur de proxy d'API, cliquez sur l'onglet Développer. Deux règles s'affichent dans le volet Navigator (Navigateur) de gauche. Vous verrez également deux flux POST dans la section Proxy Endpoints.
  2. Cliquez sur AccessTokenClientCredential sous Proxy Endpoints.

    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 se déclenche lorsqu'une certaine condition est remplie (on parle de flux conditionnel). La condition, définie dans l'élément <Condition>, indique que si l'appel de proxy d'API est effectué vers la ressource /accesstoken et que le verbe de requête est POST, exécuter la stratégie 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 est chargée dans la vue Code :

    <OAuthV2 name="GenerateAccessTokenClient">
        <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
        <Operation>GenerateAccessToken</Operation>
        <!-- This is in millseconds, 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).
    • 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.

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

À propos de "mocktarget"

Le service mocktarget est hébergé sur Apigee et renvoie des données simples. En fait, vous pouvez y accéder dans un navigateur Web. Essayez-le en cliquant sur les éléments suivants :

http://mocktarget.apigee.net/ip

La cible renvoie ce qui doit s'afficher lorsque vous appelez ce proxy d'API.

Vous pouvez également cliquer sur http://mocktarget.apigee.net/help pour voir d'autres ressources d'API disponibles dans le service mocktarget.

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 + Proxy.
    Bouton &quot;Créer un proxy&quot;
  3. Dans l'assistant Créer un proxy, sélectionnez Proxy inverse (le plus courant), puis cliquez sur Suivant.
  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

    Ce champ définit l'URL cible qu'Apigee Edge appelle lors d'une requête adressée au proxy d'API.

    Description Saisissez : hello world protected by OAuth
  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.
  7. Cliquez sur Suivant.
  8. Sur la page Virtual Hosts (Hôtes virtuels), cliquez sur Next (Suivant).
  9. Sur la page Build, assurez-vous que l'environnement de test est sélectionné, puis cliquez sur Create and Deploy (Créer et déployer).
  10. Sur la page Résumé, un message confirme que votre nouveau proxy d'API a bien été créé et qu'il a été déployé dans votre environnement de test.
  11. Cliquez sur Edit proxy (Modifier le proxy) pour afficher la page Overview (Présentation) du proxy d'API.
    Notez que cette fois, le proxy d'API est automatiquement déployé. Cliquez sur le menu déroulant "Déploiement" pour vérifier qu'il y a un point de déploiement vert à côté de l'environnement "test".

Afficher les règles

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

  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.
    • Remove Header Authorization (Supprimer l'autorisation d'en-têtes) : stratégie "AssignMessage" qui supprime le jeton d'accès une fois qu'il a été vérifié, 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 + Produit API.
  3. Saisissez les informations détaillées sur le produit pour votre 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éé. Par exemple, helloworld_oauth2-Product.
    Nom à afficher Nom à afficher du produit d'API. Le nom à afficher est utilisé dans l'interface utilisateur et vous pouvez le modifier à 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 "Nom". Vous pouvez modifier ou supprimer son contenu. Le nom à afficher peut inclure des caractères spéciaux. Par exemple, helloworld_oauth2-Product.
    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. Par exemple, test.
    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 le champ Proxys d'API, sélectionnez le proxy d'API que vous venez de créer.
  5. Dans le champ Chemin d'accès, saisissez "/". Ignorez les autres champs.
  6. Cliquez sur Enregistrer.

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 de l'API, car Edge 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 ce qui suit dans la fenêtre New Developer (Nouveau développeur) :
    Dans ce champ OK
    Prénom Nigel
    Nom Tufnel
    Nom d'utilisateur nigel
    Adresse e-mail nigel@example.com
  4. Cliquez sur Créer.

Enregistrer une application

Créons une application pour Nigel.

  1. Sélectionnez Publier > Applications.
  2. Cliquez sur + App (+ Application).
  3. Saisissez ce qui suit dans la fenêtre New App (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. Sélectionnez helloworld_oauth2-Product.
  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.

  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 à l'élément "helloworld_oauth2-Product", créé automatiquement.

  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 !).

Juste pour tester, essayez d'appeler le proxy d'API protégé qui doit renvoyer votre adresse IP. Exécutez la commande cURL suivante dans une fenêtre de terminal, en remplaçant le nom de votre organisation Edge. Le mot test dans l'URL correspond à l'environnement de test de votre organisation, celui sur lequel vous avez déployé vos proxys. Le chemin de base du proxy est /hellooauth2, le même que celui spécifié lors de la création du proxy. Notez que vous ne transmettez pas de jeton d'accès OAuth dans l'appel.

curl https://ORG_NAME-test.apigee.net/hellooauth2

É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

Nous arrivons maintenant à la phase finale. Vous êtes sur le point d'utiliser la clé et le secret que vous avez copiés et collés dans un fichier texte, et de les échanger contre 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 code secret, effectuez l'appel cURL suivant (notez que le protocole est https), en remplaçant le nom de votre organisation Edge, votre clé et votre code secret, le cas échéant:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
"https://ORG_NAME-test.apigee.net/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 sont placés 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 ! 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 vous souvenez que, lorsque vous avez examiné ce flux conditionnel dans le proxy oauth, celui qui disait si l'URI de la ressource est /accesstoken et le verbe de 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 Edge et le jeton d'accès.

curl https://ORG_NAME-test.apigee.net/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 valide soit inclus dans l'appel.

Articles associés