OAuth

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

OAuth est apparu comme le principal protocole d'autorisation pour les API. La version d'OAuth abordée en détail dans cet article est définie dans la spécification OAuth 2.0.

OAuth est un protocole qui permet aux utilisateurs finaux d'une application d'autoriser les applications à agir en leur nom. Pour ce faire, les applications obtiennent des jetons d'accès auprès des fournisseurs d'API. Le fournisseur d'API authentifie les identifiants de l'utilisateur final de l'application, s'assure que celui-ci a autorisé l'application, puis émet un jeton d'accès à l'application. Lorsque l'application utilise une API protégée, Apigee Edge vérifie le jeton d'accès pour s'assurer qu'il est valide et qu'il n'a pas expiré. En tant que fournisseur d'API, vous devez exposer des points de terminaison qui permettent aux applications d'obtenir des jetons d'accès.

Pour faciliter la prise en main du protocole OAuth, Apigee Edge vous permet de configurer et d'appliquer OAuth à l'aide de règles, sans que vous ayez à écrire de code. Dans cet article, vous allez découvrir comment protéger vos API, obtenir des jetons d'accès et utiliser ces jetons pour accéder à des API protégées.

Configuration OAuth par défaut pour votre organisation

Pour plus de commodité, toutes les organisations utilisant Apigee Edge sont préconfigurées avec un ensemble de points de terminaison OAuth 2.0 qui implémentent le type d'attribution des identifiants client. Le type d'attribution des identifiants client définit une procédure permettant d'émettre des jetons d'accès en échange d'identifiants d'application. Ces identifiants d'application constituent simplement la paire clé/code secret client qu'Apigee Edge émet pour chaque application enregistrée dans une organisation. Le terme "identifiants client" fait référence à la paire clé/code secret client.

Pour en savoir plus sur l'émission d'identifiants aux applications à l'aide des services de développement Edge, consultez la section Enregistrer des applications et gérer les clés.

Pour cette raison, il est relativement simple d 'intensifier votre schéma de sécurité d'API, de la validation des clés API aux identifiants client OAuth. Les deux schémas utilisent la même clé client et le même code secret pour valider l'application cliente. La différence réside dans le fait que les identifiants client fournissent un niveau de contrôle supplémentaire, car vous pouvez facilement révoquer un jeton d'accès en cas de besoin, sans que vous ayez besoin de révoquer la clé client de l'application. Pour utiliser les points de terminaison OAuth par défaut, vous pouvez récupérer les jetons d'accès à partir du point de terminaison des jetons à l'aide de n'importe quelle clé client et n'importe quel secret généré pour l'application de votre organisation. (Vous pouvez même activer les identifiants client pour les applications qui possèdent déjà des clés et des secrets client.)

La spécification complète de l'attribution des identifiants client est disponible dans la spécification OAuth 2.0.

Protégez votre API avec une règle

Avant de pouvoir utiliser les jetons d'accès, vous devez configurer vos API de façon à valider les jetons d'accès OAuth au moment de l'exécution. Pour ce faire, configurez un proxy d'API pour validate les jetons d'accès. Cela signifie que chaque fois qu'une application envoie une requête pour consommer l'une de vos API, elle doit présenter un jeton d'accès valide avec la requête API. Apigee Edge gère la complexité associée à la génération, au stockage et à la validation des jetons d'accès qui vous sont présentés.

