Mettre en œuvre le type d'attribution du code d'autorisation

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

Le code d'autorisation est l'un des types d'attribution OAuth 2.0 les plus couramment utilisés. Le flux de code d'autorisation est une configuration "OAuth à trois acteurs". Dans cette configuration, l'utilisateur s'authentifie auprès du serveur de ressources et permet à l'application d'accéder à ses ressources protégées sans divulguer les noms d'utilisateur et mots de passe à l'application cliente.

À propos de ce sujet

Cet article propose une description et une présentation générales du flux de type d'attribution OAuth 2.0, et explique comment mettre en œuvre ce flux sur Apigee Edge.

Vidéo

Regardez une courte vidéo pour apprendre à sécuriser vos API à l'aide du type d'attribution d'autorisation OAuth 2.0.

Cas d'utilisation

Ce type d'attribution d'autorisation est destiné aux applications écrites par des développeurs tiers qui n'ont pas de relation commerciale de confiance avec le fournisseur d'API. Par exemple, les développeurs inscrits à des programmes d'API publics ne doivent généralement pas être approuvés. Avec ce type d'attribution, les identifiants de l'utilisateur sur le serveur de ressources ne sont jamais partagés avec l'application.

Exemple de code

Vous trouverez un exemple d'implémentation complète et fonctionnelle du type d'attribution de code d'autorisation sur Apigee Edge dans le dépôt api-platform-samples sur GitHub. Consultez l'exemple oauth-advanced dans le répertoire api-platform-samples/sample-proxies. Consultez le fichier README pour obtenir des détails sur l'exemple.

Schéma de flux

Le schéma de flux suivant illustre le flux OAuth de code d'autorisation avec Apigee Edge en tant que serveur d'autorisation.

Conseil:Pour afficher une version plus grande de ce diagramme, effectuez un clic droit dessus et ouvrez-le dans un nouvel onglet, ou enregistrez-le et ouvrez-le dans une visionneuse d'images.

Étapes du flux du code d'autorisation

Voici un résumé des étapes requises pour mettre en œuvre le type d'attribution de code d'autorisation où Apigee Edge sert de serveur d'autorisation. N'oubliez pas que l'objectif de ce flux est que le client ne doit jamais avoir accès aux identifiants de l'utilisateur sur le serveur de ressources.

Conditions préalables : l'application cliente doit être enregistrée auprès d'Apigee Edge pour obtenir l'ID client et les clés secrètes du client. Pour en savoir plus, consultez la section Enregistrer des applications clientes.

1. L'utilisateur lance le flux

Lorsque l'application doit accéder aux ressources protégées de l'utilisateur à partir d'un serveur de ressources (par exemple, une liste de contacts sur un site de réseaux sociaux), elle envoie un appel d'API à Apigee Edge, qui valide l'ID du client et qui, le cas échéant, redirige le navigateur de l'utilisateur vers une page de connexion depuis laquelle l'utilisateur saisit ses identifiants. L'appel d'API comprend des informations obtenues par l'application cliente lors de son enregistrement : l'ID client et l'URI de redirection.

2. L'utilisateur saisit ses identifiants

L'utilisateur accède alors à une page de connexion lui demandant de saisir ses identifiants. Si la connexion est établie, passez à l'étape suivante.

3. L'utilisateur donne son autorisation

Au cours de cette étape, l'utilisateur autorise l'application à accéder à ses ressources. Le formulaire d'autorisation inclut généralement les sélections de champs d'application, permettant à l'utilisateur de choisir ce que l'application est autorisée à faire sur le serveur de ressources. Par exemple, l'utilisateur peut accorder une autorisation en lecture seule ou autoriser l'application à modifier des ressources.

4. L'application de connexion envoie une requête Apigee Edge

Si la connexion et le consentement aboutissent, l'application de connexion crée (POST) des données sur le point de terminaison /coded'autorisation d'Apigee Edge. Les données incluent l'URI de redirection, l'ID client, le champ d'application, les informations spécifiques à l'utilisateur qu'elle souhaite inclure, ainsi qu'une indication selon laquelle la connexion a réussi.

5. Apigee Edge génère un code d'autorisation

