Utiliser des jetons OAuth tiers

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

Dans cette rubrique, nous verrons comment importer des jetons d'accès générés en externe, des jetons d'actualisation ou des codes d'autorisation dans le magasin de jetons Edge. Vous pouvez utiliser cette technique si vous souhaitez configurer Apigee Edge pour valider les jetons générés en dehors d'Apigee Edge.

Habituellement, Apigee Edge génère et stocke un jeton OAuth, puis le renvoie à l'application appelante. L'application appelante présente ensuite ce jeton à Apigee Edge lors de la demande de service, et Apigee Edge vérifie que le jeton est valide (via la stratégie OAuthV2 avec Operation = VerifyAccessToken). Cette rubrique explique comment configurer Apigee Edge pour stocker un jeton OAuth généré à l'extérieur, tout en conservant la même partie de la validation, comme si le jeton avait été généré par Edge.

Exemple

Si vous souhaitez voir un exemple fonctionnel illustrant les techniques décrites dans cette rubrique, consultez l'exemple de gestion des jetons déléguée d'Apigee.

Plus d'infos

Supposons que vous disposez d'un système d'autorisation existant et que vous souhaitiez utiliser les valeurs de jeton ou de code générées par ce système au lieu du jeton ou du code de protocole OAuth2 générés par Edge. Vous pouvez ensuite effectuer des demandes sécurisées de proxy d'API avec un jeton ou un code substitué. Edge les validera comme si elles avaient été générées par Edge.

Informations générales

Dans le cas habituel, Apigee Edge génère un jeton en produisant une chaîne aléatoire de lettres et de chiffres. Apigee Edge associe à ce jeton d'autres données telles que l'heure d'émission du jeton, son expiration, la liste des produits d'API pour lesquels le jeton est valide et le champ d'application. Toutes ces informations peuvent être renvoyées dans une réponse générée automatiquement par la stratégie OAuthV2 configurée avec l'opération Operation = GenerateAccessToken. La réponse est semblable à ce qui suit :

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "zBC90HhCGmGlaMBWeZAai2s3za5j",
  "organization_name": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

La valeur de l'attribut access_token est effectivement la clé de recherche des données de réponse. Une application peut envoyer une requête à un proxy d'API hébergé dans Edge, portant le jeton de support zBC90HhCGmGlaMBWeZAai2s3za5j, et Edge - avec la stratégie OAuthV2 avec Opération = VerifyAccessToken - recherchera le jeton, récupérera toutes les informations et utiliser ces informations pour déterminer si le jeton est valide ou non, pour le proxy d'API demandé. C'est ce qu'on appelle la validation de jeton. Toutes les informations ci-dessus comprennent le jeton. La valeur access_token est un moyen de rechercher cette information.

D'autre part, en suivant les étapes décrites ici, vous pouvez configurer Edge pour stocker un jeton afin que sa valeur access_token soit générée par un service externe. Toutes les autres métadonnées peuvent être identiques. Par exemple, supposons que vous disposiez d'un système externe à Apigee Edge qui génère des jetons sous la forme "TOKEN-<16 random number>" . Dans ce cas, les métadonnées de jeton complètes stockées par Apigee Edge peuvent être:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "TOKEN-1092837373654221",
  "organization_name": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

Dans ce cas, une application peut envoyer une requête à un proxy d'API hébergé dans Edge, en transportant le jeton de support TOKEN-1092837373654221, et Edge - via la stratégie OAuthV2 avec Operation = VerifyAccessToken - sera en mesure de le valider. Vous pouvez appliquer un schéma d'importation similaire aux codes d'autorisation et aux jetons d'actualisation.

Voyons comment valider les identifiants client

L'une des conditions préalables à la génération d'un jeton consiste à valider le client demandeur. Par défaut, la stratégie OAuthV2/GenerateAccessToken dans Apigee Edge vérifie implicitement les identifiants du client. Normalement, dans une requête de jeton OAuthV2, les champs client_id et client_secret sont transmis dans l'en-tête Authorization, encodés via l'autorisation de base HTTP (concaténés deux-points, puis encodés en base64). La stratégie OAuthV2/GenerateAccessToken dans Apigee Edge décode cet en-tête et recherche le client_id, puis vérifie que le client_secret transmis est valide pour ce client_id. Cela fonctionne si les identifiants sont connus d'Apigee Edge : en d'autres termes, il existe une application de développeur stockée dans Apigee Edge et contenant des identifiants, qui contiennent eux-mêmes les client_id et client_secret donnés.

Dans le cas où les identifiants du client ne doivent pas être validés par Apigee Edge, vous devez concevoir votre proxy d'API avant qu'il ne génère un jeton, afin de valider explicitement le client par d'autres moyens. Ceci est souvent via une règle ServiceCallout qui se connecte à un point de terminaison distant de votre réseau.

D'une manière ou d'une autre, implicitement ou explicitement, vous devez vous assurer que le proxy d'API qui génère des jetons valide d'abord les identifiants client. N'oubliez pas que la validation du client est indépendante de la génération du jeton d'accès. Vous pouvez configurer Apigee Edge pour effectuer les deux, l'une ou l'autre, ou aucune.

Si vous souhaitez que la stratégie OAuthV2/GenerateAccessToken dans Apigee Edge valide les identifiants du client par rapport au magasin Edge, définissez l'élément <ExternalAuthorization> sur false dans la configuration de la stratégie ou omettez-le complètement. Si vous souhaitez utiliser un service d'autorisation externe pour valider explicitement les identifiants client, définissez <ExternalAuthorization> sur true.

