Autenticación entre servicios

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

Descripción general

Para identificar un servicio que envía solicitudes a tu API, usas una cuenta de servicio. El servicio de llamadas usa la clave privada de la cuenta de servicio para firmar un token web JSON (JWT) seguro y enviarlo en la solicitud a tu API.

Para implementar la autenticación de cuentas de servicio en tu API y en el servicio de llamadas, completa los pasos siguientes:

1. Crea una cuenta de servicio y una clave para que use el servicio de llamadas.
2. Agrega compatibilidad con la autenticación en la configuración de la API para tu servicio de API Gateway.

3. Agrega código al servicio de llamadas que realiza las tareas siguientes:

   • 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.

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

Requisitos previos

En esta página, se supone que ya:

• Creaste un proyecto de Google Cloud.

• Creaste un documento de OpenAPI que describe tu API.

• Creaste una configuración de API.

Crea una cuenta de servicio con una clave

Necesitas una cuenta de servicio con un archivo de claves privadas que el servicio de llamadas usa para firmar el JWT. Si tienes más de un servicio que envía solicitudes a tu API, puedes crear una cuenta que represente todos los servicios de llamadas. Si necesitas diferenciar entre los servicios (por ejemplo, podrían tener permisos diferentes), puedes crear una cuenta de servicio y una clave para cada servicio de llamadas.

En esta sección, se muestra cómo usar la consola de Google Cloud y la herramienta de línea de comandos de gcloud para crear la cuenta de servicio y el archivo de claves privadas, y asignar a la cuenta de servicio el rol de Creador de tokens de la cuenta de servicio. Si deseas obtener más información sobre el uso de una API a fin de realizar esta tarea, consulta la sección para crear y administrar cuentas de servicio.

Para crear una cuenta de servicio con una clave, completa los pasos siguientes:

Si deseas obtener información sobre cómo proteger la clave privada, consulta Recomendaciones para administrar las credenciales.

Configura tu API para que sea compatible con la autenticación

Cuando creas una configuración de API para tu puerta de enlace, especificas una cuenta de servicio que esta usa para interactuar con otros servicios. Para habilitar la autenticación de cuentas de servicio para los servicios que llaman a tu puerta de enlace, modifica el objeto de requisitos 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 afirmaciones en el JWT firmado que usan los servicios de llamadas.

1. Agrega la cuenta de servicio como una entidad emisora en la configuración de tu 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"
   

   • Reemplaza DEFINITION_NAME por una string que identifique esta definición de seguridad. Es posible que desees reemplazarlo por el nombre de la cuenta de servicio o un nombre que identifique el servicio de llamadas.
   • Reemplaza SA_EMAIL_ADDRESS por la dirección de correo electrónico de la cuenta de servicio.
   • Puedes establecer varias definiciones de seguridad en tu configuración de API, pero cada definición debe tener un x-google-issuer diferente. Si creaste cuentas de servicio separadas para cada servicio de llamadas, puedes crear una definición de seguridad por 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"
   

2. O bien agrega x-google-audiences a la sección securityDefinitions. Si no agregas x-google-audiences, API Gateway requiere que la reclamación "aud" (público) en el JWT tenga el formato https://SERVICE_NAME, en el que SERVICE_NAME es el nombre de tu servicio de API Gateway que configuraste en el campo host de tu documento de OpenAPI.

3. Agrega una sección security al nivel superior del archivo (sin sangría ni anidado) para aplicarla en toda la API, o al nivel de los métodos a fin de aplicarla a un método específico. Si usas las secciones security en los niveles de la API y de los métodos, la configuración del nivel de los métodos anula la configuración del nivel de la API.

   security:
     - DEFINITION_NAME: []

   • Reemplaza DEFINITION_NAME por el nombre que usaste en la sección securityDefinitions.

   • Si tienes más de una definición en la sección securityDefinitions, agrégalas en la sección security, por ejemplo:

     security:
       - service-1: []
       - service-2: []
     

