Questa pagina è stata tradotta dall'API Cloud Translation.

Controllo di ammissione

Introduzione

Questa pagina descrive come utilizzare la versione 2 dell'API Service Control per il controllo di ammissione per i servizi gestiti integrati con Service Infrastructure. È destinato ai produttori di servizi che vogliono integrare profondamente i propri servizi con Google Cloud.

Service Infrastructure è una piattaforma di base che consente agli sviluppatori di produrre, gestire, difendere e utilizzare API e servizi. Utilizza un modello di utilizzo del servizio semplice e generico: un consumer utilizza un servizio gestito da un producer. Tutte le API Google e le API Google Cloud utilizzano questo modello, poiché sono anche basate sull'Service Infrastructure.

Quando un client accede a un servizio, tutte le entità coinvolte nell'accesso tipicamente richiedono un controllo dello stato e delle norme, inclusi consumer, servizio, producer, utente, applicazione, rete e risorse. Con Service Infrastructure, questo processo è chiamato controllo di ammissione, che include autenticazione, autorizzazione, controllo, limitazione di frequenza e altro ancora.

API Service Control v2

La versione 2 dell'API Service Control fornisce un semplice metodo services.check che offre il controllo dell'accesso a tutti i servizi integrati con Service Infrastructure. Questo metodo consente di eseguire le seguenti operazioni in una singola chiamata al metodo:

Controllo dello stato
- Stato di comportamento illecito
- Stato fatturazione
- Stato del consumatore
- Stato del servizio
- Abilitazione del servizio
Autenticazione
- Token di accesso OAuth di Google
- JWT firmato dell'account di servizio Google
Autorizzazione
- Identity and Access Management (IAM)
Controllo
- Audit log di Cloud. L'audit log è associato al servizio "externalaudit.googleapis.com".

Quando un servizio chiama l'API Service Control, il producer è anche un consumatore dell'API Service Control. Pertanto, il metodo services.check esegue anche il controllo di ammissione sulla chiamata all'API Service Control.

Affinché un servizio chiami l'API Service Control, devi attivare l'API Service Control nel progetto del produttore e disporre delle autorizzazioni appropriate per il servizio. Per ulteriori informazioni, consulta la guida introduttiva alle API Cloud e il Controllo degli accessi di Service Control.

Attributi della richiesta

Quando un client accede a un servizio, il servizio deve astrarre l'accesso in una o più richieste API che possono essere controllate con il controllo dell'accesso. Nella maggior parte dei casi, questi accessi sono effettivamente richieste API reali. In altri casi, l'accesso può essere costituito da job di importazione di dati o query SQL complessi e il servizio deve modellare l'accesso in termini di un insieme di richieste API virtuali ed eseguire il controllo dell'accesso su ogni richiesta.

Per eseguire il controllo di ammissione utilizzando l'API Service Control, il servizio deve chiamare il metodo services.check con gli attributi della richiesta richiesti. La tabella seguente elenca gli attributi necessari per il controllo dell'accesso. Per la specifica completa, consulta AttributeContext.

Attributo	Descrizione	Esempio
`origin.ip`	L'indirizzo IP della persona che chiama.	"1.2.3.4"
`api.service`	Il nome del servizio API.	"endpointsapis.appspot.com"
`api.operation`	Il nome del metodo API.	"google.example.hello.v1.HelloService.GetHello"
`api.version`	La stringa della versione dell'API.	"v1"
`api.protocol`	Il nome del protocollo dell'API.	"https"
`request.id`	Un ID richiesta univoco.	"123e4567-e89b-12d3-a456-426655440000"
`request.time`	L'ora della richiesta.	"2019-07-31T05:20:00Z"
`request.method`	Il nome del metodo HTTP.	"POST"
`request.scheme`	Lo schema dell'URL.	"https"
`request.host`	L'intestazione host HTTP.	"endpointsapis.appspot.com"
`request.path`	Il percorso dell'URL.	"/v1/hello"
`request.headers`	Le intestazioni delle richieste HTTP. Le intestazioni richieste sono "authorization", "user-agent", "origin", "referer".
`resource.name`	Il nome della risorsa target.	"projects/123/topics/news-feed"

Attributi risorsa

Quando un client accede a un servizio, l'accesso può coinvolgere una o più risorse all'interno del servizio, ad esempio la lettura di un oggetto o la creazione di un'istanza VM. Il servizio può utilizzare il controllo dell'accesso all'Service Infrastructure per il controllo dell'accesso alle risorse, supportato da IAM e Cloud Audit Logs. Se il tuo servizio non richiede il controllo dell'accesso, puoi saltare questa sezione.

Per controllo dell'accesso, un servizio deve passare gli attributi della risorsa al metodo services.check insieme agli attributi della richiesta. La tabella seguente mostra gli attributi delle risorse richiesti per controllo dell'accesso.

Attributo	Descrizione	Esempio
`name`	Nome della risorsa.	"projects/123/locations/global/instances/instance-1"
`type`	Il tipo di risorsa. Il formato è "{service}/{Kind}".	"endpointsapis.appspot.com/Instance"
`permission`	L'autorizzazione della risorsa. Il formato è "{service}/{kinds}.{verb}".	"endpointsapis.appspot.com/instances.get"

Per prestazioni ed efficienza, il metodo services.check consente di controllare più autorizzazioni su una singola risorsa in un'unica chiamata.

Eseguire il controllo di ammissione

Dopo aver eseguito il deployment della configurazione del servizio nell'API Service Management e aver verificato che il servizio sia pronto a soddisfare le richieste dei clienti, puoi iniziare a chiamare services.check per il servizio di cui è stato eseguito il deployment. Devi chiamare services.check per eseguire il controllo di ammissione ogni volta che il tuo servizio riceve una richiesta.

Per eseguire rapidamente esperimenti sul controllo dell'accesso, puoi utilizzare il comando gcurl per chiamare il metodo services.check. Per i passaggi di configurazione iniziale, consulta Introduzione all'API Service Control.

L'esempio seguente mostra come utilizzare il comando gcurl per chiamare services.check tramite HTTP.

gcurl -d '{
  "service_config_id": "latest",
  "attributes": {
    "origin": {
      "ip": "1.2.3.4"
    },
    "api": {
      "service": "endpointsapis.appspot.com",
      "operation": "google.example.hello.v1.HelloService.GetHello",
      "version": "v1",
      "protocol": "https"
    }
  },
  "request": {
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "time": "2019-07-31T05:20:00Z",
    "scheme": "https",
    "host": "endpointsapis.appspot.com"
    "headers": {
      "authorization": "Bearer xxx",
      "user-agent": "curl/1.0"
    }
  },
  "resources": [
  ]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:check
{
}

La risposta del metodo services.check indica se il controllo di ammissione è andato a buon fine. Se supera il test, la risposta deve essere vuota. In caso di errore, status nella risposta contiene le informazioni di errore che il servizio deve restituire al cliente. Spesso il servizio deve tradurre le informazioni sull'errore nel proprio formato. Il servizio può utilizzare le informazioni anche per scopi di logging e monitoraggio.

Per i servizi di produzione, devi utilizzare una delle librerie client fornite da Google per chiamare l'API Service Control. Queste librerie offrono un'ottima usabilità e gestiscono automaticamente le funzionalità comuni, come l'autenticazione. Per ulteriori informazioni, consulta Librerie client spiegate.