Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Autenticazione tra servizi

Oltre ad autenticare le richieste degli utenti finali, potresti voler autenticare i servizi (utenti non umani) che effettuano richieste alla tua API. In questa pagina viene spiegato come utilizzare i service account per fornire l'autenticazione a persone o servizi.

Panoramica

Per identificare un servizio che invia richieste alla tua API, utilizza un service account. Il servizio chiamante utilizza la chiave privata del account di servizio per firmare un token web JSON (JWT) sicuro e invia il JWT firmato nella richiesta alla tua API.

Per implementare l'autenticazione del account di servizio nella tua API e nel servizio chiamante:

Crea un account di servizio e una chiave da utilizzare per il servizio chiamante.
Aggiungi il supporto per l'autenticazione nella configurazione API per il servizio API Gateway.
Aggiungi codice al servizio chiamante che:
- Crea un JWT e lo firma con la chiave privata del account di servizio.
- Invia il JWT firmato in una richiesta all'API.

API Gateway convalida che le attestazioni nel JWT corrispondano alla configurazione nella configurazione API prima di inoltrare la richiesta alla tua API. API Gateway non verifica le autorizzazioni Cloud Identity che hai concesso al account di servizio.

Prerequisiti

In questa pagina si presuppone che tu abbia già:

Creare un account di servizio con una chiave

Ti serve un account di servizio con un file di chiave privata che il servizio chiamante utilizza per firmare il JWT. Se più servizi inviano richieste alla tua API, puoi creare un account di servizio per rappresentare tutti i servizi chiamanti. Se devi distinguere tra i servizi, ad esempio perché potrebbero avere autorizzazioni diverse, puoi creare un account di servizio e una chiave per ogni servizio chiamante.

Questa sezione mostra come utilizzare la Google Cloud console e lo gcloud strumento a riga di comando per creare il service account e il file della chiave privata e per assegnare al service account il ruolo Creatore token account di servizio. Per informazioni sull'utilizzo di un'API per eseguire questa attività, vedi Creare e gestire i service account.

Nota: le chiavi dei service account comportano un rischio per la sicurezza se non vengono gestite correttamente. Dovresti scegliere un'alternativa più sicura alle chiavi del service account quando è possibile. Se devi eseguire l'autenticazione con una chiave dell'account di servizio, sei responsabile della sicurezza della chiave privata e di altre operazioni descritte in Best practice per la gestione delle chiavi dei service account. Se non riesci a creare una chiave del service account, la creazione di chiavi del service account potrebbe essere disabilitata per la tua organizzazione. Per ulteriori informazioni, vedi Gestione delle risorse dell'organizzazione sicure per impostazione predefinita.

Se hai acquisito la chiave del service account da una fonte esterna, devi convalidarla prima dell'utilizzo. Per maggiori informazioni, consulta Requisiti di sicurezza per le credenziali di origine esterna.

Per creare un account di servizio con una chiave:

Google Cloud Console

Crea un account di servizio:

Nella Google Cloud console vai a Crea service account.

Vai a Crea account di servizio
Seleziona un progetto.
Nel campo Nome service account, inserisci un nome. La Google Cloud console compila il campo ID service account in base a questo nome.
(Facoltativo) Nel campo Descrizione service account, inserisci una descrizione.
Fai clic su Crea.
Fai clic sul campo Seleziona un ruolo.

In Tutti i ruoli, seleziona Service account > Creatore token account di servizio.
Fai clic su Continua.
Fai clic su Fine per completare la creazione del account di servizio.

Non chiudere la finestra del browser. Lo utilizzerai nella procedura successiva.

Crea una chiave dell'account di servizio:

Nella Google Cloud console, fai clic sull'indirizzo email del service account che hai creato.
Fai clic su Chiavi.
Fai clic su Aggiungi chiave, poi su Crea nuova chiave.
Fai clic su Crea. Un file della chiave JSON viene scaricato sul computer.
Fai clic su Chiudi.

gcloud

Puoi eseguire i seguenti comandi utilizzando Google Cloud CLI sulla tua macchina locale o in Cloud Shell.

