Esta página se ha traducido con Cloud Translation API.

Autenticación entre servicios

Además de autenticar las solicitudes de los usuarios finales, puede que quieras autenticar los servicios (usuarios no humanos) que envían solicitudes a tu API. En esta página se explica cómo usar cuentas de servicio para proporcionar autenticación a personas o servicios.

Información general

Para identificar un servicio que envía solicitudes a tu API, debes usar una cuenta de servicio. El servicio que llama usa la clave privada de la cuenta de servicio para firmar un JSON Web Token (JWT) seguro y envía el JWT firmado en la solicitud a tu API.

Para implementar la autenticación con cuenta de servicio en tu API y en el servicio de llamada, sigue estos pasos:

Crea una cuenta de servicio y una clave para que las use el servicio de llamada.
Añade compatibilidad con la autenticación en la configuración de la API de tu servicio API Gateway.
Añade código al servicio de llamadas que haga lo siguiente:
- Crea un JWT y lo firma con la clave privada de la cuenta de servicio.
- Envía el JWT firmado en una solicitud a la API.

API Gateway valida que las reclamaciones del JWT coincidan con la configuración de tu API antes de reenviar la solicitud a tu API. API Gateway no comprueba los permisos de Cloud Identity que hayas concedido en la cuenta de servicio.

Requisitos previos

En esta página se da por hecho que ya has hecho lo siguiente:

Crear una cuenta de servicio con una clave

Necesitas una cuenta de servicio con un archivo de clave privada que el servicio de llamada utilice para firmar el JWT. Si tienes más de un servicio que envía solicitudes a tu API, puedes crear una cuenta de servicio que represente a todos los servicios que hacen llamadas. Si necesitas diferenciar entre los servicios (por ejemplo, si tienen permisos diferentes), puedes crear una cuenta de servicio y una clave para cada servicio de llamada.

En esta sección se muestra cómo usar la consola de Google Cloud y la herramienta de línea de comandos gcloud para crear la cuenta de servicio y el archivo de clave privada, así como para asignar a la cuenta de servicio el rol Creador de tokens de cuenta de servicio. Para obtener información sobre cómo usar una API para llevar a cabo esta tarea, consulta el artículo Crear y gestionar cuentas de servicio.

Nota: Las claves de las cuentas de servicio suponen un riesgo para la seguridad si no se gestionan adecuadamente. Siempre que sea posible, deberías elegir una alternativa más segura a las claves de cuentas de servicio. Si debes autenticarte con una clave de cuenta de servicio, eres responsable de la seguridad de la clave privada y de otras operaciones descritas en las prácticas recomendadas para gestionar las claves de cuentas de servicio. Si no puedes crear una clave de cuenta de servicio, es posible que la creación de claves de cuenta de servicio esté inhabilitada en tu organización. Para obtener más información, consulta el artículo sobre gestionar recursos de organización seguros de forma predeterminada.

Si has obtenido la clave de cuenta de servicio de una fuente externa, debes validarla antes de usarla. Para obtener más información, consulta los requisitos de seguridad de las credenciales de fuentes externas.

Para crear una cuenta de servicio con una clave, sigue estos pasos:

Google Cloud consola

Crea una cuenta de servicio:

En la Google Cloud consola, ve a Crear cuenta de servicio.

Ir a Crear cuenta de servicio
Selecciona un proyecto.
En el campo Nombre de cuenta de servicio, escribe un nombre. La consola rellena el campo ID de cuenta de servicio en función de este nombre.Google Cloud
Opcional: En el campo Descripción de la cuenta de servicio, escribe una descripción.
Haz clic en Crear.
Haz clic en el campo Selecciona un rol.

En Todos los roles, selecciona Cuentas de servicio > Creador de tokens de cuenta de servicio.
Haz clic en Continuar.
Haz clic en Hecho para terminar de crear la cuenta de servicio.

No cierres la ventana del navegador. Lo usarás en el siguiente procedimiento.

Crea una clave de cuenta de servicio:

