Controllo di ammissione

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Introduzione

Questa pagina descrive come utilizzare l'API Service Control v2 per il controllo di ammissione per i servizi gestiti integrati con Service Infrastructure. È destinato ai produttori di servizi che vogliono integrare profondamente i loro servizi con Google Cloud.

Service Infrastructure è una piattaforma fondamentale per cui gli sviluppatori possono produrre, gestire, proteggere e utilizzare API e servizi. Utilizza un semplice modello di utilizzo dei servizi generico: un consumatore consuma un servizio gestito da un producer. Tutte le API di Google e le API di Google Cloud utilizzano questo modello, poiché sono anch'esse basate su Infrastruttura di servizi.

Quando un client accede a un servizio, tutte le entità coinvolte nell'accesso in genere richiedono una verifica dello stato e del criterio, inclusi consumer, servizio, produttore, utente, applicazione, rete e risorse. Con Service Infrastructure, questo processo è chiamato controllo di ammissione, che include autenticazione, autorizzazione, controllo, limitazione della frequenza e altro ancora.

API Service Control v2

L'API Service Control v2 fornisce un semplice metodo services.check che fornisce il controllo di ammissione per tutti i servizi integrati con Service Infrastructure. Questo metodo ti permette di:

  • Controllo dello stato
    • Stato dell'abuso
    • Stato fatturazione
    • Stato del consumatore
    • Stato del servizio
    • Attivazione dei servizi
  • Autenticazione
    • Token di accesso OAuth di Google
    • JWT firmato dall'account di servizio Google
  • Autorizzazione
  • Controllo
    • Audit log di Cloud. Il log di controllo è associato a service "externalaudit.googleapis.com".

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

Per fare in modo che un servizio chiami l'API Service Control, devi abilitare l'API Service Control nel progetto producer e disporre delle autorizzazioni appropriate sul servizio. Per saperne di più, consulta la guida introduttiva per le API Cloud e il controllo dell'accesso per il controllo dei servizi.

Attributi della richiesta

Quando un client accede a un servizio, questo deve astrarre l'accesso in una o più richieste API che possono essere verificate con il controllo di ammissione. Nella maggior parte dei casi, questi accessi sono in realtà richieste API reali. In altri casi, l'accesso può essere complicato per l'importazione di dati o query SQL e il servizio deve modellarlo in termini di set di richieste API virtuali ed eseguire il controllo di ammissione per ogni richiesta.

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

Attributo Descrizione Esempio
origin.ip L'indirizzo IP del chiamante. "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 API. "v1"
api.protocol Il nome del protocollo 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 URL. "https"
request.host L'intestazione host HTTP. "endpointsapis.appspot.com"
request.path 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 di destinazione. "projects/123/topics/news-feed"

Attributi della risorsa

Quando un client accede a un servizio, può essere previsto l'accesso a una o più risorse interne al servizio, come la lettura di un oggetto o la creazione di un'istanza VM. Il servizio può utilizzare il controllo di ammissione dell'infrastruttura di servizi per il controllo dell'accesso alle risorse, supportato da IAM e dagli audit log di Cloud. Se il tuo servizio non ha bisogno del controllo dell'accesso, puoi saltare questa sezione.

Per il 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 necessari per il controllo dell'accesso.

Attributo Descrizione Esempio
name Il 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 per la risorsa. Il formato è "{service}/{kinds}.{verb}". "endpointsapis.appspot.com/instances.get"

Per le prestazioni e l'efficienza, il metodo services.check consente di verificare più autorizzazioni per una singola risorsa in una sola chiamata.

Esecuzione del controllo di ammissione

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

Per sperimentare rapidamente il controllo di ammissione, puoi utilizzare il comando gcurl per chiamare il metodo services.check. Consulta la guida introduttiva all'utilizzo dell'API Service Control per i passaggi di configurazione iniziali.

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 è stato superato. In caso di esito positivo, la risposta deve essere vuota. Se non riesce, l'elemento status nella risposta contiene informazioni di errore che il servizio dovrebbe restituire al client. Spesso il servizio deve tradurre le informazioni sugli errori 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. Tali librerie offrono una grande usabilità e gestiscono automaticamente le funzionalità comuni, come l'autenticazione. Per ulteriori informazioni, consulta la sezione Spiegazione delle librerie client.