Imposta l'account predefinito per gcloud. Se hai più di un account, assicurati di scegliere l'account che si trova nel Google Cloud progetto che vuoi utilizzare.
```
gcloud auth login
```
Visualizza gli ID progetto dei tuoi Google Cloud progetti.
```
gcloud projects list
```
Imposta il progetto predefinito. Sostituisci PROJECT_ID con l' Google Cloud ID progetto che vuoi utilizzare.
```
gcloud config set project PROJECT_ID
```
Crea un account di servizio. Sostituisci SA_NAME e SA_DISPLAY_NAME con il nome e il nome visualizzato che vuoi utilizzare.
```
gcloud iam service-accounts create SA_NAME \
  --display-name "SA_DISPLAY_NAME"
```
Visualizza l'indirizzo email del account di servizio che hai appena creato.
```
gcloud iam service-accounts list
```

Aggiungi il ruolo Creatore token account di servizio. Sostituisci SA_EMAIL_ADDRESS con l'indirizzo email del account di servizio.

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member serviceAccount:SA_EMAIL_ADDRESS \
  --role roles/iam.serviceAccountTokenCreator

Crea un file della chiave del account di servizio nella directory di lavoro corrente. Sostituisci FILE_NAME con il nome che vuoi utilizzare per il file della chiave. Per impostazione predefinita, il comando gcloud crea un file JSON.
```
gcloud iam service-accounts keys create FILE_NAME.json \
  --iam-account SA_EMAIL_ADDRESS
```

Per ulteriori informazioni sui comandi precedenti, consulta la documentazione di riferimento gcloud.

Per informazioni sulla protezione della chiave privata, vedi Best practice per la gestione delle credenziali.

Configurare l'API per supportare l'autenticazione

Quando crei una configurazione API per il gateway, specifichi un account di servizio che il gateway utilizza per interagire con altri servizi. Per abilitare l'autenticazione del account di servizio per i servizi che chiamano il gateway, modifica gli oggetti di sicurezza nella configurazione API. Le modifiche variano in base alla versione della specifica OpenAPI utilizzata.

Per configurare API Gateway in modo che convalidi le attestazioni nel JWT firmato utilizzato dai servizi chiamanti:

OpenAPI 2.0

Aggiungi il account di servizio come emittente nella configurazione API:

securityDefinitions:
    DEFINITION_NAME:
      authorizationUrl: ""
      flow: "implicit"
      type: "oauth2"
      x-google-issuer: "SA_EMAIL_ADDRESS"
      x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/SA_EMAIL_ADDRESS"

Sostituisci DEFINITION_NAME con una stringa che identifica questa definizione di sicurezza. Potresti sostituirla con il nome del account di servizio o con un nome che identifica il servizio chiamante.
Sostituisci SA_EMAIL_ADDRESS con l'indirizzo email del service account's.

Puoi definire più definizioni di sicurezza nella configurazione API, ma ogni definizione deve avere un x-google-issuer diverso. Se hai creato service account separati per ogni servizio chiamante, puoi creare una definizione di sicurezza per ogni account di servizio, ad esempio:

securityDefinitions:
    service-1:
      authorizationUrl: ""
      flow: "implicit"
      type: "oauth2"
      x-google-issuer: "service-1@example-project-12345.iam.gserviceaccount.com"
      x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/service-1@example-project-12345.iam.gserviceaccount.com"
    service-2:
      authorizationUrl: ""
      flow: "implicit"
      type: "oauth2"
      x-google-issuer: "service-2@example-project-12345.iam.gserviceaccount.com"
      x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/service-2@example-project-12345.iam.gserviceaccount.com"

(Facoltativo) Aggiungi x-google-audiences alla sezione securityDefinitions. Se non aggiungi x-google-audiences, API Gateway richiede che l'attestazione "aud" (pubblico) nel JWT sia nel formato https://SERVICE_NAME, dove SERVICE_NAME è il nome del servizio API Gateway che hai configurato nel campo host del documento OpenAPI.
Aggiungi una sezione security a livello principale del file (senza rientro o nidificazione) da applicare all'intera API o a livello di metodo da applicare a un metodo specifico. Se utilizzi le sezioni security sia a livello di API sia a livello di metodo, le impostazioni a livello di metodo sostituiscono quelle a livello di API.
```
security:
  - DEFINITION_NAME: []
```
- Sostituisci DEFINITION_NAME con il nome che hai utilizzato nella securityDefinitions sezione.
- Se hai più di una definizione nella sezione securityDefinitions, aggiungile nella sezione security, ad esempio:
```
security:
  - service-1: []
  - service-2: []
```
Esegui il deployment della configurazione API aggiornata. Prima che API Gateway inoltri una richiesta alla tua API, API Gateway verifica:
- La firma del JWT utilizzando la chiave pubblica, che si trova nell'URI specificato nel x-google-jwks_uricampo nella configurazione API.
- Che l'attestazione "iss"(emittente) nel JWT corrisponda al valore specificato nel x-google-issuercampo.
- Che l'attestazione "aud"(pubblico) nel JWT contenga il nome del servizio API Gateway o corrisponda a uno dei valori specificati nel campo x-google-audiences
- Che il token non sia scaduto utilizzando l'attestazione "exp"(ora di scadenza).