En la Google Cloud consola, haz clic en la dirección de correo de la cuenta de servicio que has creado.
Haz clic en Teclas.
Haz clic en Añadir clave y, a continuación, en Crear clave.
Haz clic en Crear. Se descargará un archivo de clave JSON en tu ordenador.
Haz clic en Cerrar.

gcloud

Puedes ejecutar los siguientes comandos mediante la CLI de Google Cloud en tu máquina local o en Cloud Shell.

Define la cuenta predeterminada de gcloud. Si tienes más de una cuenta, asegúrate de elegir la cuenta del Google Cloud proyecto que quieras usar.
```
gcloud auth login
```
Muestra los IDs de los proyectos de Google Cloud .
```
gcloud projects list
```
Define el proyecto predeterminado. Sustituye PROJECT_ID por el ID del proyecto que quieras usar. Google Cloud
```
gcloud config set project PROJECT_ID
```
Crea una cuenta de servicio. Sustituye SA_NAME y SA_DISPLAY_NAME por el nombre y el nombre visible que quieras usar.
```
gcloud iam service-accounts create SA_NAME \
  --display-name "SA_DISPLAY_NAME"
```
Se muestra la dirección de correo de la cuenta de servicio que acabas de crear.
```
gcloud iam service-accounts list
```

Añade el rol Creador de tokens de cuenta de servicio. Sustituye SA_EMAIL_ADDRESS por la dirección de correo de la cuenta de servicio.

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

Crea un archivo de clave de cuenta de servicio en el directorio de trabajo actual. Sustituye FILE_NAME por el nombre que quieras usar para el archivo de claves. De forma predeterminada, el comando gcloud crea un archivo JSON.
```
gcloud iam service-accounts keys create FILE_NAME.json \
  --iam-account SA_EMAIL_ADDRESS
```

Consulta la referencia de gcloud para obtener más información sobre los comandos anteriores.

Para obtener información sobre cómo proteger la clave privada, consulta las prácticas recomendadas para gestionar las credenciales.

Configurar tu API para que admita la autenticación

Cuando crea una configuración de API para su pasarela, especifica una cuenta de servicio que la pasarela usa para interactuar con otros servicios. Para habilitar la autenticación de cuentas de servicio en los servicios que llaman a tu pasarela, modifica el objeto de requisito de seguridad y el objeto de definiciones de seguridad en la configuración de tu API. Si sigues los pasos que se indican a continuación, API Gateway podrá validar las reclamaciones del JWT firmado que usan los servicios que llaman.

Añada la cuenta de servicio como emisor en la configuración de la 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"

Sustituye DEFINITION_NAME por una cadena que identifique esta definición de seguridad. Puedes sustituirlo por el nombre de la cuenta de servicio o por un nombre que identifique el servicio que hace la llamada.
Sustituye SA_EMAIL_ADDRESS por la dirección de correo de la cuenta de servicio.
Puedes definir varias definiciones de seguridad en la configuración de tu API, pero cada una debe tener un x-google-issuer diferente. Si has creado cuentas de servicio independientes para cada servicio de llamada, puedes crear una definición de seguridad para cada cuenta de servicio. Por ejemplo:

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"

Si quiere, puede añadir x-google-audiences a la sección securityDefinitions. Si no añade x-google-audiences, API Gateway requiere que la reclamación "aud" (audiencia) del JWT tenga el formato https://SERVICE_NAME, donde SERVICE_NAME es el nombre de su servicio de API Gateway, que ha configurado en el campo host de su documento OpenAPI.
Añada una sección security en el nivel superior del archivo (sin sangría ni anidación) para aplicarla a toda la API, o en el nivel del método para aplicarla a un método específico. Si usas secciones security tanto a nivel de API como a nivel de método, los ajustes a nivel de método anulan los ajustes a nivel de API.
```
security:
  - DEFINITION_NAME: []
```
- Sustituye DEFINITION_NAME por el nombre que has usado en la sección securityDefinitions.
- Si tienes más de una definición en la sección securityDefinitions, añádelas en la sección security. Por ejemplo:
```
security:
  - service-1: []
  - service-2: []
```
Implementa la configuración de API actualizada.

