Obtenir des jetons OAuth 2.0

Cette page s'applique à Apigee et à Apigee hybrid.

Consultez la documentation d'Apigee Edge.

Ce document explique comment obtenir des jetons d'accès et des codes d'autorisation OAuth 2.0 avec l'API Apigee. Nous montrons également comment créer des règles pour chaque type d'attribution OAuth 2.0 et configurer les points de terminaison du proxy afin d'accepter les requêtes des clients.

Remarque : Ces exemples illustrent les configurations les plus élémentaires possibles. La règle OAuthV2 comprend de nombreux éléments configurables facultatifs qui ne sont pas mentionnés dans cet article. Pour en savoir plus sur ces éléments, consultez la section sur la stratégie OAuthV2.

Utiliser le type d'attribution du code d'autorisation

Cette section explique comment demander un jeton d'accès à l'aide du flux de type d'attribution du code d'autorisation. La requête de jeton pour ce flux nécessite un code d'autorisation. Consultez la section Obtenir un code d'autorisation. Voir également Qu'est-ce que les types d'attribution OAuth 2.0 ?

Remarque  : La configuration de la règle OAuthV2 dans cette section utilise l'opération GenerateAccessToken. Cette opération génère un format de jeton de chaîne opaque. Vous pouvez également générer des jetons au format JWT en substituant l'opération GenerateJWTAccessToken. Consultez également la section Utiliser des opérations de jetons OAuth JWT.

Exemple de demande

curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://apitest.acme.com/oauth/token' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com' 

Paramètres obligatoires