OpenAPI 3.x

Aggiungi il account di servizio come emittente nella configurazione API:

components:
  securitySchemes:
    SCHEME_NAME:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: SA_EMAIL_ADDRESS
        jwksUri: https://www.googleapis.com/robot/v1/metadata/x509/SA_EMAIL_ADDRESS
security:
  - SCHEME_NAME: []

Sostituisci SCHEME_NAME con una stringa che identifica questo schema di sicurezza. Potresti sostituirla con il nome del account di servizio o con un nome che identifica il servizio chiamante.
Sostituisci SA_EMAIL_ADDRESS con l'indirizzo email del service account's.

Puoi definire più schemi di sicurezza nella configurazione API, ma ogni definizione deve avere un issuer diverso. Se hai creato service account separati per ogni servizio chiamante, puoi creare una definizione di sicurezza per ogni account di servizio, ad esempio:

components:
  securitySchemes:
    service-1:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: "service-1@example-project-12345.iam.gserviceaccount.com"
        jwksUri: https://www.googleapis.com/robot/v1/metadata/x509/service-1@example-project-12345.iam.gserviceaccount.com
        jwtLocations:
          - header: Authorization
            valuePrefix: "Bearer "
    service-2:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: "service-2@example-project-12345.iam.gserviceaccount.com"
        jwksUri: "https://www.googleapis.com/robot/v1/metadata/x509/service-2@example-project-12345.iam.gserviceaccount.com"

(Facoltativo) Aggiungi audiences alla sezione securitySchemes. Se non aggiungi audiences, API Gateway richiede che l'"aud" (pubblico) attestazione nel JWT sia nel formato https://SERVICE_NAME, dove SERVICE_NAME è il nome del servizio API Gateway, che hai configurato nel campo servers.url del documento OpenAPI.
Aggiungi una sezione security a livello principale del file (senza rientro o nidificazione) da applicare all'intera API o a livello di metodo da applicare a un metodo specifico. Se utilizzi le sezioni security sia a livello di API sia a livello di metodo, le impostazioni a livello di metodo sostituiscono quelle a livello di API.
```
security:
  - SCHEME_NAME: []
```
- Sostituisci SCHEME_NAME con il nome che hai utilizzato nella sezione securitySchemes.
- Se hai più di una definizione nella sezione securitySchemes, aggiungile nella sezione security, ad esempio:
```
security:
  - service-1: []
  - service-2: []
```
Esegui il deployment della configurazione API aggiornata. Prima che API Gateway inoltri una richiesta alla tua API, API Gateway verifica:
- La firma del JWT utilizzando la chiave pubblica, che si trova nell'URI specificato nel jwksUricampo nella configurazione API.
- Che l'attestazione "iss"(emittente) nel JWT corrisponda al valore specificato nel issuercampo.
- Che l'attestazione "aud"(pubblico) nel JWT contenga il nome del servizio API Gateway o corrisponda a uno dei valori specificati nel campo audiences
- Che il token non sia scaduto utilizzando l'attestazione "exp"(ora di scadenza).

Effettuare una richiesta autenticata a un'API API Gateway

Per effettuare una richiesta autenticata, il servizio chiamante invia un JWT firmato dal account di servizio specificato nella configurazione API. Il servizio chiamante deve:

Creare un JWT e firmarlo con la chiave privata del account di servizio.
Inviare il JWT firmato in una richiesta all'API.

Il seguente codice campione illustra questa procedura per le lingue selezionate. Per effettuare una richiesta autenticata in altre lingue, consulta jwt.io per un elenco delle librerie supportate.

Nel servizio chiamante, aggiungi la seguente funzione e passale i seguenti parametri:

Java