Antes de reenviar una solicitud a tu API, API Gateway verifica lo siguiente:

La firma del JWT mediante la clave pública, que se encuentra en el URI especificado en el campo x-google-jwks_uri de la configuración de la API.
Que la reclamación "iss" (emisor) del JWT coincida con el valor especificado en el campo x-google-issuer.
Que la reclamación "aud" (audiencia) del JWT contenga el nombre de tu servicio de API Gateway o coincida con uno de los valores que hayas especificado en el campo x-google-audiences.
Que el token no haya caducado mediante la reclamación "exp" (hora de vencimiento).

Para obtener más información sobre x-google-issuer, x-google-jwks_uri y x-google-audiences, consulta Extensiones de OpenAPI.

Realizar una solicitud autenticada a una API de API Gateway

Para hacer una solicitud autenticada, el servicio que llama envía un JWT firmado por la cuenta de servicio que has especificado en la configuración de la API. El servicio de llamadas debe cumplir los siguientes requisitos:

Crea un JWT y fírmalo con la clave privada de la cuenta de servicio.
Envía el JWT firmado en una solicitud a la API.

El siguiente código de ejemplo muestra este proceso para algunos idiomas. Para hacer una solicitud autenticada en otros idiomas, consulta jwt.io para ver una lista de bibliotecas compatibles.

En el servicio de llamada, añade la siguiente función y pásale los siguientes parámetros:

Java

saKeyfile: ruta completa al archivo de clave privada de la cuenta de servicio.
saEmail: la dirección de correo de la cuenta de servicio.
audience: Si has añadido el campo x-google-audiences a tu configuración de la API, asigna a audience uno de los valores que hayas especificado para x-google-audiences. De lo contrario, asigna el valor https://SERVICE_NAME a audience, donde SERVICE_NAME es el nombre del servicio de API Gateway.
expiryLength: tiempo de vencimiento del JWT, en segundos.

Python

sa_keyfile: ruta completa al archivo de clave privada de la cuenta de servicio.
sa_email: la dirección de correo de la cuenta de servicio.
audience: si has añadido el campo x-google-audiences a tu configuración de la API, asigna a audience uno de los valores que hayas especificado para x-google-audiences. De lo contrario, asigna el valor https://SERVICE_NAME a audience, donde SERVICE_NAME es el nombre del servicio de API Gateway.
expiry_length: tiempo de vencimiento del JWT, en segundos.

saKeyfile: ruta completa al archivo de clave privada de la cuenta de servicio.
saEmail: la dirección de correo de la cuenta de servicio.
audience: si has añadido el campo x-google-audiences a tu configuración de la API, asigna a audience uno de los valores que hayas especificado para x-google-audiences. De lo contrario, asigna el valor https://SERVICE_NAME a audience, donde SERVICE_NAME es el nombre del servicio de API Gateway.
expiryLength: tiempo de vencimiento del JWT, en segundos.

La función crea un JWT, lo firma con el archivo de clave privada y devuelve el JWT firmado.

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)
}

En el servicio de llamada, añade la siguiente función para enviar el JWT firmado en el encabezado Authorization: Bearer de la solicitud a la 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
}

Cuando envías una solicitud mediante un JWT, por motivos de seguridad, te recomendamos que incluyas el token de autenticación en el encabezado Authorization: Bearer. Por ejemplo:

curl --request POST \
  --header "Authorization: Bearer ${TOKEN}" \
  "${GATEWAY_URL}/echo"

donde GATEWAY_URL y TOKEN son variables de entorno que contienen la URL de la pasarela implementada y el token de autenticación, respectivamente.

Recibir resultados autenticados en tu API

API Gateway suele reenviar todos los encabezados que recibe. Sin embargo, anula el encabezado Authorization original cuando la dirección del backend se especifica mediante x-google-backend en la configuración de la API.

API Gateway enviará el resultado de la autenticación en el X-Apigateway-Api-Userinfo a la API de backend. Se recomienda usar este encabezado en lugar del encabezado Authorization original. Este encabezado está codificado en base64url y contiene la carga útil del JWT.

Siguientes pasos

Gestionar el acceso a la API