Bien qu'Apigee Edge puisse ne pas valider les identifiants du client, il est toujours nécessaire que le client_id soit connu et géré par Apigee Edge. Chaque access_token dans Apigee Edge, qu'il soit généré par Apigee Edge ou par un système externe, puis importé dans Apigee Edge, doit être associé à une application cliente - indiqué par le client_id. Ainsi, même dans le cas où la stratégie OAuthV2/GenerateAccessToken dans Apigee Edge ne valide pas la correspondance entre client_id et client_secret, la stratégie confirme que client_id est valide, présent et non révoqué. Ainsi, en tant qu'étape de configuration préalable, vous devrez peut-être importer les client_id via l'API d'administration Edge.

Flux de stratégie pour OAuth tiers sur Apigee

Pour utiliser des jetons de systèmes OAuth tiers dans Apigee Edge, le flux de génération de jetons d'accès doit suivre l'un des modèles suivants.

Validation externe des identifiants client

  1. ServiceCallout pour vérifier les identifiants du client entrant, et acquérir un jeton externe.
  2. ExtractVariables ou une étape JavaScript pour extraire le jeton généré en externe à partir de la réponse.
  3. AssignMessage pour définir la variable bien connue nommée oauth_external_authorization_status. La valeur doit être vraie pour indiquer que les identifiants du client sont valides.
  4. OAuthV2/GenerateAccessToken avec l'élément <ExternalAuthorization> défini sur true et au moins l'une des valeurs <ExternalAccessToken>, <ExternalRefreshToken> ou <ExternalAuthorizationCode>.

Validation interne des identifiants client

  • ServiceCallout pour acquérir un jeton externe.
  • ExtractVariables ou une étape JavaScript pour extraire le jeton généré en externe à partir de la réponse.
  • OAuthV2/GenerateAccessToken avec l'élément <ExternalAuthorization> défini sur false et au moins l'une des valeurs <ExternalAccessToken>, <ExternalRefreshToken> ou <ExternalAuthorizationCode>.

Remarques sur la configuration du flux et des stratégies

  • Si vous souhaitez utiliser un système externe pour valider les identifiants client, il vous incombe de développer un flux de stratégies qui effectue les tâches nécessaires. Normalement, une règle ServiceCallout envoie les identifiants reconnus en externe au service d'authentification externe. Le service d'authentification externe renvoie généralement une réponse et, si les identifiants sont valides, un jeton d'accès.

  • Après le ServiceCallout, le proxy d'API doit analyser la réponse pour extraire l'état de validité, ainsi que le paramètre access_token généré de manière externe et éventuellement le paramètre refresh_token.

  • Dans la stratégie OAuthV2/GenerateAccessToken, définissez l'élément <StoreToken> sur true et l'élément <ExternalAuthorization> sur true ou false selon le cas.

    Lorsque la stratégie OAuthV2/GenerateAccessToken s'exécute, elle lit la variable oauth_external_authorization_status. Si la variable est définie et que la valeur est "true", Apigee Edge ne tente pas de valider les identifiants du client. Si la variable n'est pas définie ou si la valeur n'est pas vraie, Apigee Edge tentera de valider les identifiants du client.

  • La règle OAuthV2 comprend trois éléments qui vous permettent de spécifier les données externes à importer : <ExternalAccessToken>, <ExternalRefreshToken> et <ExternalAuthorizationCode>. Chacun de ces éléments accepte une variable de flux. La stratégie Edge lit cette variable pour trouver le jeton d'accès, le jeton d'actualisation ou le code d'autorisation généré en externe. Il vous appartient de mettre en œuvre des stratégies et des logiques pour placer les jetons ou codes externes dans les variables appropriées.

    Par exemple, la configuration suivante de la stratégie OAuthV2 indique à Edge de rechercher le jeton dans une variable de contexte nommée external_token.

    <ExternalAccessToken>external_token</ExternalAccessToken>
    

    Vous devez également disposer d'une étape précédente qui définit cette variable.

  • Concernant la définition de la variable oauth_external_authorization_status, une technique courante de définition de cette variable consiste à utiliser une stratégie AssignMessage avec l'élément AssignVariable, comme suit :

    <AssignMessage name="AssignMessage-SetVariable">
        <DisplayName>Assign Message - Set Variable</DisplayName>
        <AssignVariable>
            <Name>oauth_external_authorization_status</Name>
            <Value>true</Value>
        </AssignVariable>
        <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    </AssignMessage>
    

    N'oubliez pas que cette stratégie doit précéder la stratégie OAuthV2 avec Operation = GenerateAccessToken.

Exemple de règle OAuthV2

La stratégie OAuthV2 suivante génère un jeton d'accès Apigee Edge si Edge trouve une valeur de jeton dans la variable de flux external_access_token.

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <ExternalAccessToken>external_access_token</ExternalAccessToken>
    <ExternalAuthorization>true</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <GenerateResponse enabled="true">
        <Format>FORM_PARAM</Format>
    </GenerateResponse>
    <ReuseRefreshToken>false</ReuseRefreshToken>
    <StoreToken>true</StoreToken>
    <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <ExpiresIn ref='flow.variable'>2400000</ExpiresIn>
</OAuthV2>

En théorie, vous pouvez appliquer ce modèle avec n'importe quel service d'autorisation tiers OAuth2.