Demander des jetons d'accès et des codes d'autorisation

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

Dans cette rubrique, nous vous expliquons comment demander des jetons d'accès et des codes d'autorisation, configurer des points de terminaison OAuth 2.0 et configurer des règles pour chaque type d'autorisation compatible.

Exemple de code

Pour plus de commodité, les règles et les points de terminaison décrits dans cette rubrique sont disponibles sur GitHub dans le projet oauth-doc-examples du dépôt Apigee api-platform-samples. Vous pouvez déployer l'exemple de code et essayer les exemples de requêtes présentés dans cette rubrique. Pour en savoir plus, consultez le fichier README du projet.

Demander un jeton d'accès : 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. Pour plus d'informations sur les types d'attribution OAuth 2.0, consultez la page Présentation d'OAuth 2.0.

Exemple de demande

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
   -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 indiqué dans l'exemple ci-dessus). Cependant, il est possible de modifier cette valeur par défaut en configurant les éléments <GrantType>, <Code> et <RedirectUri> dans la stratégie OAuthV2 associée à ce point de terminaison /accesstoken. Pour plus d'informations, consultez la section sur la stratégie OAuthV2.

  • grant_type : doit être défini sur la valeur authorization_code.
  • code : code d'autorisation reçu de la part du point de terminaison /authorize (ou tout autre nom que vous choisissez de lui donner). Pour demander un jeton d'accès dans le flux de type d'attribution du code d'autorisation, vous devez d'abord obtenir un code d'autorisation. Consultez la section Demander des codes d'autorisation ci-dessous. Consultez également la section Mettre en œuvre le type d'attribution du 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, cette stratégie utilise la valeur de l'URL de rappel fournie lorsque l'application de développeur a été 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.

Authentification

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 pouvez obtenir ces valeurs à partir d'une application de développement enregistrée. 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 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": "tesla@weathersample.com",
    "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"
}

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

Demander un jeton d'accès : type d'attribution d'identifiants client

Cette section explique comment demander un jeton d'accès à l'aide du flux de type d'attribution des identifiants client. Pour plus d'informations sur les types d'attribution OAuth 2.0, consultez la page Présentation d'OAuth 2.0.

Exemple de demande

Pour en savoir plus 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 -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Paramètres obligatoires

Par défaut, le paramètre "grant_type" obligatoire 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 cette valeur par défaut en configurant l'élément <GrantType> dans la stratégie OAuthV2 associée à ce point de terminaison /accesstoken. 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.

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

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.

Authentification

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 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": "tesla@weathersample.com",
    "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

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. Pour plus d'informations sur les types d'attribution OAuth 2.0, consultez la page Présentation d'OAuth 2.0.

Pour en savoir plus sur le type d'attribution des mots de passe, en plus d'une vidéo de quatre minutes sur le sujet, consultez la section Mise en œuvre du type d'attribution de mots de passe.

Exemple de demande

Pour en savoir plus 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 -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST https://docs-test.apigee.net/oauth/token \
  -d 'grant_type=password&username=the-user-name&password=the-users-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 indiqué dans l'exemple ci-dessus). Cependant, il est possible de modifier cette valeur par défaut en configurant les éléments <GrantType>, <Username> et <Password> 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 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.

Authentification

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 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": "tesla@weathersample.com",
    "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

Demander un jeton d'accès : type d'attribution implicite

Cette section explique comment demander un jeton d'accès à l'aide du flux de type d'attribution implicite. Pour plus d'informations sur les types d'attribution OAuth 2.0, consultez la page Présentation d'OAuth 2.0.

Exemple de demande

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://docs-test.apigee.net/oauth/implicit?response_type=token&client_id=ABC123&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.

Authentification

L'attribution implicite ne nécessite pas d'authentification de base. Vous devez transmettre un ID client en tant que paramètre de requête, comme expliqué ici.

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

Si vous utilisez le flux de type d'attribution du code d'autorisation, vous devez obtenir un code d'autorisation avant de pouvoir demander un jeton d'accès.

