Utiliser OAuth2 pour accéder à l'API Edge

Vous consultez la documentation Apigee Edge.
Accédez à la documentation**Apigee X**. info

Apigee Edge vous permet d'effectuer des appels d'API Edge authentifiés avec des jetons OAuth2. La compatibilité avec OAuth2 est activée par défaut sur Edge pour les comptes Cloud. Si vous utilisez Edge pour le cloud privé, vous ne pouvez pas utiliser OAuth2 sans avoir d'abord configuré SAML ou LDAP.

Fonctionnement d'OAuth2 (avec l'API Apigee Edge)

Les appels à l'API Apigee Edge nécessitent une authentification afin que nous puissions nous assurer que vous êtes bien la personne que vous prétendez être. Pour vous authentifier, nous vous demandons d'envoyer un jeton d'accès OAuth2 avec votre requête d'accès à l'API.

Par exemple, si vous souhaitez obtenir des informations sur une organisation sur Edge, vous devez envoyer une requête à une URL semblable à la suivante :

https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

Mais vous ne pouvez pas simplement envoyer cette requête sans nous dire qui vous êtes. Sinon, n'importe qui pourrait voir les informations de votre organisation.

C'est là qu'OAuth2 entre en jeu : pour vous authentifier, nous avons besoin que vous nous envoyiez également un jeton d'accès dans cette requête. Le jeton d'accès nous indique qui vous êtes afin que nous puissions nous assurer que vous êtes autorisé à consulter les informations de l'organisation.

Heureusement, vous pouvez obtenir un jeton en envoyant vos identifiants au service Edge OAuth2. Le service répond avec des jetons d'accès et d'actualisation.

Flux OAuth2 : requête initiale

L'image suivante illustre le flux OAuth2 lorsque vous accédez à l'API Edge pour la première fois :

Schéma de principe OAuth : première requête
Figure 1: Flux OAuth : première requête

Comme le montre la figure 1, lorsque vous effectuez votre requête initiale auprès de l'API Edge :

  1. Vous demandez un jeton d'accès. Vous pouvez le faire avec l' API Edge, acurl ou get_token. Exemple : 
    get_token
Enter username:
ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code if 'ahamilton@apigee.com' is MFA enabled or press ENTER:
123456
  2. Le service Edge OAuth2 répond avec un jeton d'accès et l'imprime dans stdout; : 
    Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

    Les utilitaires acurl et get_token enregistrent silencieusement les jetons d'accès et d'actualisation dans ~/.sso-cli (le jeton d'actualisation n'est pas écrit dans stdout). Si vous utilisez le service Edge OAuth2 pour obtenir des jetons, vous devez les enregistrer vous-même pour une utilisation ultérieure.

  3. Vous envoyez une requête à l'API Edge avec le jeton d'accès. acurl joint automatiquement le jeton : 
    acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval

    Si vous utilisez un autre client HTTP, veillez à ajouter le jeton d'accès. Exemple :

    curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"
  4. L'API Edge exécute votre requête et renvoie généralement une réponse contenant des données.

Flux OAuth2 : requêtes suivantes

Pour les requêtes suivantes, vous n'avez pas besoin d'échanger vos identifiants contre un jeton. Au lieu de cela, vous pouvez simplement inclure le jeton d'accès dont vous disposez déjà, tant qu'il n'a pas encore expiré :

Flux OAuth : requêtes ultérieures
Figure 2: Flux OAuth : requêtes suivantes

Comme le montre la figure 2, lorsque vous disposez déjà d'un jeton d'accès :

  1. Vous envoyez une requête à l'API Edge avec le jeton d'accès. acurl joint automatiquement le jeton. Si vous utilisez d'autres outils, vous devez ajouter le jeton manuellement.
  2. L'API Edge exécute votre requête et renvoie généralement une réponse contenant des données.

Flux OAuth2 : lorsque votre jeton d'accès expire