Lorsque Edge reçoit une requête GET de l'application de connexion sur son point de terminaison /permissioncode, deux choses se produisent. Tout d'abord, Edge détermine que la connexion a réussi (en vérifiant le statut HTTP ou d'autres moyens). Next Edge vérifie que l'URI de redirection envoyé à partir de l'application de connexion correspond à l'URI de redirection spécifié lors de l'enregistrement de l'application auprès d'Apigee Edge. Si tout va bien, Edge génère un code d'autorisation. Exemple :

http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

6. Edge renvoie le code d'autorisation au client

Edge envoie une redirection 302 avec le code d'autorisation joint en tant que paramètre de requête au client.

7. Le client récupère le code d'autorisation et demande un code d'accès à Edge

Désormais, avec un code d'autorisation valide, le client peut demander un jeton d'accès à Edge. Pour ce faire, il publie (POST) l'ID client et les clés secrètes du client (obtenus lors de l'enregistrement de l'application sur Edge), le type d'attribution et le champ d'application. En incluant l'ID client et les clés secrètes, Apigee Edge peut vérifier que l'application cliente est celle qui a été enregistrée. Exemple :

$ curl https://{org_name}-test.apigee.net/my_oauth_proxy/accesstoken?code=Xyz123&grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpKNhGar6K&client_secret=hAr4GngA9vAyvI4'

8. Le client reçoit un jeton d'accès

Si tout réussit, Edge renvoie un jeton d'accès au client. Le jeton d'accès comporte une date d'expiration et n'est valide que pour le champ d'application spécifié par l'utilisateur lorsqu'il a autorisé l'application à accéder à ses ressources.

9. Le client appelle l'API protégée

Maintenant qu'il dispose d'un code d'accès valide, le client peut appeler l'API protégée. Dans ce scénario, les requêtes sont adressées à Apigee Edge (le proxy) et Edge est responsable de la validation du jeton d'accès avant de transmettre l'appel d'API au serveur de ressources cible. Les jetons d'accès sont transmis dans un en-tête d'autorisation. Exemple :

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

Configurer les flux et les règles

En tant que serveur d'autorisation, Edge doit traiter un certain nombre de requêtes OAuth : pour les jetons d'accès, les codes d'autorisation, les jetons d'actualisation, les redirections de page de connexion, etc. Il existe deux étapes fondamentales pour configurer ces points de terminaison :

  • Créer des flux personnalisés
  • Ajouter et configurer des règles OAuthV2

Configuration de flux personnalisé

Vous configurez généralement ce flux de type d'attribution de sorte que chaque étape ou "acteur" du flux soit défini par un flux dans le proxy Apigee Edge. Chaque flux possède un point de terminaison et une règle qui effectue la tâche spécifique OAuth requise, telle que la génération d'un code d'autorisation ou d'un jeton d'accès. Par exemple, comme indiqué dans le XML ci-dessous, le point de terminaison /oauth/authorizationcode possède une règle associée appelée GenerateAuthCode (qui est une règle OAuthV2 avec l'opération GenerateAuthorizationCode spécifiée).

Le moyen le plus simple d'afficher la configuration de flux consiste à utiliser un exemple XML. Consultez les commentaires en ligne pour obtenir des informations sur chaque flux. Ceci est un exemple ; les noms de flux et de chemins d'accès peuvent être configurés à votre guise. Consultez la section Configurer des points de terminaison et des stratégies OAuth pour obtenir un aperçu rapide des étapes nécessaires à la création d'un flux personnalisé de ce type.

Consultez également l'exemple de mise en œuvre sur GitHub.

<Flows>
<Flow name="RedirectToLoginApp">
<!--
Publish this URI to developers to use for their 'login' link
-->
<Condition>proxy.pathsuffix == "/oauth/authorize"</Condition>
<Request>
<Step><Name>RedirectToLoginPage</Name></Step>
</Request>
</Flow>
<Flow name="GetAuthCode">
<!--
Call this URL from your Login app after you authenticate the user.
The policy will automatically return the auth code in the response to the
redirect_uri registered by the calling app
-->
<Condition>proxy.pathsuffix == "/oauth/authorizationcode"</Condition>
<Request>
<Step><Name>GenerateAuthCode</Name></Step>
</Request>
</Flow>
<Flow name="GetAccessToken">
<!-- This policy flow is triggered when the URI path suffix
matches /oauth/accesstoken. Publish this URL to app developers
to use when obtaining an access token using an auth code
-->
<Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
<Request>
<Step><Name>GenerateAccessToken</Name></Step>
</Request>
</Flow>
</Flows>

