Utiliser des jetons OAuth tiers

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

Consultez la documentation d'Apigee Edge.

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'authentification dans le magasin de jetons Apigee. Vous pouvez utiliser cette technique si vous souhaitez configurer Apigee pour valider les jetons générés en dehors d'Apigee.

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

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 en place et que vous souhaitiez utiliser les valeurs de jeton ou de code générées par ce système à la place des valeurs de jeton ou du code de protocole OAuth2 générés par Apigee. Vous pouvez ensuite effectuer des demandes sécurisées de proxy d'API avec le jeton ou le code substitué. Apigee les validera comme si elles avaient été générées par Apigee.

Informations générales

Dans le cas habituel, Apigee génère un jeton en générant une chaîne aléatoire de lettres et de chiffres. Apigee associe ce jeton à d'autres données telles que l'heure d'émission du jeton, l'expiration, la liste des produits API pour lesquels le jeton est valide, ainsi que 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": "myorg",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

La valeur access_token est utilisée par Apigee pour récupérer les métadonnées du jeton. Par exemple, supposons qu'une requête de proxy d'API inclut le jeton de support zBC90HhCGmGlaMBWeZAai2s3za5j. À l'aide de la valeur du jeton, Apigee récupère les métadonnées du jeton pour déterminer si le jeton est valide ou non.

En suivant la procédure décrite ici, vous pouvez configurer Apigee pour stocker un jeton dont la valeur access_token a été générée par un service externe. Par exemple, supposons que vous disposiez d'un système externe à Apigee qui génère des jetons sous la forme "TOKEN-<16 random numbers>" . Dans ce cas, les métadonnées de jeton complètes stockées par Apigee peuvent être les suivantes :

{
  "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": "myorg",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

Dans ce cas, une application peut envoyer une requête à un proxy d'API disposant du jeton de support TOKEN-1092837373654221, et Apigee pourra 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 d'Apigee vérifie implicitement les identifiants client. Normalement, dans une requête de jeton OAuthV2, les valeurs client_id et client_secret sont transmises dans l'en-tête "Authorization", encodé via l'autorisation HTTP de base (deux-points concaténés, puis encodée en base64). La stratégie OAuthV2/GenerateAccessToken d'Apigee décode cet en-tête et recherche le champ client_id, et vérifie que le paramètre client_secret transmis est valide pour ce client_id. Cela fonctionne si les identifiants sont connus pour Apigee. En d'autres termes, il existe une application de développeur stockée dans Apigee qui contient un identifiant, qui contient les client_id et client_secret donnés.

Dans le cas où les identifiants client ne doivent pas être validés par Apigee, vous devez concevoir votre proxy d'API, avant de générer un jeton, pour 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.

Dans l'un ou l'autre, de manière implicite ou explicite, vous devez vous assurer que le proxy d'API qui génère des jetons commence par valider 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 pour qu'il effectue l'une ou l'autre des opérations, les deux ou aucune.

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

Bien qu'Apigee ne puisse pas valider les identifiants client, il est toujours nécessaire que client_id soit connu et géré par Apigee. Chaque élément access_token d'Apigee, généré par Apigee ou généré par un système externe, puis importé dans Apigee, doit être associé à une application cliente, comme indiqué par client_id. Ainsi, même si la stratégie OAuthV2/GenerateAccessToken d'Apigee ne valide pas la correspondance des valeurs client_id et client_secret, elle vérifie que le champ client_id est valide, actuel et non révoquée. Par conséquent, vous devrez peut-être effectuer cette étape préalable et importer les client_id via l'API d'administration Apigee.

Flux de stratégie pour OAuth tiers sur Apigee

Pour utiliser des jetons à partir de systèmes OAuth tiers dans Apigee, le flux permettant de générer des jetons d'accès doit respecter l'un des formats suivants.

Validation externe des identifiants client

ServiceCallout pour vérifier les identifiants du client entrant, et acquérir un jeton externe.
ExtractVariables ou une étape JavaScript pour extraire le jeton généré en externe à partir de la réponse.
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.
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 n'essaie pas de valider les identifiants client. Si la variable n'est pas définie ou si la valeur n'est pas définie sur "true", Apigee tente de valider les identifiants 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 Apigee lira cette variable pour rechercher le jeton d'accès généré en externe, le jeton d'actualisation ou le code d'autorisation. 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 à Apigee 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 étant donné qu'Apigee trouve une valeur de jeton dans la variable de flux external_access_token.

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <DisplayName>OAuth v2.0 1</DisplayName>
    <Attributes/>
    <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>

Normalement, avec le type d'attribution des identifiants client, vous devez fournir un en-tête d'authentification de base avec l'ID client et le code secret du client encodés. Toutefois, dans ce cas, vous n'avez pas besoin de fournir cet en-tête. La stratégie s'attend toujours à ce que la valeur client_id soit présente dans la requête, et la règle la validera. Apigee s'attend à ce que la valeur client_id soit envoyée dans les données du formulaire de requête, par exemple dans request.formparam.client_id.

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