saKeyfile: il percorso completo del file della chiave privata del account di servizio.
saEmail: l'indirizzo email del account di servizio.
audience: se hai aggiunto il campo x-google-audiences alla configurazione API, imposta audience su uno dei valori specificati per x-google-audiences. In caso contrario, imposta audience su https://SERVICE_NAME, dove SERVICE_NAME è il nome del servizio API Gateway.
expiryLength: l'ora di scadenza del JWT, in secondi.

Python

sa_keyfile: il percorso completo del file della chiave privata del account di servizio.
sa_email: l'indirizzo email del account di servizio.
audience: se hai aggiunto il campo x-google-audiences alla configurazione API, imposta audience su uno dei valori specificati per x-google-audiences. In caso contrario, imposta audience su https://SERVICE_NAME, dove SERVICE_NAME è il nome del servizio API Gateway.
expiry_length: l'ora di scadenza del JWT, in secondi.

saKeyfile: il percorso completo del file della chiave privata del account di servizio.
saEmail: l'indirizzo email del account di servizio.
audience: se hai aggiunto il campo x-google-audiences alla configurazione API, imposta audience su uno dei valori specificati per x-google-audiences. In caso contrario, imposta audience su https://SERVICE_NAME, dove SERVICE_NAME è il nome del servizio API Gateway.
expiryLength: l'ora di scadenza del JWT, in secondi.

La funzione crea un JWT, lo firma utilizzando il file della chiave privata e restituisce il JWT firmato.

Java

/**
 * Generates a signed JSON Web Token using a Google API Service Account
 * utilizes com.auth0.jwt.
 */
public static String generateJwt(final String saKeyfile, final String saEmail,
    final String audience, final int expiryLength)
    throws FileNotFoundException, IOException {

  Date now = new Date();
  Date expTime = new Date(System.currentTimeMillis() + TimeUnit.SECONDS.toMillis(expiryLength));

  // Build the JWT payload
  JWTCreator.Builder token = JWT.create()
      .withIssuedAt(now)
      // Expires after 'expiryLength' seconds
      .withExpiresAt(expTime)
      // Must match 'issuer' in the security configuration in your
      // swagger spec (e.g. service account email)
      .withIssuer(saEmail)
      // Must be either your Endpoints service name, or match the value
      // specified as the 'x-google-audience' in the OpenAPI document
      .withAudience(audience)
      // Subject and email should match the service account's email
      .withSubject(saEmail)
      .withClaim("email", saEmail);

  // Sign the JWT with a service account
  FileInputStream stream = new FileInputStream(saKeyfile);
  ServiceAccountCredentials cred = ServiceAccountCredentials.fromStream(stream);
  RSAPrivateKey key = (RSAPrivateKey) cred.getPrivateKey();
  Algorithm algorithm = Algorithm.RSA256(null, key);
  return token.sign(algorithm);
}

Python

def generate_jwt(
    sa_keyfile,
    sa_email="account@project-id.iam.gserviceaccount.com",
    audience="your-service-name",
    expiry_length=3600,
):
    """Generates a signed JSON Web Token using a Google API Service Account."""

    now = int(time.time())

    # build payload
    payload = {
        "iat": now,
        # expires after 'expiry_length' seconds.
        "exp": now + expiry_length,
        # iss must match 'issuer' in the security configuration in your
        # swagger spec (e.g. service account email). It can be any string.
        "iss": sa_email,
        # aud must be either your Endpoints service name, or match the value
        # specified as the 'x-google-audience' in the OpenAPI document.
        "aud": audience,
        # sub and email should match the service account's email address
        "sub": sa_email,
        "email": sa_email,
    }

    # sign with keyfile
    signer = google.auth.crypt.RSASigner.from_service_account_file(sa_keyfile)
    jwt = google.auth.jwt.encode(signer, payload)

    return jwt