Par défaut, ces paramètres doivent être x-www-form-urlencoded et spécifiés dans le corps de la requête (comme illustré dans l'exemple ci-dessus). Toutefois, il est possible de modifier ce paramètre par défaut en configurant les éléments <GrantType>, <Code> et <RedirectUri> dans la stratégie OAuthV2. Consultez la stratégie OAuthV2.

• grant_type : doit être défini sur la valeur authorization_code.
• code : code d'autorisation. Consultez la section Demander un code d'autorisation.
• redirect_uri : vous devez fournir ce paramètre si le paramètre redirect_uri a été inclus dans la requête de code d'autorisation précédente. Si le paramètre redirect_uri n'a pas été inclus dans la requête de code d'autorisation et si vous ne fournissez pas ce paramètre, alors cette règle utilise la valeur de l'URL de rappel fournie dans l'application de développeur enregistrée.

Paramètres facultatifs

• state : chaîne qui sera renvoyée avec la réponse. Généralement utilisé pour empêcher les attaques de falsification sur plusieurs sites.
• scope : permet de filtrer la liste des produits API avec lesquels le jeton associé peut être utilisé. Pour plus d'informations sur le champ d'application, consultez la section Utiliser des champs d'application OAuth2.

Autorisation

Vous devez transmettre l'ID client et le code secret du client en tant qu'en-tête d'authentification de base (avec un encodage en base64) ou en tant que paramètres de formulaire client_id et client_secret. Vous obtenez ces valeurs à partir d'une application de développeur enregistrée. Voir aussi Encodage des identifiants d'authentification de base.

Exemple de point de terminaison

Voici un exemple de configuration de point de terminaison permettant de générer un jeton d'accès. Il exécute la stratégie GenerateAccessToken, qui doit être configurée pour accepter le type d'attribution authorization_code.

...
       <Flow name="generate-access-token">
            <Description>Generate a token</Description>
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Exemple de stratégie

Il s'agit d'une stratégie GenerateAccessToken de base configurée pour accepter le type d'attribution authorization_code. Pour plus d'informations sur les éléments de configuration facultatifs que vous pouvez configurer avec cette stratégie, consultez la page Stratégie OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn>
    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>
    <SupportedGrantTypes>
      <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Renvoie

Lorsque <GenerateResponse> est activé, la stratégie renvoie une réponse JSON incluant le jeton d'accès, comme indiqué ci-dessous. Le type d'attribution authorization_code crée un jeton d'accès et un jeton d'actualisation. Par conséquent, une réponse peut se présenter comme suit:

{
    "issued_at": "1420262924658",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420262924658",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "[e-mail]",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi",
    "organization_name": "docs",
    "refresh_token_expires_in": "86399", //--in seconds
    "refresh_count": "0"
}

Remarque : En effet, il est inhabituel de spécifier des valeurs d'expiration en millisecondes dans la stratégie, mais elles sont reçues en secondes dans la charge utile de la réponse. Nous sommes conscients de cette particularité.

Si <GenerateResponse> est défini sur "false", la stratégie ne renvoie pas de réponse. Au lieu de cela, il renseigne l'ensemble de variables de flux suivant avec des données concernant l'attribution de jeton d'accès.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Exemple :

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Utiliser le type d'attribution des identifiants client

Cette section explique comment demander un jeton d'accès à l'aide du flux de type d'attribution des identifiants client. Voir également Qu'est-ce que les types d'attribution OAuth 2.0 ?

Remarque  : La configuration de la règle OAuthV2 dans cette section utilise l'opération GenerateAccessToken. Cette opération génère un format de jeton de chaîne opaque. Vous pouvez également générer des jetons au format JWT en substituant l'opération GenerateJWTAccessToken. Consultez également la section Utiliser des opérations de jetons OAuth JWT.

Exemple de demande

curl -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=client_credentials"

Paramètres obligatoires

• grant_type : doit être défini sur la valeur client_credentials.

  Par défaut, le paramètre obligatoire grant_type doit être x-www-form-urlencoded et spécifié dans le corps de la requête (comme illustré dans l'exemple ci-dessus). Toutefois, il est possible de modifier ce paramètre par défaut en configurant l'élément <GrantType> dans la règle OAuthV2. Par exemple, vous pouvez choisir de transmettre le paramètre dans un paramètre de requête. Pour plus d'informations, consultez la section sur la stratégie OAuthV2.

Paramètres facultatifs

• state : chaîne qui sera renvoyée avec la réponse. Généralement utilisé pour empêcher les attaques de falsification sur plusieurs sites.
• scope : permet de filtrer la liste des produits API avec lesquels le jeton associé peut être utilisé. Pour plus d'informations sur le champ d'application, consultez la section Utiliser des champs d'application OAuth2.

Autorisation

Vous devez transmettre l'ID client et le code secret du client en tant qu'en-tête d'autorisation de base (avec un encodage en base64) ou en tant que paramètres de formulaire client_id et client_secret. Vous obtenez ces valeurs auprès de l'application de développeur enregistrée associée à la requête. Consultez également la section Encoder des identifiants d'authentification de base.

Exemple de point de terminaison

Voici un exemple de configuration de point de terminaison permettant de générer un jeton d'accès. Il exécute la stratégie GenerateAccessToken, qui doit être configurée pour accepter le type d'attribution client_credentials.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Exemple de stratégie

Il s'agit d'une stratégie GenerateAccessToken de base configurée pour accepter le type d'attribution client_credentials. Pour plus d'informations sur les éléments de configuration facultatifs que vous pouvez configurer avec cette stratégie, consultez la page Stratégie OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Renvoie

Lorsque <GenerateResponse> est activé, la stratégie renvoie une réponse JSON. Notez qu'avec le type d'attribution client_credentials, les jetons d'actualisation ne sont pas acceptés. Seul un jeton d'accès est associé. Exemple :

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "[e-mail]",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

Si <GenerateResponse> est défini sur "false", la stratégie ne renvoie pas de réponse. Au lieu de cela, il renseigne l'ensemble de variables de flux suivant avec des données concernant l'attribution de jeton d'accès.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds

Exemple :

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

Utiliser le type d'attribution des mots de passe

Cette section explique comment demander un jeton d'accès à l'aide du flux de type d'attribution des identifiants (mot de passe) du propriétaire de la ressource. Consultez également Mettre en œuvre le type d'attribution de mot de passe. Voir également Qu'est-ce que les types d'attribution OAuth 2.0 ?

Remarque  : La configuration de la règle OAuthV2 dans cette section utilise l'opération GenerateAccessToken. Cette opération génère un format de jeton de chaîne opaque. Vous pouvez également générer des jetons au format JWT en substituant l'opération GenerateJWTAccessToken. Consultez également la section Utiliser des opérations de jetons OAuth JWT.

Exemple de demande

curl -v -k -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=password&username=a_username&password=a_password"

Paramètres obligatoires

Par défaut, ces paramètres doivent être x-www-form-urlencoded et spécifiés dans le corps de la requête (comme illustré dans l'exemple ci-dessus). Toutefois, il est possible de modifier ce paramètre par défaut en configurant les éléments <GrantType>, <Username> et <Password> dans la stratégie OAuthV2. Consultez la stratégie OAuthV2.

Les identifiants utilisateur sont généralement validés par rapport à un stockage d'identifiants à l'aide d'une stratégie LDAP ou JavaScript.

• grant_type : doit être défini sur la valeur password.
• username : nom d'utilisateur du propriétaire de la ressource.
• password : mot de passe du propriétaire de la ressource.

Paramètres facultatifs

• state : chaîne qui sera renvoyée avec la réponse. Généralement utilisé pour empêcher les attaques de falsification sur plusieurs sites.
• scope : permet de filtrer la liste des produits API avec lesquels le jeton associé peut être utilisé. Pour plus d'informations sur le champ d'application, consultez la section Utiliser des champs d'application OAuth2.

Autorisation

Vous devez transmettre l'ID client et le code secret du client en tant qu'en-tête d'autorisation de base (avec un encodage en base64) ou en tant que paramètres de formulaire client_id et client_secret. Vous obtenez ces valeurs auprès de l'application de développeur enregistrée associée à la requête. Consultez également la section Encoder des identifiants d'authentification de base.

Exemple de point de terminaison

Voici un exemple de configuration de point de terminaison permettant de générer un jeton d'accès. Il exécute la stratégie GenerateAccessToken, qui doit être configurée pour accepter le type d'attribution des mots de passe.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Exemple de stratégie

Il s'agit d'une stratégie GenerateAccessToken de base configurée pour accepter le type d'attribution de mots de passe. Pour plus d'informations sur les éléments de configuration facultatifs que vous pouvez configurer avec cette stratégie, consultez la page Stratégie OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
    <SupportedGrantTypes>
      <GrantType>password</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Renvoie

Lorsque <GenerateResponse> est activé, la stratégie renvoie une réponse JSON. Notez qu'avec le type d'attribution de mot de passe, un jeton d'accès et un jeton d'actualisation sont générés. Exemple :

{
    "issued_at": "1420258685042",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420258685042",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "[e-mail]",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "0"
}

Si <GenerateResponse> est défini sur "false", la stratégie ne renvoie pas de réponse. Au lieu de cela, il renseigne l'ensemble de variables de flux suivant avec des données concernant l'attribution de jeton d'accès.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Exemple :

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Utiliser le type d'attribution implicite

Cette section explique comment demander un jeton d'accès à l'aide du flux de type d'attribution implicite. Voir également Qu'est-ce que les types d'attribution OAuth 2.0 ?

Remarque  : La configuration de la règle OAuthV2 dans cette section utilise l'opération GenerateAccessTokenImplicitGrant. Cette opération génère un format de jeton de chaîne opaque. Vous pouvez également générer des jetons au format JWT en substituant l'opération GenerateJWTAccessTokenImplicitGrant. Consultez également la section Utiliser des opérations de jetons OAuth JWT.

Exemple de demande

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://apitest.acme.com/oauth/implicit?response_type=token&client_id=c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ&redirect_uri=http://callback-example.com'

Paramètres obligatoires

Par défaut, ces paramètres doivent être des paramètres de requête, comme indiqué dans l'exemple ci-dessus. Toutefois, il est possible de modifier cette valeur par défaut en configurant les éléments <ResponseType>, <ClientId> et <RedirectUri> dans la stratégie OAuthV2 associée à ce point de terminaison /token. Pour plus d'informations, consultez la section sur la stratégie OAuthV2.

Les identifiants utilisateur sont généralement validés par rapport à un stockage d'identifiants à l'aide d'une stratégie d'appel de service LDAP ou d'une stratégie JavaScript.

• response_type : doit être défini sur la valeur token.
• client_id : ID client d'une application de développeur enregistrée.
• redirect_uri : ce paramètre est obligatoire si un URI de rappel n'a pas été fourni lors de l'enregistrement de l'application de développeur client. Si une URL de rappel a été fournie lors de l'enregistrement du client, elle sera comparée à cette valeur et doit lui correspondre.

Paramètres facultatifs

• state : chaîne qui sera renvoyée avec la réponse. Généralement utilisé pour empêcher les attaques de falsification sur plusieurs sites.
• scope : permet de filtrer la liste des produits API avec lesquels le jeton associé peut être utilisé. Pour plus d'informations sur le champ d'application, consultez la section Utiliser des champs d'application OAuth2.

Autorisation

Ne nécessite pas l'en-tête "Authorization" Cependant, vous devez transmettre un ID client en tant que paramètre de requête.

Exemple de point de terminaison

Voici un exemple de configuration de point de terminaison permettant de générer un jeton d'accès. Il exécute la stratégie GenerateAccessTokenImplicitGrant.

...
       <Flow name="generate-access-token-implicit">
            <Request>
                <Step>
                    <Name>GenerateAccessTokenImplicitGrant</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition>
        </Flow>
...

Exemple de stratégie

Il s'agit d'une stratégie GenerateAccessTokenImplicitGrant de base qui traite les demandes de jeton pour le flux de type d'attribution implicite. Pour plus d'informations sur les éléments de configuration facultatifs que vous pouvez configurer avec cette stratégie, consultez la page Stratégie OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="GenerateAccessTokenImplicit">
    <DisplayName>GenerateAccessTokenImplicit</DisplayName>
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Renvoie

Lorsque <GenerateResponse> est activé, la règle renvoie une redirection de localisation 302 dans l'en-tête de réponse. La redirection pointe vers l'URL spécifiée dans le paramètre redirect_uri et est ajoutée au jeton d'accès et au délai d'expiration du jeton. Notez que le type d'attribution implicite n'est pas compatible avec les jetons d'actualisation. Exemple :

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

Si <GenerateResponse> est défini sur "false", la stratégie ne renvoie pas de réponse. Au lieu de cela, il renseigne l'ensemble de variables de flux suivant avec des données concernant l'attribution de jeton d'accès.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in  //--in seconds

Exemple :

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

Obtenir un code d'autorisation

Dans le flux d'attribution du code d'autorisation, un code d'autorisation est requis pour obtenir un jeton d'accès. Consultez Utiliser le type d'attribution du code d'autorisation. Voir également Qu'est-ce que les types d'attribution OAuth 2.0 ?

Remarque : Le flux de code d'autorisation s'effectue entre un service d'authentification des utilisateurs tiers et Apigee. L'objectif du flux de type d'attribution du code d'autorisation est que les identifiants de l'utilisateur pour le serveur de ressources ne s'affichent jamais pour l'application cliente. Pour en savoir plus sur ce flux, consultez la section Mettre en œuvre le type d'attribution du code d'autorisation.

Exemple de demande

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  "https://apitest.acme.com/oauth/authorize?response_type=code&client_id=c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ&redirect_uri=http://my-callback.com"

Paramètres obligatoires

Par défaut, ces paramètres doivent être des paramètres de requête, comme illustré dans l'exemple ci-dessus. Toutefois, il est possible de modifier ce paramètre par défaut en configurant les éléments <ResponseType>, <ClientId> et <RedirectUri> dans la stratégie OAuthV2. Pour plus d'informations, consultez la section sur la stratégie OAuthV2.

• redirect_uri : si un URI de rappel complet (non partiel) est spécifié dans l'application cliente enregistrée, ce paramètre est facultatif. Sinon, il est obligatoire. Le rappel correspond à l'URL à laquelle Apigee envoie le code d'authentification nouvellement généré. Consultez la section Enregistrer des applications et gérer les clés API.
• response_type : doit être défini sur la valeur code.
• client_id : ID client d'une application de développeur enregistrée.

Paramètres facultatifs

• redirect_uri : si un URI de rappel complet (non partiel) est spécifié dans l'application cliente enregistrée, ce paramètre est facultatif. Sinon, il est obligatoire. Le rappel correspond à l'URL à laquelle Apigee envoie le code d'authentification nouvellement généré. Consultez la section Enregistrer des applications et gérer les clés API.
• state : chaîne qui sera renvoyée avec la réponse. Généralement utilisé pour empêcher les attaques de falsification sur plusieurs sites.
• scope : permet de filtrer la liste des produits API avec lesquels le jeton associé peut être utilisé. Pour plus d'informations sur le champ d'application, consultez la section Utiliser des champs d'application OAuth2.

Autorisation

Ne nécessite pas l'en-tête "Authorization", mais l'ID client de l'application cliente enregistrée doit être fourni dans la requête.

Exemple de stratégie

Il s'agit d'une stratégie de base GenerateAuthorizationCode. Pour plus d'options de configuration, consultez la stratégie OAuthV2:

<OAuthV2 name="GenerateAuthorizationCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Renvoie

Lorsque <GenerateResponse> est activé, la stratégie renvoie le paramètre de requête ?code à l'emplacement redirect_uri (URI de rappel) avec le code d'autorisation associé. Elle est envoyée via une redirection de navigateur 302 avec l'URL figurant dans l'en-tête "Location" de la réponse. Exemple : ?code=123456

Si <GenerateResponse> est défini sur false, la stratégie ne renvoie pas de réponse. Au lieu de cela, elle renseigne l'ensemble de variables de flux ci-dessous avec des données concernant le code d'autorisation.

oauthv2authcode.{policy-name}.code
oauthv2authcode.{policy-name}.scope
oauthv2authcode.{policy-name}.redirect_uri
oauthv2authcode.{policy-name}.client_id

Exemple :

oauthv2authcode.GenerateAuthorizationCode.code
oauthv2authcode.GenerateAuthorizationCode.scope
oauthv2authcode.GenerateAuthorizationCode.redirect_uri
oauthv2authcode.GenerateAuthorizationCode.client_id

Remarque : Vous pouvez également définir des attributs personnalisés dans la règle OAuthV2. Les attributs personnalisés seront renvoyés au même format que les autres variables : oauthv2.{policy_name}.{attribute_name}. Lorsque vous générez un jeton d'accès à partir du code d'authentification, il hérite de toutes les variables personnalisées définies dans le code d'authentification. Consultez également la page Stratégie OAuthV2.

Actualiser un jeton d'accès

Un jeton d'actualisation est un identifiant qui vous permet d'obtenir un jeton d'accès, généralement après que le jeton d'accès a expiré ou devient non valide. Un jeton d'actualisation est renvoyé dans la réponse lorsque vous recevez un jeton d'accès.

Remarque  : La configuration de la règle OAuthV2 dans cette section utilise l'opération RefreshAccessToken. Cette opération actualise un format de jeton de chaîne opaque. Vous pouvez également actualiser les jetons au format JWT en remplaçant l'opération RefreshJWTAccessToken. Consultez également la section Utiliser des opérations de jetons OAuth JWT.

Remarque: Les attributs existants d'un jeton d'accès ne peuvent pas être ajoutés/supprimés/modifiés pendant l'opération RefreshAccessToken. Les valeurs de l'élément ne sont pas traitées dans l'opération RefreshAccessToken. Utilisez la stratégie SetOAuthV2Info pour mettre à jour les attributs.

Exemple de demande

Pour plus d'informations sur l'encodage de l'en-tête d'authentification de base dans l'appel suivant, consultez la section Encoder les identifiants d'authentification de base.

$ curl -X POST \
  -H "Content-type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ" \
  https://apitest.acme.com/oauth/refresh \
  -d "grant_type=refresh_token&refresh_token=yVSL38WpuN3Kzn1UTMoE6AQ4ANZM"

Réglages obligatoires

Par défaut, la stratégie recherche ces paramètres en tant que paramètres x-www-form-urlencoded spécifiés dans le corps de la requête, comme illustré dans l'exemple ci-dessus. Pour configurer un autre emplacement pour ces entrées, vous pouvez utiliser les éléments <GrantType> et <RefreshToken> de la stratégie OAuthV2. Pour plus d'informations, consultez la section sur la stratégie OAuthV2.

• grant_type : doit être défini sur la valeur refresh_token.
• refresh_token : jeton d'actualisation associé au jeton d'accès que vous souhaitez renouveler.

Paramètres facultatifs

• state : chaîne qui sera renvoyée avec la réponse. Généralement utilisé pour empêcher les attaques de falsification sur plusieurs sites.
• scope : permet de filtrer la liste des produits API avec lesquels le jeton associé peut être utilisé. Pour plus d'informations sur le champ d'application, consultez la section Utiliser des champs d'application OAuth2.

Autorisation

Ne nécessite pas l'en-tête "Authorization", mais l'ID client de l'application cliente enregistrée doit être fourni dans la requête.

Lors de l'actualisation d'un jeton d'accès, l'utilisateur n'est pas authentifié de nouveau.

Voici un exemple de configuration de point de terminaison permettant de générer un jeton d'accès à l'aide d'un jeton d'actualisation. Il exécute la stratégie RefreshAccessToken.

 ...
       <Flow name="generate-refresh-token">
            <Request>
                <Step>
                    <Name>RefreshAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
       </Flow>
...

Exemple de stratégie

Il s'agit d'une stratégie RefreshAccessToken de base configurée pour accepter le type d'attribution refresh_token. Pour plus d'informations sur les éléments de configuration facultatifs que vous pouvez configurer avec cette stratégie, consultez la page Stratégie OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
</OAuthV2>

Renvoie

Lorsque <GenerateResponse> est activé, la stratégie renvoie une réponse JSON contenant le nouveau jeton d'accès. Le type d'attribution refresh_token permet de générer des jetons d'accès et des nouveaux jetons d'actualisation. Exemple :

{
    "issued_at": "1420301470489",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "refresh_token_issued_at": "1420301470489",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "[e-mail]",
    "token_type": "BearerToken",
    "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "2"
}

Remarque : La date d'expiration du jeton d'accès et du jeton d'actualisation indiqués dans la réponse est inférieure d'une seconde par rapport à la date spécifiée dans la configuration de stratégie. Cela est dû au délai d'acheminement et à une marge de sécurité. Il est peu courant d'indiquer les valeurs d'expiration en millisecondes dans la stratégie, mais de les recevoir en secondes de charge utile dans la réponse. Nous sommes conscients de cette particularité.

Vous devez savoir qu'après la création d'un nouveau jeton d'actualisation, l'original n'est plus valide.

La réponse ci-dessus correspond à ce que vous obtenez si <GenerateResponse> est défini sur "true". Si <GenerateResponse> est défini sur "false", la stratégie ne renvoie pas de réponse. Au lieu de cela, il renseigne l'ensemble de variables de contexte (flux) suivant avec des données concernant l'attribution de jeton d'accès.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Exemple :

oauthv2accesstoken.RefreshAccessToken.access_token
oauthv2accesstoken.RefreshAccessToken.expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token
oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at
oauthv2accesstoken.RefreshAccessToken.refresh_token_status

Encoder des identifiants d'authentification de base.

Lorsque vous effectuez un appel d'API pour demander un jeton ou un code d'authentification, il est recommandé par la spécification OAuth 2.0 de transmettre les valeurs client_id et client_secret en tant qu'en-tête d'autorisation HTTP de base, comme décrit. dans IETF RFC 2617. Pour ce faire, vous devez encoder en base64 le résultat de la jointure des deux valeurs, en les séparant par deux-points.

En pseudo-code :

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

Où ns4fQc14Zg4hKFCNaSzArVuwszX95X correspond à client_id et ZIjFyTsNgQNyxI au code secret du client.

Exemples

Cet exemple de commande fonctionne sous Linux et MacOS:

export CREDENTIALS=$(echo -n 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' | base64)

Ensuite, vous pouvez envoyer la requête de jeton comme suit :

$ curl -i -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Basic $CREDENTIALS" \
  -X POST "https://apitest.acme.com/oauth/token" \
  -d "grant_type=client_credentials"

Hacher les jetons dans la base de données

Apigee hache tous les jetons d'accès et d'actualisation OAuth pour les protéger en cas de brèche de sécurité sur la base de données. Vous utilisez des jetons non hachés dans les appels d'API, et Apigee les valide par rapport aux versions hachées dans la base de données.

Articles associés

• Mettre en œuvre le type d'attribution des identifiants client
• Mettre en œuvre le type d'attribution du code d'autorisation
• Cours en ligne sur la sécurité des API (inclut OAuth)
• Stratégie OAuthV2 : comprend de nombreux exemples indiquant comment envoyer des requêtes au serveur d'autorisation et comment configurer la stratégie OAuthV2.