Configurer les flux avec des stratégies

Chaque point de terminaison est associé à une stratégie. Examinons des exemples de stratégies. Consultez également la page Configurer des points de terminaison et des règles OAuth pour obtenir un aperçu rapide des étapes nécessaires à l'ajout de stratégies OAuthV2 aux points de terminaison de proxy.

Redirection de connexion

Il s'agit du chemin d'accès /oauth/authorize. La règle associée doit rediriger l'utilisateur vers une application de connexion, où l'utilisateur final peut s'authentifier et autoriser en toute sécurité l'application cliente à accéder à ses ressources protégées sans divulguer son nom d'utilisateur et son mot de passe à l'application cliente. Pour ce faire, vous pouvez utiliser une règle d'appel de service, JavaScript, Node.js ou d'autres moyens.

L'appel d'API pour effectuer la requête est une opération GET, et nécessite les paramètres de requête "client_id" (ID client), "response_type" (type de réponse), "redirect_uri" (URI de redirection), "scope" (champ d'application) et "state" (état).

$ curl http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

Obtenir le code d'autorisation

Il s'agit du chemin d'accès /oauth/authorizationcode. Il utilise la stratégie OAuthV2 avec l'opération GenerateAuthorizationCode spécifiée.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GetAuthCode">
    <DisplayName>GetAuthCode</DisplayName>
    <Operation>GenerateAuthorizationCode</Operation>
    <ExpiresIn>600000</ExpiresIn>
    <GenerateResponse/>
</OAuthV2>

L'appel d'API pour obtenir le code d'autorisation est une opération GET et nécessite les paramètres de requête "client_id" (ID client), "response_type" (type de réponse), et éventuellement "scope" (champ d'application) et "state" (état), comme illustré dans cet exemple :

$curl http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&scope=scope1%20scope2&state={some_string}

Obtenir un jeton d'accès

Cette règle est associée au chemin d'accès /oauth/accesstoken. Il utilise la stratégie OAuthV2 avec l'opération GenerateAccessCode spécifiée. Dans ce cas, le paramètre grant_type est attendu en tant que paramètre de requête :

<OAuthV2 name="GetAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>360000000</ExpiresIn> 
    <SupportedGrantTypes> 
        <GrantType>authorization_code</GrantType> 
    </SupportedGrantTypes> 
    <GrantType>request.queryparam.grant_type</GrantType> 
    <GenerateResponse/> 
</OAuthV2>

L'appel d'API pour obtenir le code d'accès est une opération POST et doit inclure les paramètres "client_id", "client_secret", "grant_type=authorization_code" et éventuellement "scope". Exemple :

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

Ceci est un simple résumé. Un exemple de production comprend de nombreuses autres règles pour créer des URL, effectuer des transformations et effectuer d'autres tâches. Consultez l'exemple sur GitHub pour obtenir un projet complet et fonctionnel.

Associer la règle de vérification du jeton d'accès

Associez une stratégie VerifyAccessToken (stratégie OAuthV2 avec l'opération VerifyAccessToken spécifiée) au début d'un flux accédant à une API protégée, afin qu'elle soit exécutée à chaque fois qu'une requête de ressources protégées est envoyée. Edge vérifie que chaque requête dispose d'un jeton d'accès valide. Sinon, une erreur est renvoyée. Pour connaître la procédure de base, consultez Valider des jetons d'accès.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
    <DisplayName>VerifyAccessToken</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
</OAuthV2>

Appeler l'API protégée

Pour appeler une API protégée par la sécurité OAuth 2.0, vous devez présenter un jeton d'accès valide. Le format correct consiste à inclure le jeton dans un en-tête "Authorization", comme suit. Notez que le jeton d'accès est également appelé "jeton de support".

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282 

Consultez également la section Envoyer un jeton d'accès.