Lorsqu'un jeton d'accès expire (au bout de 12 heures), vous pouvez utiliser le jeton d'actualisation pour obtenir un nouveau jeton d'accès :

Flux OAuth : actualiser le jeton d'accès
Figure 3: Flux OAuth : actualisation du jeton d'accès

Comme le montre la figure 3, lorsque votre jeton d'accès a expiré :

  1. Vous envoyez une requête à l'API Edge, mais votre jeton d'accès a expiré.
  2. L'API Edge rejette votre requête, car elle n'est pas autorisée.
  3. Vous envoyez un jeton d'actualisation au service Edge OAuth2. Si vous utilisez acurl, cette opération est effectuée automatiquement.
  4. Le service Edge OAuth2 répond avec un nouveau jeton d'accès.
  5. Vous envoyez une requête à l'API Edge avec le nouveau jeton d'accès.
  6. L'API Edge exécute votre requête et renvoie généralement une réponse contenant des données.

Obtenir les jetons

Pour obtenir un jeton d'accès que vous pouvez envoyer à l'API Edge, vous pouvez utiliser les utilitaires Apigee suivants, en plus d'un utilitaire tel que curl :

  • Utilitaire get_token : échange vos identifiants Apigee contre des jetons d'accès et d'actualisation que vous pouvez utiliser pour appeler l'API Edge.
  • Utilitaire acurl : fournit un wrapper pratique autour d'une commande curl standard. Construit des requêtes HTTP auprès de l'API Edge, obtient des jetons d'accès et d'actualisation à partir de get_token, puis transmet le jeton d'accès à l'API Edge.
  • Points de terminaison de jeton dans le service Edge OAuth2 : échangez vos identifiants Apigee contre les jetons d’accès et d’actualisation via un appel à l’API Edge.

Ces utilitaires échangent vos identifiants de compte Apigee (adresse e-mail et mot de passe) contre des jetons dont les durées sont les suivantes :

  • Les jetons d'accès expirent au bout de 12 heures.
  • Les jetons d'actualisation expirent au bout de 30 jours.

Par conséquent, une fois que vous avez effectué un appel d’API avec acurl ou get_token, vous pouvez continuer à utiliser la paire de jetons pendant 30 jours. Après l'expiration, vous devez saisir à nouveau vos identifiants et obtenir de nouveaux jetons.

Accéder à l'API Edge avec OAuth2

Pour accéder à l'API Edge, vous envoyez une requête à un point de terminaison d'API et incluez le jeton d'accès. Vous pouvez le faire avec n'importe quel client HTTP, y compris un utilitaire de ligne de commande tel que curl, une interface utilisateur basée sur un navigateur telle que Postman ou un utilitaire Apigee tel que acurl.

L'accès à l'API Edge avec acurl et curl est décrit dans les sections suivantes.

Utiliser acurl

Pour accéder à l'API Edge avec acurl, votre requête initiale doit inclure vos identifiants. Le service Edge OAuth2 répond avec les jetons d'accès et d'actualisation. acurl enregistre les jetons localement.

Pour les requêtes suivantes, acurl utilise les jetons enregistrés dans ~/.sso-cli. Vous n'avez donc pas besoin d'inclure à nouveau vos identifiants tant que les jetons n'ont pas expiré.

L'exemple suivant montre une requête acurl initiale qui obtient des informations sur l' "ahamilton-eval" organization :

acurl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -u ahamilton@apigee.com
Enter the password for user 'ahamilton@apigee.com'
[hidden input]
Enter the six-digit code (no spaces) if 'ahamilton@apigee.com' is MFA-enabled or press ENTER:
1a2b3c
{
  "createdAt" : 1491854501264,
  "createdBy" : "noreply_iops@apigee.com",
  "displayName" : "ahamilton",
  "environments" : [ "prod", "test" ],
  "lastModifiedAt" : 1491854501264,
  "lastModifiedBy" : "noreply_iops@apigee.com",
  "name" : "ahamilton",
  "properties" : {
    "property" : [ {
      "name" : "features.isSmbOrganization",
      "value" : "false"
    }, {
      "name" : "features.isCpsEnabled",
      "value" : "true"
    } ]
  },
  "type" : "trial"
}

