Vous consultez la documentation d'Apigee Edge.
Consultez la
documentation Apigee X. en savoir plus
Version: 1.3.1
Authentifiez-vous auprès de Google pour accéder aux API Google que vous spécifiez.
Utilisez cette extension afin d'obtenir un jeton (OAuth ou JWT) pour les services Google Cloud, puis utilisez-le pour les appels suivants à l'API Google, par exemple à l'aide d'une règle ServiceCallout.
Par exemple, dans un proxy d'API, vous pouvez obtenir un jeton avec cette extension, le mettre en cache à l'aide de la règle PopulateCache, puis le transmettre via la règle ServiceCallout pour accéder aux services Google Cloud à partir d'un flux de proxy d'API.
Conditions préalables
Ce contenu fournit une documentation de référence sur la configuration et l'utilisation de cette extension. Avant d'utiliser l'extension à partir d'un proxy d'API avec la règle ExtensionCallout, vous devez:
Assurez-vous que le compte que l'extension utilisera (c'est-à-dire le compte représenté par le compte de service que vous utiliserez pour les identifiants) a accès aux services Google Cloud avec lesquels l'extension s'authentifiera.
Utilisez la console Google Cloud afin de générer une clé pour le compte de service.
Utilisez le contenu du fichier JSON de clé de compte de service obtenu lorsque vous ajoutez et configurez l'extension à l'aide des documents de référence de configuration.
À propos de l'authentification avec Google Cloud
Cette extension demande une authentification à Google Cloud en représentant un membre spécifique défini dans votre projet Google Cloud. Utilisez le fichier JSON du compte de service de ce membre du projet lorsque vous configurez cette extension.
Cette extension n'aura alors accès qu'aux ressources pour lesquelles ce membre dispose des autorisations nécessaires. En d'autres termes, la réussite de l'authentification par cette extension dépend de la correspondance entre les autorisations accordées dans la console Google Cloud et les accès demandés par l'extension (via les niveaux d'accès ou l'audience) au moment de l'exécution.
En règle générale, voici la procédure à suivre pour vous authentifier afin d'accéder aux API à partir de cette extension:
Assurez-vous que le compte de service membre que représente cette extension a accès à la ressource Google à laquelle vous souhaitez accéder. Vous pouvez utiliser la page Cloud Identity and Access Management (Cloud IAM) de la console Google Cloud pour attribuer des rôles au membre du projet représenté par cette extension.
Utilisez le fichier JSON de la clé de compte de service de ce membre lors de la configuration de cette extension.
Lorsque vous configurez une règle ExtensionCallout pour utiliser cette extension, demandez une authentification uniquement pour les ressources auxquelles le membre du projet a accès.
Samples
Les exemples suivants montrent comment s'authentifier auprès de Google Cloud à l'aide de la règle ExtensionCallout.
Obtenir un jeton d'accès
Dans l'exemple suivant, l'action getOauth2AccessToken
de l'extension récupère un jeton à utiliser dans les requêtes adressées à l'API Cloud Translation.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ConnectorCallout async="false" continueOnError="true" enabled="true" name="Get-Access-Token">
<DisplayName>Get Access Token</DisplayName>
<Connector>google-auth</Connector>
<Action>getOauth2AccessToken</Action>
<Input><![CDATA[{
"scope" : [
"https://www.googleapis.com/auth/cloud-translation"
]
}]]></Input>
<Output>google.credentials</Output>
</ConnectorCallout>
La valeur de la réponse se présente comme suit:
{
"access_token":"ya29.c.ElpSB...BMgkALBJ0kou-8",
"token_type":"Bearer",
"expiresInSec": 3600
}
La règleAssignMessage suivante récupère la valeur de réponse de la règle ExtensionCallout ci-dessus et la copie dans la charge utile de la réponse. Cela peut être utile pour le débogage. En pratique, vous ne souhaitez peut-être pas renvoyer le jeton au client.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AssignMessage async="false" continueOnError="false" enabled="true" name="Retrieve-Auth-Token">
<DisplayName>Retrieve Auth Token</DisplayName>
<AssignTo type="response" createNew="false"/>
<Set>
<Payload contentType="application/json">{google.credentials.access_token}</Payload>
</Set>
</AssignMessage>
Mettre en cache un jeton d'accès
Pour éviter d'effectuer des appels inutiles pour récupérer un jeton, envisagez de le mettre en cache. Pour les appels ultérieurs nécessitant un jeton, la récupération du jeton à partir du cache Apigee Edge est plus rapide que l'obtention d'un nouveau jeton. Lorsque le jeton mis en cache expire, récupérez un nouveau jeton et actualisez le cache avec celui-ci.
Le code suivant à partir d'un exemple de proxy d'API montre comment définir et utiliser un jeton mis en cache pour appeler l'API Google Translation avec une règle ServiceCallout. Chaque exemple de code correspond à une règle différente dans le flux.
Les règles suivantes sont exécutées dans l'ordre décrit par le flux XML suivant:
<Request>
<!-- Attempt to get a token from the cache. -->
<Step>
<Name>Get-Cached-Auth-Token</Name>
</Step>
<!-- Only execute the following ExtensionCallout policy if the call to the
cache couldn't retrieve a cached token. -->
<Step>
<Name>Google-Auth-Callout</Name>
<Condition>lookupcache.Get-Cached-Auth-Token.cachehit is false</Condition>
</Step>
<!-- Only execute the following PopulateCache policy if the call to the
cache couldn't retrieve a cached token. -->
<Step>
<Name>Cache-Auth-Token</Name>
<Condition>lookupcache.Get-Cached-Auth-Token.cachehit is false</Condition>
</Step>
<!-- Use the ServiceCallout policy to call the translate API. -->
<Step>
<Name>Translate-Text</Name>
</Step>
</Request>
La règle LookupCache suivante tente d'obtenir un jeton du cache. Si le jeton a déjà été obtenu et mis en cache, cette règle l'utilisera pour le proxy d'API.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <LookupCache async="false" continueOnError="false" enabled="true" name="Get-Cached-Auth-Token"> <DisplayName>Get Cached Auth Token</DisplayName> <!-- Give cache key and scope to specify the entry for the cached token. --> <CacheKey> <Prefix/> <KeyFragment>gcp_translate_token_</KeyFragment> </CacheKey> <Scope>Exclusive</Scope> <!-- Assign the retrieved token (if any) to a variable, where it can be retrieved by policies. --> <AssignTo>cloud.translation.auth.token</AssignTo> </LookupCache>
Si la recherche dans le cache ne récupère pas de jeton mis en cache, la règle ExtensionCallout suivante récupère un nouveau jeton OAuth, en spécifiant l'API Google Cloud Translation comme champ d'application du jeton. Google Cloud renvoie un jeton valide si les identifiants du compte de service utilisés lors de la configuration de l'extension
Google-Auth-Callout
représentent un membre du projet ayant accès à l'API.<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ConnectorCallout async="false" continueOnError="true" enabled="true" name="Google-Auth-Callout"> <DisplayName>Google-Auth-Callout</DisplayName> <Connector>example-auth-extension</Connector> <Action>getOauth2AccessToken</Action> <Input><![CDATA[{ "scope" : ["https://www.googleapis.com/auth/cloud-translation"] }]]></Input> <Output parsed="false">cloud.translation.auth.token</Output> </ConnectorCallout>
Une fois que la stratégie ExtensionCallout a récupéré un nouveau jeton, la règle PopulateCache le met en cache pour une utilisation ultérieure par les stratégies du proxy d'API.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <PopulateCache async="false" continueOnError="false" enabled="true" name="Cache-Auth-Token"> <DisplayName>Cache Auth Token</DisplayName> <Properties/> <!-- Set cache key information to specify a unique key for this entry. --> <CacheKey> <Prefix/> <KeyFragment>gcp_translate_token_</KeyFragment> </CacheKey> <Scope>Exclusive</Scope> <ExpirySettings> <TimeoutInSec>5</TimeoutInSec> </ExpirySettings> <!-- Get the token to cache from the variable where the ExtensionCallout put it. --> <Source>cloud.translation.auth.token</Source> </PopulateCache>
Actions
getOauth2AccessToken
Récupère un jeton d'accès OAuth 2.0. Utilisez cette action pour permettre l'authentification OAuth à deux acteurs entre votre proxy d'API et les API Google lorsque les API Google nécessitent un jeton OAuth.
Dans le protocole OAuth à deux acteurs, cette action d'extension récupère un jeton OAuth en s'authentifiant auprès de Google à l'aide d'un compte de service JSON (vous ajoutez ce fichier JSON lorsque vous configurez l'extension). Une fois que cette action a récupéré le jeton OAuth, votre proxy d'API peut l'utiliser pour appeler les API Google, appelant ainsi les API pour le compte du compte de service Google.
L'accès aux API Google Cloud est filtré selon les champs d'application listés dans Champs d'application OAuth 2.0 pour les API Google.
Pour en savoir plus sur les interactions de serveur à serveur avec OAuth 2.0, consultez Utiliser OAuth 2.0 pour l'authentification serveur à serveur.
Syntaxe
<Action>getOauth2AccessToken</Action>
<Input><![CDATA[{
"scope" : [
"scope1",
"scope2"
]
}]]></Input>
Exemple
Dans l'exemple suivant, l'action getOauth2AccessToken
de l'extension récupère un jeton à utiliser dans les requêtes adressées à l'API Cloud Translation.
<Action>getOauth2AccessToken</Action>
<Input><![CDATA[{
"scope" : [
"https://www.googleapis.com/auth/cloud-translation"
]
}]]></Input>
Paramètres de requête
Paramètres | Description | Type | Par défaut | Obligatoire |
---|---|---|---|---|
champ d'application | Tableau des champs d'application OAuth 2.0. Pour en savoir plus sur les champs d'application, consultez la page Champs d'application OAuth 2.0 pour les API Google. | Array | ["https://www.googleapis.com/auth/cloud-platform"] , qui accorde l'accès à toutes les API auxquelles le compte de service a accès. |
Non. |
Réponse
Objet contenant le jeton d'accès, son type et sa date d'expiration sous la forme suivante:
{
"accessToken": "ewogICJ0eXB...C5jb20iCn0K",
"token_type": "Bearer",
"expiresInSec": 3600
}
Propriétés de la réponse
Paramètres | Description | Par défaut | Obligatoire |
---|---|---|---|
accessToken | Jeton d'accès OAuth 2.0. | Aucun | Oui |
tokenType | Type de jeton | Support | Oui |
expiresInSec | Nombre de secondes avant l'expiration du jeton. | 3 600 | Oui |
getJWTAccessToken
Récupère un jeton d'accès à jeton Web JSON (JWT). Vous pouvez utiliser ce jeton pour vous authentifier auprès des API Google si l'API que vous souhaitez appeler dispose d'une définition de service publiée dans le dépôt GitHub des API Google.
Avec certaines API Google, vous pouvez effectuer des appels d'API autorisés à l'aide d'un jeton JWT signé directement en tant que jeton de support, plutôt qu'à l'aide d'un jeton d'accès OAuth 2.0. Lorsque cela est possible, vous évitez d'avoir à envoyer une requête réseau au serveur d'autorisation de Google avant d'effectuer un appel d'API.
Pour en savoir plus sur l'authentification avec un jeton d'accès JWT, consultez la page Utiliser OAuth 2.0 pour l'authentification serveur à serveur.
Syntaxe
<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
"audience" : "audience"
}]]></Input>
Exemple: URL de la fonction Cloud
Dans l'exemple suivant, l'action getOauth2AccessToken
de l'extension récupère un jeton à utiliser dans les requêtes adressées à l'API Cloud Translation.
<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
"audience" : "https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/FUNCTION_NAME"
}]]></Input>
Exemple: ID client sécurisé par Cloud IAP
Dans l'exemple suivant, l'action getOauth2AccessToken
de l'extension récupère un jeton à utiliser dans les requêtes adressées à l'API Cloud Translation.
<Action>getJWTAccessToken</Action>
<Input><![CDATA[{
"audience" : "Cloud-IAP-secured-client-ID"
}]]></Input>
Paramètres de requête
Paramètres | Description | Par défaut | Obligatoire |
---|---|---|---|
audience | Destinataire souhaité du jeton. Il peut s'agir d'un ID client sécurisé par Cloud IAP, d'une URL Cloud Functions, etc. | Aucun | Oui |
Réponse
{
"accessToken": "token",
"tokenType": "Bearer",
"expiresInSec": 3600
}
Propriétés de la réponse
Paramètres | Description | Par défaut | Obligatoire |
---|---|---|---|
accessToken | Jeton d'accès. | Aucun | Oui |
tokenType | Type de jeton | Support | Oui |
expiresInSec | Expire en quelques secondes. | 3 600 | Oui |
Documentation de référence sur la configuration
Utilisez le code suivant lorsque vous configurez et déployez cette extension pour l'utiliser dans des proxys d'API. Pour savoir comment configurer une extension à l'aide de la console Apigee, consultez Ajouter et configurer une extension.
Propriétés d'extension courantes
Les propriétés suivantes sont présentes pour chaque extension.
Propriété | Description | Par défaut | Obligatoire |
---|---|---|---|
name |
Nom que vous attribuez à cette configuration de l'extension. | Aucune | Oui |
packageName |
Nom du package d'extension tel qu'indiqué par Apigee Edge. | Aucune | Oui |
version |
Numéro de version du package d'extension à partir duquel vous configurez une extension. | Aucune | Oui |
configuration |
Valeur de configuration spécifique à l'extension que vous ajoutez. Consultez Propriétés de ce package d'extension. | Aucune | Oui |
Propriétés de ce package d'extension
Spécifiez les valeurs des propriétés de configuration suivantes spécifiques à cette extension.
Propriété | Description | Par défaut | Obligatoire |
---|---|---|---|
identifiants | Lorsqu'il est saisi dans la console Apigee Edge, il s'agit de l'intégralité du contenu du fichier JSON de clé de compte de service. Lorsqu'elle est envoyée via l'API de gestion, il s'agit d'une valeur encodée en base64 générée à partir de l'intégralité du fichier JSON de clé de compte de service. | Aucun | Oui |