4. Implementa la configuración de API actualizada.

Antes de que API Gateway reenvíe una solicitud a tu API, la puerta de enlace de API 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 en tu configuración de API.
• Que la reclamación "iss" (entidad emisora) en el JWT coincida con el valor especificado en el campo x-google-issuer
• Que la reclamación "aud" (público) en el JWT contenga el nombre de tu servicio de API Gateway o coincida con uno de los valores que especificaste en el campo x-google-audiences
• Que el token no haya vencido 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.

Realiza una solicitud autenticada a una API de API Gateway

Para realizar una solicitud autenticada, el servicio de llamadas envía un JWT firmado por la cuenta de servicio que especificaste en la configuración de API. El servicio de llamadas debe hacer lo siguiente:

1. Crear un JWT y firmarlo con la clave privada de la cuenta de servicio
2. Enviar el JWT firmado en una solicitud a la API

En el siguiente código de muestra, se muestra este proceso para los lenguajes seleccionados. Si deseas realizar una solicitud autenticada en otros lenguajes, consulta jwt.io para obtener una lista de bibliotecas compatibles.

1. En el servicio de llamadas, agrega la función que sigue y pásala a los parámetros siguientes:
   Java

   • saKeyfile: La ruta de acceso completa al archivo de claves privadas de la cuenta de servicio
   • saEmail: La dirección de correo electrónico de la cuenta de servicio
   • audience: Si agregaste el campo x-google-audiences a tu configuración de API, configura audience como uno de los valores que especificaste para x-google-audiences. De lo contrario, configura audience como https://SERVICE_NAME, en el que SERVICE_NAME es el nombre de tu servicio de API Gateway.
   • expiryLength: El tiempo de vencimiento del JWT, en segundos

   Python

   • sa_keyfile: La ruta de acceso completa al archivo de claves privadas de la cuenta de servicio
   • sa_email: La dirección de correo electrónico de la cuenta de servicio
   • audience: Si agregaste el campo x-google-audiences a la configuración de tu API, configura audience como uno de los valores que especificaste para x-google-audiences. De lo contrario, configura audience como https://SERVICE_NAME, en el que SERVICE_NAME es el nombre de tu servicio de API Gateway.
   • expiry_length: El tiempo de vencimiento del JWT, en segundos

   Go

   • saKeyfile: La ruta de acceso completa al archivo de claves privadas de la cuenta de servicio
   • saEmail: La dirección de correo electrónico de la cuenta de servicio
   • audience: Si agregaste el campo x-google-audiences a la configuración de tu API, configura audience como uno de los valores que especificaste para x-google-audiences. De lo contrario, configura audience como https://SERVICE_NAME, en el que SERVICE_NAME es el nombre de tu servicio de API Gateway.
   • expiryLength: El tiempo de vencimiento del JWT, en segundos

   La función crea un JWT, lo firma con el archivo de claves privadas y muestra 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
   
   

   Go

   
   // 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 := ioutil.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)
   }
   

2. En el servicio de llamadas, agrega la función siguiente 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()
   
   

   Go

   
   // 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 := ioutil.ReadAll(response.Body)
   	if err != nil {
   		return "", fmt.Errorf("failed to parse HTTP response: %w", err)
   	}
   	return string(responseData), nil
   }
   

Cuando envíes una solicitud con un JWT, por motivos de seguridad, te recomendamos que coloques 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 puerta de enlace implementada y el token de autenticación, respectivamente.

Recibe resultados autenticados en tu API

Por lo general, API Gateway reenvía todos los encabezados que recibe. Sin embargo, anula el encabezado original Authorization cuando la dirección de backend se especifique mediante x-google-backend en la configuración de la API.

API Gateway enviará el resultado de la autenticación en 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 de JWT.

¿Qué sigue?

• Administra el acceso a la API