Questa pagina descrive come utilizzare le librerie client per accedere alle API di Google.
Le librerie client semplificano l'accesso alle APIGoogle Cloud utilizzando un linguaggio supportato. Puoi utilizzare le API Google Cloud direttamente effettuando richieste non elaborate al server, ma le librerie client forniscono semplificazioni che riducono notevolmente la quantità di codice da scrivere. Ciò vale soprattutto per l'autenticazione, perché le librerie client supportano le credenziali predefinite dell'applicazione (ADC).
Se accetti configurazioni delle credenziali (JSON, file o stream) da un'origine esterna (ad esempio, un cliente), esamina i requisiti di sicurezza quando utilizzi configurazioni delle credenziali da un'origine esterna.
Utilizzare le credenziali predefinite dell'applicazione con le librerie client
Per utilizzare le Credenziali predefinite dell'applicazione per autenticare la tua applicazione, devi prima configurare le credenziali predefinite dell'applicazione per l'ambiente in cui è in esecuzione l'applicazione. Quando utilizzi la libreria client per creare un client, la libreria client verifica automaticamente le credenziali che hai fornito ad ADC e le utilizza per l'autenticazione alle API utilizzate dal tuo codice. La tua applicazione non deve autenticarsi o gestire i token in modo esplicito. Questi requisiti vengono gestiti automaticamente dalle librerie di autenticazione.
Per un ambiente di sviluppo locale, puoi configurare ADC con le tue credenziali utente o con la rappresentazione dell'account di servizio utilizzando gcloud CLI. Per gli ambienti di produzione, configura ADC collegando un service account.
Creazione di un client di esempio
I seguenti esempi di codice creano un client per il servizio Cloud Storage. È probabile che il tuo codice richieda client diversi. Questi esempi hanno lo scopo di mostrare come creare un client e utilizzarlo senza codice per eseguire l'autenticazione in modo esplicito.
Prima di poter eseguire gli esempi riportati di seguito, devi completare i seguenti passaggi:
Vai
Java
Node.js
PHP
Python
Ruby
Utilizzare le chiavi API con le librerie client
Puoi utilizzare le chiavi API solo con le librerie client per le API che accettano le chiavi API. Inoltre, la chiave API non deve avere una limitazione API che ne impedisca l'utilizzo per l'API.
Per saperne di più sulle chiavi API create in modalità express, consulta le domande frequenti sulla modalità express di Google Cloud.
Questo esempio utilizza l'API Cloud Natural Language, che accetta le chiavi API, per mostrare come fornire una chiave API alla libreria.
C#
Per eseguire questo esempio, devi installare la libreria client Natural Language.
C++
Per eseguire questo esempio, devi installare la libreria client Natural Language.
Vai
Per eseguire questo esempio, devi installare la libreria client Natural Language.
Node.js
Per eseguire questo esempio, devi installare la libreria client Natural Language.
Python
Per eseguire questo esempio, devi installare la libreria client Natural Language.
Quando utilizzi le chiavi API nelle tue applicazioni, assicurati che siano protette durante l'archiviazione e la trasmissione. L'esposizione pubblica delle chiavi API può comportare addebiti imprevisti sul tuo account. Per saperne di più, consulta le best practice per la gestione delle chiavi API.
Requisiti di sicurezza quando si utilizzano configurazioni delle credenziali da un'origine esterna
In genere, le configurazioni delle credenziali vengono generate utilizzando i comandi gcloud CLI o la console Google Cloud . Ad esempio, puoi utilizzare gcloud CLI per generare un file ADC locale o un file di configurazione di accesso. Allo stesso modo, puoi utilizzare la console Google Cloud per creare e scaricare una chiave dell'account di servizio.
Per alcuni casi d'uso, tuttavia, le configurazioni delle credenziali vengono fornite da un'entità esterna; queste configurazioni delle credenziali sono destinate a essere utilizzate per l'autenticazione alle API di Google.
Alcuni tipi di configurazioni delle credenziali includono endpoint e percorsi dei file, che le librerie di autenticazione utilizzano per acquisire un token. Quando accetti le configurazioni delle credenziali da un'origine esterna, devi convalidare la configurazione prima di utilizzarla. Se non convalidi la configurazione, un malintenzionato potrebbe utilizzare le credenziali per compromettere i tuoi sistemi e dati.
Convalidare le configurazioni delle credenziali da origini esterne
La modalità di convalida delle credenziali esterne dipende dai tipi di credenziali accettati dalla tua applicazione.
Convalida le chiavi del account di servizio
Se la tua applicazione accetta solo le chiavi del account di servizio, utilizza un caricatore di credenziali specifico per le chiavi del account di servizio, come mostrato negli esempi seguenti. Il caricatore di credenziali specifico per il tipo analizza solo i campi presenti per le chiavi del service account, che non espongono vulnerabilità.
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)
Se non puoi utilizzare un caricatore di credenziali specifico per il tipo, convalida la credenziale
verificando che il valore del campo type
sia service_account
. Se il valore del campo type
è un altro valore, non utilizzare la chiave dell'account di servizio.
Convalidare altre configurazioni delle credenziali
Se la tua applicazione accetta qualsiasi tipo di credenziale oltre a una chiave del account di servizio, devi eseguire una verifica aggiuntiva. Esempi di altri tipi di configurazioni delle credenziali includono file delle credenziali ADC, file delle credenziali della federazione delle identità per i carichi di lavoro o file di configurazione dell'accesso della federazione delle identità della forza lavoro.
La tabella seguente elenca i campi che devi convalidare, se presenti nelle tue credenziali. Non tutti questi campi sono presenti in tutte le configurazioni delle credenziali.
Campo | Finalità | Valore previsto |
---|---|---|
service_account_impersonation_url |
Le librerie di autenticazione utilizzano questo campo per accedere a un endpoint per generare un token di accesso per il account di servizio di cui viene eseguita l'impersonificazione. | https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/service account email:generateAccessToken |
token_url |
Le librerie di autenticazione inviano un token esterno a questo endpoint per scambiarlo con un token di accesso federato. | https://sts.googleapis.com/v1/token |
credential_source.file |
Le librerie di autenticazione leggono un token esterno dal file nella posizione specificata da questo campo e lo inviano all'endpoint token_url .
|
Il percorso di un file contenente un token esterno. Dovresti riconoscere questo percorso. |
credential_source.url |
Un endpoint che restituisce un token esterno. Le librerie di autenticazione
inviano una richiesta a questo URL e inviano la risposta all'endpoint
token_url .
|
Uno dei seguenti elementi:
|
credential_source.executable.command |
Se la variabile di ambiente GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES è impostata su 1 , le librerie di autenticazione eseguono questo comando o file eseguibile.
|
Un file eseguibile o un comando che restituisce un token esterno. Dovresti riconoscere questo comando e verificare che sia sicuro. |
credential_source.aws.url |
Le librerie di autenticazione inviano una richiesta a questo URL per recuperare un token di sicurezza AWS. |
Uno di questi valori esatti:
|
credential_source.aws.region_url |
Le librerie di autenticazione inviano una richiesta a questo URL per recuperare la regione AWS attiva. |
Uno di questi valori esatti:
|
credential_source.aws.imdsv2_session_token_url |
Le librerie di autenticazione inviano una richiesta a questo URL per recuperare il token di sessione AWS. |
Uno di questi valori esatti:
|
Passaggi successivi
- Scopri di più sulle credenziali predefinite dell'applicazione.
- Scopri di più sulle chiavi API.
- Consulta una panoramica dei metodi di autenticazione.