Cette page a été traduite par l'API Cloud Translation.

Utiliser OAuth2 pour accéder à l'API Edge

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

Apigee Edge vous permet d'effectuer des appels d'API Edge authentifiés avec des jetons OAuth2. La prise en charge d'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 préalablement 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 qui vous prétendez être. Pour vous authentifier, un jeton d'accès OAuth2 doit être envoyé 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 comme celle-ci:

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

Cependant, vous ne pouvez pas envoyer cette demande sans nous indiquer qui vous êtes. Sinon, tout le monde pourrait voir les informations de votre organisation.

C'est là qu'OAuth2 entre en jeu: pour vous authentifier, vous devez nous envoyer é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é à voir les détails de l'organisation.

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

Flux OAuth2: requête initiale

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

**Figure 1**:Flux OAuth: première requête

Comme le montre la figure 1, lorsque vous envoyez votre requête initiale à l'API Edge:

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

Le service Edge OAuth2 répond avec un jeton d'accès et l'imprime sur stdout. Par exemple :

Dy42bGciOiJSUzI1NiJ9.eyJqdGkiOiJhM2YwNjA5ZC1lZTIxLTQ1YjAtOGQyMi04MTQ0MTYxNjNhNTMiLCJz
AJpdGUiLCJhcHByb3ZhbHMubWUiLCJvYXV0aC5hcHByb3ZhbHMiXSwiY2xpZW50X2lkIjoiZWRnZWNsaSIsIm
NjbGkiLCJhenAiOiJlZGdlY2xpIiwiZ3JhbnRfdHlwZSI6InBhc3N3b3JkIiwidXNlcl9pZCI6IjJkMWU3NDI
GzQyMC1kYzgxLTQzMDQtOTM4ZS1hOGNmNmVlODZhNzkiLCJzY29wZSI6WyJzY2ltLm1lIiwib3BlbmlkIiwic
ENC05MzhlLWE4Y2Y2ZWU4NmE3OSIsIm9yaWdpbiI6InVzZXJncmlkIiwidXNlcl9uYW1lIjoiZGFuZ2VyNDI0
RI6ImUyNTM2NWQyIiwiaWF0IjoxNTI4OTE2NDA5LCJleHAiOjE1Mjg5MTgyMDksImlzcyI6Imh0dHBzOi8vbG
420iLCJlbWFpbCI6ImRhbmdlcjQyNDJAeWFob28uY29tIiwiYXV0aF90aW1lIjoxNTI4OTE2NDA5LCJhbCI6M
2lLmNvbSIsInppZCI6InVhYSIsImF1ZCI6WyJlZGdlY2xpIiwic2NpbSIsIm9wZW5pZCIsInBhc3N3b3JkIiw

Les utilitaires acurl et get_token enregistrent en mode silencieux 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.

Vous envoyez une demande à l'API Edge avec le jeton d'accès. acurl associe le jeton automatiquement. Par exemple :
```
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"
```
L'API Edge exécute votre requête et renvoie généralement une réponse avec des données.

Flux OAuth2: requêtes ultérieures

Lors des requêtes suivantes, vous n'avez pas besoin d'échanger vos identifiants contre un jeton. À la place, vous pouvez simplement inclure le jeton d'accès dont vous disposez déjà, tant qu'il n'a pas encore expiré:

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

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

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

Flux OAuth2: expiration de votre jeton d'accès

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

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é:

Vous envoyez une demande à l'API Edge, mais votre jeton d'accès a expiré.
L'API Edge rejette votre requête comme non autorisée.
Vous envoyez un jeton d'actualisation au service Edge OAuth2. Si vous utilisez acurl, cette opération est effectuée automatiquement.
Le service Edge OAuth2 répond avec un nouveau jeton d'accès.
Vous envoyez une demande à l'API Edge avec le nouveau jeton d'accès.
L'API Edge exécute votre requête et renvoie généralement une réponse avec 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 pour une commande curl standard. Construit des requêtes HTTP à destination de l'API Edge, obtient des jetons d'accès et d'actualisation de get_token, et transmet le jeton d'accès à l'API Edge.
Points de terminaison des jetons 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 d'une durée suivante:

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. Passé ce délai, vous devrez 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 de l'API et vous incluez le jeton d'accès. Vous pouvez effectuer cette opération 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 comme 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 les détails de l'organisation "ahamilton-eval" :

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 présente une deuxième requête qui obtient la liste des règles dans le proxy d'API "bonjour". La deuxième requête utilise le raccourcissement "o" pour "organisations" 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 récupère le jeton de ~/.sso-cli pour les appels suivants.

Pour plus d'informations, 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'en-tête Authorization 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 arrivé à expiration, le jeton d'actualisation peut être utilisé pendant 30 jours pour émettre un autre jeton d'accès sans identifiants. Apigee recommande de ne demander un nouveau jeton d'accès qu'après l'expiration du jeton de parrainage, plutôt que de saisir des identifiants et d'envoyer une nouvelle requête à chaque appel d'API.

Expiration des jetons

Une fois votre jeton d'accès arrivé à expiration, vous pouvez l'utiliser pour en obtenir un nouveau sans avoir à renvoyer vos identifiants.

La manière dont vous actualisez votre jeton d'accès dépend de l'outil que vous utilisez:

acurl: aucune action requise. acurl actualise automatiquement le jeton d'accès lorsque vous envoyez une requête en contenant un qui est 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 du formulaire grant_type défini sur "refresh_token"

OAuth2 pour les utilisateurs de machines

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 machine. 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 un utilisateur de la machine d'être invité à saisir un code MFA.