Vous pouvez facilement ajouter la validation OAuth à une API lorsque vous créez un proxy d'API. Lorsque vous créez un proxy d'API, vous pouvez Ajouter des fonctionnalités. Comme indiqué ci-dessous, vous pouvez ajouter la validation des jetons d'accès OAuth 2.0 en sélectionnant la case d'option Secure with OAuth v2.0 Access Tokens (Sécuriser avec des jetons d'accès OAuth v2.0). Lorsque vous sélectionnez cette option, deux règles sont associées au nouveau proxy d'API, l'une pour valider les jetons d'accès et l'autre pour supprimer le jeton d'accès une fois qu'il a été validé.

De plus, lorsque vous sélectionnez l'option Secure with OAuth v2.0 Access Tokens (Sécuriser avec des jetons d'accès OAuth v2.0), la case Publish API Product (Publier un produit d'API) devient sélectionnable et est automatiquement cochée. Cochez cette case si vous souhaitez générer automatiquement un produit lorsque vous créez le nouveau proxy d'API. Le produit généré automatiquement sera créé avec une association au nouveau proxy d'API. Si vous souhaitez associer un produit existant à cette nouvelle API, décochez cette case afin de ne pas créer de produit inutile. Pour plus d'informations sur les produits, consultez Qu'est-ce qu'un produit API ?

Si vous devez activer la validation des jetons d'accès pour un proxy d'API existant, il vous suffit d'associer une stratégie de type OAuthV2 à l'API que vous souhaitez protéger. Les règles OAuthV2 fonctionnent en spécifiant une opération. Si vous souhaitez valider les jetons d'accès, vous devez spécifier l'opération appelée VerifyAccessToken. (Les autres types d'opérations compatibles avec le type de stratégie OAuthV2 sont GenerateAccessToken et GenerateRefreshToken. Vous vous familiariserez avec ces opérations lors de la configuration de points de terminaison OAuth.)

Vérifier la stratégie OAuthTokens de type OAuthV2

Voici un exemple de stratégie pour valider les jetons d'accès. (Les paramètres sont expliqués dans le tableau ci-dessous.)

<OAuthV2 name="VerifyOAuthTokens"> 
  <Operation>VerifyAccessToken</Operation> 
</OAuthV2>

Paramètres de la règle

Nom Description Par défaut Obligatoire ?
OAuthV2 Type de règle
name Nom de la règle, référencé dans la configuration du point de terminaison du proxy d'API. N/A Oui
Operation Opération à exécuter par la règle OAuthV2. En spécifiant VerifyAccessToken, vous configurez la règle pour vérifier les requêtes de jetons d'accès et pour vérifier que le jeton d'accès est valide, qu'il n'a pas expiré et qu'il est autorisé à utiliser la ressource API demandée (URI). Pour effectuer cette vérification, la règle lit le produit d'API que l'application est autorisée à utiliser. N/A Oui

Pour créer cette règle dans l'interface utilisateur de gestion, accédez à API > API Proxies (API > Proxys d'API).

Dans la liste des proxys d'API, sélectionnez weatherapi.

Dans la section Overview (Aperçu) de weatherapi, sélectionnez la vue Develop (Développer).

Dans le menu déroulant, sélectionnez Nouvelle règle > OAuth v2.0.

Une fois que vous avez sélectionné la règle OAuth v2.0, le menu de configuration Nouvelle règle s'affiche.

Attribuez un nom descriptif à votre règle, puis assurez-vous de sélectionner Attach Policy (Associer une règle), Flow PreFlow (Préflux de flux) et Request (Requête) comme paramètres de rattachement de règle.

Sélectionnez Add (Ajouter). La règle est créée et associée au PreFlow de requête de weatherapi.

Une fois la règle ajoutée, la configuration PreFlow de la requête ci-dessous s'affiche dans le volet Designer (Concepteur).

Si vous travaillez localement dans un éditeur de texte ou un IDE, vous devez associer la stratégie au PreFlow de la requête du proxy d'API que vous souhaitez protéger:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthTokens</Name></Step>
  </Request>
</PreFlow>

En joignant la règle au PreFlow de la requête, vous vous assurez qu'elle est toujours appliquée à tous les messages de requête.

Vous avez maintenant sécurisé une API avec des identifiants client OAuth 2.0. L'étape suivante consiste à apprendre à obtenir un jeton d'accès et à l'utiliser pour accéder à l'API sécurisée.

Utiliser un jeton d'accès pour accéder à une ressource protégée

Maintenant que l'API weatherapi est sécurisée avec OAuth 2.0, les applications doivent présenter des jetons d'accès pour utiliser l'API. Pour accéder à une ressource protégée, l'application présente un jeton d'accès dans la requête sous la forme d'un en-tête HTTP "Authorization", comme suit:

$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

Étant donné que l'API est associée à une stratégie OAuthV2, Apigee Edge vérifie que le jeton d'accès présenté est valide, puis accorde l'accès à l'API, renvoyant ainsi le bulletin météo à l'application qui a effectué la requête.

Mais comment les applications obtiennent-elles des jetons d'accès ? Nous aborderons ce point dans la section suivante.

Échanger des identifiants client contre un jeton d'accès

Les applications obtiennent les jetons d'accès en présentant leurs paires clé/code secret client au point de terminaison des jetons. Le point de terminaison du jeton est configuré dans le proxy de l'API appelé oauth. Les applications doivent donc appeler l'API exposée par le proxy d'API oauth pour obtenir un jeton d'accès. Une fois que l'application dispose d'un jeton d'accès, elle peut appeler weatherapi à plusieurs reprises, jusqu'à ce que le jeton d'accès expire ou que le jeton soit révoqué.

Vous devez maintenant passer à la vitesse supérieure pour vous considérer comme un développeur d'applications. Vous souhaitez appeler l'API weatherapi. Vous devez donc obtenir un jeton d'accès pour votre application. Vous devez d'abord obtenir une paire clé client/code secret (également appelée clé API ou clé d'application).

Vous pouvez obtenir une clé et un code secret client en enregistrant une application dans votre organisation sur Apigee Edge.

Vous pouvez afficher toutes les applications de votre organisation dans l'interface utilisateur de gestion Apigee Edge.

La liste des applications enregistrées dans votre organisation s'affiche.

(Si aucune application ne s'affiche, découvrez comment enregistrer une application dans l'article intitulé Enregistrer des applications et gérer les clés API.)

Sélectionnez une application dans la liste pour afficher son profil détaillé.

Dans la vue détaillée de l'application que vous avez sélectionnée, notez les champs Consumer Key (Clé client) et Consumer Secret (Code secret client). Ces deux valeurs sont les identifiants client que vous utiliserez pour obtenir un jeton d'accès OAuth.

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass 

Cet appel renvoie une liste d'applications triée par ID d'application.

[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]

Vous pouvez récupérer le profil d'une application en effectuant un simple appel GET sur l'ID d'application :

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass 

Exemple :

$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass 

L'appel d'API renvoie le profil de l'application que vous avez spécifiée. Par exemple, un profil d'application pour weatherapp a la représentation JSON suivante:

{
  "accessType" : "read",
  "apiProducts" : [ ],
  "appFamily" : "default",
  "appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
  "attributes" : [ ],
  "callbackUrl" : "http://weatherapp.com",
  "createdAt" : 1380290158713,
  "createdBy" : "noreply_admin@apigee.com",
  "credentials" : [ {
    "apiProducts" : [ {
      "apiproduct" : "PremiumWeatherAPI",
      "status" : "approved"
    } ],
    "attributes" : [ ],
    "consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
    "consumerSecret" : "hAr4Gn0gA9vAyvI4",
    "expiresAt" : -1,
    "issuedAt" : 1380290161417,
    "scopes" : [ ],
    "status" : "approved"
  } ],
  "developerId" : "5w95xGkpnjzJDBT4",
  "lastModifiedAt" : 1380290158713,
  "lastModifiedBy" : "noreply_admin@apigee.com",
  "name" : "weatherapp",
  "scopes" : [ ],
  "status" : "approved"
}

Notez les valeurs de consumerKey et consumerSecret. Vous pouvez utiliser ces identifiants pour obtenir un jeton d'accès en les présentant comme des identifiants d'authentification de base dans une requête HTTP, comme indiqué ci-dessous. Le type d'attribution est présenté sous la forme d'un paramètre de requête. (Veillez à modifier la valeur de la variable {org_name} afin de refléter le nom de votre organisation sur Apigee Edge.)

Créer une requête pour obtenir un jeton d'accès

Dans la requête suivante, remplacez la valeur de consumerKey par client_id. Remplacez client_secret par la valeur de l'élément consumerSecret associé.

$ curl https://{org_name}-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

Les services d'API vérifient la clé et le code secret client, puis génèrent une réponse contenant le jeton d'accès pour cette application:

{
  "issued_at" : "1380892555397",
  "application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
  "scope" : "",
  "status" : "approved",
  "api_product_list" : "[oauth-test]",
  "expires_in" : "3599",
  "developer.email" : "tesla@weathersample.com",
  "organization_id" : "0",
  "client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
  "access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
  "organization_name" : "rqa",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Notez la valeur access_token dans la réponse ci-dessus. Il s'agit du jeton d'accès que l'application utilisera pour obtenir un accès en exécution aux ressources protégées. Le jeton d'accès de cette application est ylSkZIjbdWybfs4fUQe9BqP0LH5Z.

Vous disposez maintenant d'un jeton d'accès valide, ylSkZIjbdWybfs4fUQe9BqP0LH5Z, qui peut être utilisé pour accéder aux API protégées.

Utiliser la configuration OAuth par défaut

Chaque organisation (y compris une organisation bénéficiant d'un essai sans frais) sur Apigee Edge est provisionnée avec un point de terminaison de jeton OAuth. Le point de terminaison est préconfiguré avec des règles dans le proxy d'API appelées oauth. Vous pouvez commencer à utiliser le point de terminaison du jeton dès que vous créez un compte sur Apigee Edge.

Le point de terminaison OAuth par défaut expose l'URI de point de terminaison suivant:

/oauth/client_credential/accesstoken

Publiez cet URI pour les développeurs qui ont besoin de jetons d'accès. Les développeurs d'applications configurent leurs applications pour appeler ce point de terminaison, en présentant leurs paires clé/code secret client pour obtenir des jetons d'accès.

Le point de terminaison du jeton d'identifiants clients par défaut est exposé sur le réseau à l'URL suivante :

https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken

Par exemple, si le nom de votre organisation est "apimakers", l'URL se présentera comme suit :

https://apimakers-test.apigee.net/oauth/client_credential/accesstoken

Il s'agit de l'URL que les développeurs appellent pour obtenir des jetons d'accès.

Configurations OAuth en trois étapes

Les configurations OAuth à trois acteurs (types d'attribution de code d'autorisation, implicite et mot de passe) nécessitent que vous, en tant que fournisseur d'API, authentifiez les utilisateurs finaux de l'application. Étant donné que chaque organisation authentifie les utilisateurs de différentes manières, une certaine personnalisation des règles ou du code est nécessaire pour intégrer OAuth à votre magasin d'utilisateurs. Par exemple, tous vos utilisateurs peuvent être stockés dans Active Directory, sur un serveur LDAP ou dans un autre magasin d'utilisateurs. Pour activer l'authentification OAuth à trois acteurs, vous devez intégrer une vérification auprès de ce magasin d'utilisateurs dans le flux OAuth global.

OAuth 1.0a

Pour en savoir plus sur les règles OAuth 1.0a, consultez Règles OAuth v1.0a.

Obtenir de l'aide

Pour obtenir de l'aide, consultez la page Service client Apigee.