acurl https://api.enterprise.apigee.com/v1/o/ahamilton-eval/apis/helloworld/revisions/1/policies

[ "SOAP-Message-Validation-1", "Spike-Arrest-1", "XML-to-JSON-1" ]

En plus d'obtenir des informations sur l'organisation, cet exemple montre également une deuxième requête qui obtient la liste des règles dans le proxy d'API "helloworld". La deuxième requête utilise l' abréviation "o" pour "organizations" dans l'URL.

Notez que acurl transmet automatiquement le jeton d'accès lors de la deuxième requête. Vous n'avez pas besoin de transmettre vos identifiants utilisateur une fois que acurl a stocké les jetons OAuth2. Il obtient le jeton à partir de ~/.sso-cli pour les appels suivants.

Pour en savoir plus, consultez la section Utiliser acurl pour accéder à l'API Edge.

Utiliser curl

Vous pouvez utiliser curl pour accéder à l'API Edge. Pour ce faire, vous devez d'abord obtenir les jetons d'accès et d'actualisation. Vous pouvez les obtenir à l'aide d'un utilitaire tel que get_token ou du service Edge OAuth2..

Une fois que vous avez enregistré votre jeton d'accès, vous le transmettez dans l' Authorization en-tête de vos appels à l'API Edge, comme le montre l'exemple suivant :

curl https://api.enterprise.apigee.com/v1/organizations/ahamilton-eval \
  -H "Authorization: Bearer ACCESS_TOKEN"

Le jeton d'accès est valide pendant 12 heures après son émission. Une fois le jeton d'accès expiré, le jeton d'actualisation peut être utilisé pendant 30 jours pour émettre un autre jeton d'accès sans nécessiter d'identifiants. Apigee recommande de ne demander un nouveau jeton d'accès qu'après l'expiration du jeton d'actualisation, plutôt que de saisir des identifiants et d'effectuer une nouvelle requête à chaque appel d'API.

Expiration des jetons

Une fois votre jeton d'accès expiré, vous pouvez utiliser le jeton d'actualisation pour obtenir un nouveau jeton d'accès sans avoir à envoyer à nouveau vos identifiants.

La façon dont vous actualisez votre jeton d'accès dépend de l'outil que vous utilisez :

  • acurl : aucune action n'est nécessaire. acurl actualise automatiquement le jeton d'accès lorsque vous envoyez une requête qui en contient un obsolète.
  • get_token: appelez get_token pour actualiser le jeton d'accès.
  • Service Edge OAuth2 : envoyez une requête qui inclut :
    • Jeton d'actualisation
    • Paramètre de formulaire grant_type défini sur "refresh_token"

OAuth2 pour les utilisateurs automatiques

Vous pouvez utiliser les utilitaires acurl et get_token pour créer un script d'accès automatisé aux API Edge avec l'authentification OAuth2 pour les utilisateurs automatiques. L'exemple suivant montre comment utiliser get_token pour demander un jeton d'accès, puis ajouter la valeur du jeton à un appel curl :

  USER=me@example.com
  PASS=not-that-secret
  TOKEN=$(get_token -u $USER:$PASS -m '')
  curl -H "Authorization: Bearer $TOKEN" 'https://api.enterprise.apigee.com/v1/organizations/...'

Vous pouvez également combiner la requête de jeton et l'appel curl à l'aide de l'utilitaire acurl. Exemple :

  USER=me@example.com
  PASS=not-that-secret
  acurl -u $USER:$PASS -m '' 'https://api.enterprise.apigee.com/v1/organizations/...'

Dans les deux exemples, la définition de la valeur de -m sur une chaîne vide empêche l'utilisateur automatique d'être invité à saisir un code MFA.