// generateJWT creates a signed JSON Web Token using a Google API Service Account.
func generateJWT(saKeyfile, saEmail, audience string, expiryLength int64) (string, error) {
	now := time.Now().Unix()

	// Build the JWT payload.
	jwt := &jws.ClaimSet{
		Iat: now,
		// expires after 'expiryLength' seconds.
		Exp: now + expiryLength,
		// Iss must match 'issuer' in the security configuration in your
		// swagger spec (e.g. service account email). It can be any string.
		Iss: saEmail,
		// Aud must be either your Endpoints service name, or match the value
		// specified as the 'x-google-audience' in the OpenAPI document.
		Aud: audience,
		// Sub and Email should match the service account's email address.
		Sub:           saEmail,
		PrivateClaims: map[string]interface{}{"email": saEmail},
	}
	jwsHeader := &jws.Header{
		Algorithm: "RS256",
		Typ:       "JWT",
	}

	// Extract the RSA private key from the service account keyfile.
	sa, err := os.ReadFile(saKeyfile)
	if err != nil {
		return "", fmt.Errorf("could not read service account file: %w", err)
	}
	conf, err := google.JWTConfigFromJSON(sa)
	if err != nil {
		return "", fmt.Errorf("could not parse service account JSON: %w", err)
	}
	block, _ := pem.Decode(conf.PrivateKey)
	parsedKey, err := x509.ParsePKCS8PrivateKey(block.Bytes)
	if err != nil {
		return "", fmt.Errorf("private key parse error: %w", err)
	}
	rsaKey, ok := parsedKey.(*rsa.PrivateKey)
	// Sign the JWT with the service account's private key.
	if !ok {
		return "", errors.New("private key failed rsa.PrivateKey type assertion")
	}
	return jws.Encode(jwsHeader, jwt, rsaKey)
}

Nel servizio chiamante, aggiungi la seguente funzione per inviare il JWT firmato nell'intestazione Authorization: Bearer nella richiesta all'API:

Java

/**
 * Makes an authorized request to the endpoint.
 */
public static String makeJwtRequest(final String signedJwt, final URL url)
    throws IOException, ProtocolException {

  HttpURLConnection con = (HttpURLConnection) url.openConnection();
  con.setRequestMethod("GET");
  con.setRequestProperty("Content-Type", "application/json");
  con.setRequestProperty("Authorization", "Bearer " + signedJwt);

  InputStreamReader reader = new InputStreamReader(con.getInputStream());
  BufferedReader buffReader = new BufferedReader(reader);

  String line;
  StringBuilder result = new StringBuilder();
  while ((line = buffReader.readLine()) != null) {
    result.append(line);
  }
  buffReader.close();
  return result.toString();
}

Python

def make_jwt_request(signed_jwt, url="https://your-endpoint.com"):
    """Makes an authorized request to the endpoint"""
    headers = {
        "Authorization": "Bearer {}".format(signed_jwt.decode("utf-8")),
        "content-type": "application/json",
    }
    response = requests.get(url, headers=headers)
    print(response.status_code, response.content)
    response.raise_for_status()


// makeJWTRequest sends an authorized request to your deployed endpoint.
func makeJWTRequest(signedJWT, url string) (string, error) {
	client := &http.Client{
		Timeout: 10 * time.Second,
	}

	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		return "", fmt.Errorf("failed to create HTTP request: %w", err)
	}
	req.Header.Add("Authorization", "Bearer "+signedJWT)
	req.Header.Add("content-type", "application/json")

	response, err := client.Do(req)
	if err != nil {
		return "", fmt.Errorf("HTTP request failed: %w", err)
	}
	defer response.Body.Close()
	responseData, err := io.ReadAll(response.Body)
	if err != nil {
		return "", fmt.Errorf("failed to parse HTTP response: %w", err)
	}
	return string(responseData), nil
}

Quando invii una richiesta utilizzando un JWT, per motivi di sicurezza ti consigliamo di inserire il token di autenticazione nell'intestazione Authorization: Bearer. Ad esempio:

curl --request POST \
  --header "Authorization: Bearer TOKEN" \
  "GATEWAY_URL/hello"

Qui, GATEWAY_URL e TOKEN devono essere sostituiti rispettivamente con l'URL del gateway di cui hai eseguito il deployment e il token di autenticazione.

Ricevere risultati autenticati nell'API

API Gateway in genere inoltra tutte le intestazioni che riceve. Tuttavia, sostituisce l'intestazione Authorization originale quando l'indirizzo del backend è specificato da x-google-backend nella configurazione API.

API Gateway invierà il risultato dell'autenticazione nell'intestazione X-Apigateway-Api-Userinfo all'API di backend. Ti consigliamo di utilizzare questa intestazione anziché l'intestazione Authorization originale. Questa intestazione è codificata in base64url e contiene il payload JWT.

Passaggi successivi

Gestire l'accesso API