Cette page explique comment utiliser les bibliothèques clientes pour accéder aux API Google.
Les bibliothèques clientes facilitent l'accès aux Google Cloud API à l'aide d'un langage compatible. Vous pouvez utiliser directement les API Google Cloud en envoyant des requêtes brutes au serveur, mais les bibliothèques clientes fournissent des simplifications qui réduisent considérablement la quantité de code à écrire. Cela est particulièrement vrai pour l'authentification, car les bibliothèques clientes sont compatibles avec le service Identifiants par défaut de l'application (ADC, Application Default Credentials).
Si vous acceptez les configurations d'identifiants (JSON, fichiers ou flux) provenant d'une source externe (par exemple, un client), consultez les exigences de sécurité concernant l'utilisation de configurations d'identifiants provenant d'une source externe.
Utiliser les identifiants par défaut de l'application avec les bibliothèques clientes
Pour authentifier votre application à l'aide du service d'identifiants par défaut de l'application (ADC), vous devez d'abord configurer ADC pour l'environnement dans lequel votre application s'exécute. Lorsque vous utilisez la bibliothèque cliente pour créer un client, celle-ci recherche et utilise automatiquement les identifiants que vous avez fournis au service ADC pour s'authentifier auprès des API utilisées par votre code. Votre application n'a pas besoin de s'authentifier explicitement ou de gérer les jetons. Ces points sont gérés automatiquement par les bibliothèques d'authentification.
Pour un environnement de développement local, vous pouvez configurer le service ADC avec vos identifiants utilisateur ou avec l'emprunt d'identité d'un compte de service en utilisant gcloud CLI. Pour les environnements de production, vous devez configurer le service ADC en associant un compte de service.
Exemple de création de client
Les exemples de code suivants créent un client pour le service Cloud Storage. Votre code va probablement nécessiter différents clients. Ces exemples visent simplement à montrer comment vous pouvez créer un client et l'utiliser sans code pour vous authentifier explicitement.
Avant de pouvoir exécuter les exemples suivants, vous devez effectuer les étapes ci-après :
Go
Java
Node.js
PHP
Python
Ruby
Utiliser des clés API avec des bibliothèques clientes
Vous ne pouvez utiliser une clé API qu'avec des bibliothèques clientes pour les API qui acceptent les clés API. De plus, la clé API ne doit pas comporter de restriction d'API qui l'empêche d'être utilisée pour l'API.
Pour en savoir plus sur les clés API créées en mode Express, consultez les questions fréquentes sur le mode Express de Google Cloud.
Cet exemple utilise l'API Cloud Natural Language, qui accepte les clés API, afin de vous montrer comment fournir une clé API à la bibliothèque.
C#
Pour exécuter cet exemple, vous devez installer la bibliothèque cliente Natural Language.
C++
Pour exécuter cet exemple, vous devez installer la bibliothèque cliente Natural Language.
Go
Pour exécuter cet exemple, vous devez installer la bibliothèque cliente Natural Language.
Node.js
Pour exécuter cet exemple, vous devez installer la bibliothèque cliente Natural Language.
Python
Pour exécuter cet exemple, vous devez installer la bibliothèque cliente Natural Language.
Lorsque vous utilisez des clés API dans vos applications, assurez-vous qu'elles sont protégées lors du stockage et de la transmission. L'exposition publique de vos clés API peut entraîner des frais inattendus. Pour en savoir plus, consultez la section Bonnes pratiques pour gérer les clés API.
Exigences de sécurité lorsque vous utilisez des configurations d'identifiants provenant d'une source externe
En règle générale, vous générez des configurations d'identifiants à l'aide des commandes gcloud CLI ou de la console Google Cloud . Par exemple, vous pouvez utiliser gcloud CLI pour générer un fichier ADC local ou un fichier de configuration de connexion. De même, vous pouvez utiliser la console Google Cloud pour créer et télécharger une clé de compte de service.
Toutefois, pour certains cas d'utilisation, des configurations d'identifiants vous sont fournies par une entité externe. Elles sont destinées à l'authentification auprès des API Google.
Certains types de configurations d'identifiants incluent des points de terminaison et des chemins d'accès aux fichiers, que les bibliothèques d'authentification utilisent pour obtenir un jeton. Lorsque vous acceptez des configurations d'identifiants provenant d'une source externe, vous devez les valider avant de les utiliser. Si vous ne validez pas la configuration, un pirate informatique peut utiliser les identifiants pour compromettre vos systèmes et vos données.
Valider les configurations d'identifiants à partir de sources externes
La façon dont vous devez valider vos identifiants externes dépend des types d'identifiants acceptés par votre application.
Valider les clés de compte de service
Si votre application n'accepte que les clés de compte de service, utilisez un chargeur d'identifiants spécifique aux clés de compte de service, comme illustré dans les exemples suivants. Le chargeur d'identifiants spécifiques au type n'analyse que les champs présents pour les clés de compte de service, qui n'exposent aucune faille.
C#
var saCredential = ServiceAccountCredential.FromServiceAccountData(stream);
C++
auto cred = google::cloud::MakeServiceAccountCredentials(json)
Java
ServiceAccountCredentials credentials =
ServiceAccountCredentials.fromStream(credentialsStream);
Node.js
const keys = JSON.parse(json_input)
const authClient = JWT.fromJSON(keys);
PHP
cred = new Google\Auth\Credentials\ServiceAccountCredentials($scope, $jsonKey);
Python
cred = service_account.Credentials.from_service_account_info(json_data)
Ruby
creds = Google::Auth::ServiceAccountCredentials.make_creds(json_key_io: json_stream)
Si vous ne pouvez pas utiliser de chargeur d'identifiants spécifique à un type, validez l'identifiant en vérifiant que la valeur du champ type
est service_account
. Si la valeur du champ type
est différente, n'utilisez pas la clé du compte de service.
Valider les autres configurations d'identifiants
Si votre application accepte tout type d'identifiant autre qu'une clé de compte de service, vous devez effectuer une vérification supplémentaire. Parmi les autres types de configurations d'identifiants, on trouve les fichiers d'identifiants ADC, les fichiers d'identifiants de la fédération d'identité de charge de travail ou les fichiers de configuration de connexion de la fédération des identités des employés.
Le tableau suivant liste les champs que vous devez valider, s'ils sont présents dans vos identifiants. Tous ces champs ne sont pas présents pour toutes les configurations d'identifiants.
Champ | Objectif | Valeur attendue |
---|---|---|
service_account_impersonation_url |
Les bibliothèques d'authentification utilisent ce champ pour accéder à un point de terminaison afin de générer un jeton d'accès pour le compte de service dont l'identité est empruntée. | https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/service account email:generateAccessToken |
token_url |
Les bibliothèques d'authentification envoient un jeton externe à ce point de terminaison pour l'échanger contre un jeton d'accès fédéré. | https://sts.googleapis.com/v1/token |
credential_source.file |
Les bibliothèques d'authentification lisent un jeton externe à partir du fichier à l'emplacement spécifié par ce champ et l'envoient au point de terminaison token_url .
|
Chemin d'accès à un fichier contenant un jeton externe. Vous devriez reconnaître ce chemin d'accès. |
credential_source.url |
Point de terminaison qui renvoie un jeton externe. Les bibliothèques d'authentification envoient une requête à cette URL et envoient la réponse au point de terminaison token_url .
|
L'un des éléments suivants :
|
credential_source.executable.command |
Si la variable d'environnement GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES est définie sur 1 , les bibliothèques d'authentification exécutent cette commande ou ce fichier exécutable.
|
Fichier ou commande exécutable qui renvoie un jeton externe. Vous devez reconnaître cette commande et vérifier qu'elle est sûre. |
credential_source.aws.url |
Les bibliothèques d'authentification envoient une requête à cette URL pour récupérer un jeton de sécurité AWS. |
L'une des valeurs exactes suivantes :
|
credential_source.aws.region_url |
Les bibliothèques d'authentification envoient une requête à cette URL pour récupérer la région AWS active. |
L'une des valeurs exactes suivantes :
|
credential_source.aws.imdsv2_session_token_url |
Les bibliothèques d'authentification envoient une requête à cette URL pour récupérer le jeton de session AWS. |
L'une des valeurs exactes suivantes :
|
Étapes suivantes
- Apprenez-en plus sur les identifiants par défaut de l'application.
- Apprenez-en davantage sur les clés API.
- Consultez la présentation des méthodes d'authentification.