Exemple de demande

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code'

où une stratégie GenerateAuthorizationCode OAuthV2 est associée au point de terminaison du proxy /oauth/authorize (consultez l'exemple de point de terminaison ci-dessous).

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 /authorize. Pour plus d'informations, consultez la section sur la stratégie OAuthV2.

  • 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 Edge 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.

Authentification

Ne nécessite pas d'authentification de base. Toutefois, l'ID client de l'application cliente enregistrée doit être fourni dans la requête.

Exemple de point de terminaison

Voici un exemple de configuration de point de terminaison permettant de générer un code d'autorisation :


<OAuthV2 name="GenerateAuthorizationCode">
  <Operation>GenerateAuthorizationCode</Operation>
    <!--
    ExpiresIn, in milliseconds. The ref is optional. The explicitly specified
    value is the default, when the variable reference cannot be resolved.
        60000 = 1 minute
       120000 = 2 minutes
    -->
  <ExpiresIn>60000</ExpiresIn>
  <GenerateResponse enabled="true"/>
</OAuthV2>

Exemple de stratégie

Il s'agit d'une stratégie de base GenerateAuthorizationCode. 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="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

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.

Pour demander un nouveau jeton d'accès à l'aide d'un jeton d'actualisation, procédez comme suit :

Exemple de demande

Pour en savoir plus 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://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken \
  -d 'grant_type=refresh_token&refresh_token=my-refresh-token'

Réglages obligatoires

  • 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.

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.

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.

Authentification

  • client_id
  • client_secret

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. Consultez également la section Encoder des identifiants d'authentification de base.

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": "tesla@weathersample.com",
    "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"
}

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

.

Lorsque vous effectuez un appel d'API pour demander un jeton ou un code d'authentification, il est recommandé de respecter la spécification OAuth 2.0 pour transmettre les valeurs client_id et client_secret en tant qu'en-tête d'authentification 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'))

Dans cet exemple, ns4fQc14Zg4hKFCNaSzArVuwszX95X correspond à client_id et ZIjFyTsNgQNyxI au code secret du client.

Quel que soit le langage de programmation utilisé pour calculer la valeur encodée en base64, pour les identifiants client donnés, le résultat encodé en base64 est le suivant : bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==.

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

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

L'utilitaire curl crée en fait l'en-tête HTTP Basic si vous utilisez l'option -u. Ce qui suit équivaut à ce qui précède:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

D'autres environnements de programmation peuvent inclure des raccourcis semblables qui génèrent automatiquement l'en-tête encodé en base64.

Hacher les jetons dans la base de données

Pour protéger les jetons d'accès et d'actualisation OAuth en cas de brèche de sécurité de la base de données, vous pouvez activer le hachage automatique des jetons dans votre organisation Edge. Lorsque cette fonctionnalité est activée, Edge crée automatiquement une version hachée des nouveaux jetons d'accès et d'actualisation OAuth à l'aide de l'algorithme que vous spécifiez. Vous trouverez ci-dessous des informations concernant le hachage groupé des jetons existants. Les jetons non hachés sont utilisés dans les appels d'API, et Edge les valide par rapport aux versions hachées de la base de données.

Les propriétés suivantes au niveau de l'organisation contrôlent le hachage des jetons OAuth.

features.isOAuthTokenHashingEnabled = true
features.OAuthTokenHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Si vous disposez de jetons hachés existants et que vous souhaitez les conserver jusqu'à leur expiration, définissez les propriétés suivantes dans votre organisation, où l'algorithme de hachage correspond à l'algorithme existant (par exemple, SHA1, l'ancienne valeur par défaut Edge). Si les jetons n'ont pas été hachés, utilisez PLAIN.

features.isOAuthTokenFallbackHashingEnabled = true
features.OAuthTokenFallbackHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Si vous êtes un client Edge Cloud, contactez l'assistance Apigee Edge pour définir ces propriétés sur votre organisation et éventuellement pour hacher les jetons existants de manière groupée.

Articles associés