Verifying the Identity of Instances

Before an application sends sensitive information to a virtual machine instance, the application can verify the identity of the virtual machine using instance identity tokens signed by Google. Each instance has a unique JSON Web Token (JWT) that includes details about the instance as well as Google's RSA256 signature. Your applications can verify the signature against Google's public Oauth2 certificates to confirm the identity of the instance with which they have established a connection.

Compute Engine generates signed instance tokens only when an instance requests them from instance metadata. Instances are able to access only their own unique token and not the tokens for any other instances.

You might want to verify the identities of your instances in the following scenarios:

  • When you start an instance for the first time, your applications might need to ensure that the instance they connected to has a valid identity before they transmit sensitive information to the instance.
  • When your policies require you to store credentials outside of the Compute Engine environment and you regularly send those credentials to your instances for temporary use. Your applications can confirm the identities of instances each time they need to transmit credentials.

Google's instance authentication methods have the following benefits:

  • Compute Engine creates a unique token each time an instance requests it, and each token expires within one hour. You can configure your applications to accept an instance's identity token only once, which reduces the risk that the token can be reused by an unauthorized system.
  • Google's private keys and public Oauth2 certificates rotate daily to reduce the potential attack surface against these signatures.
  • Signed metadata tokens use the RFC 7519 open industry standard and the OpenID Connect 1.0, identity layer, so existing tooling and libraries will work seamlessly with the identity tokens.

Before you begin

Verifying the identity of an instance

In some scenarios your applications must verify the identity of an instance running on Compute Engine before transmitting sensitive data to that instance. In one typical example, there is one system is running outside of Compute Engine called "Host1" and a Compute Engine instance called "VM1". VM1 can connect to Host1 and validate the identity of that instance with the following process:

  1. VM1 establishes a secure connection to Host1 over a secure connection protocol of your choice, such as HTTPS.

  2. VM1 requests its unique identity token from the metadata server and specifies the audience of the token. In this example, the audience value is the URI for Host1. The request to the metadata server includes the audience URI so that Host1 can check the value later during the token verification step.

  3. Google generates a new unique instance identity token in JWT format and provides it to VM1. The payload of the token includes several details about the instance and also includes the audience URI. Read Token Contents for a complete description of the token contents.

  4. VM1 sends the identity token to Host1 over the existing secure connection.

  5. Host1 decodes the identity token to obtain the token header and payload values.

  6. Host1 verifies that the token is signed by Google by checking the audience value and verifying the certificate signature against the public Google certificate.

  7. If the token is valid, Host1 proceeds with the transmission and closes the connection when it is finished. Host1 and any other systems should request a new token for any subsequent connections to VM1.

Obtaining the instance identity token

When your virtual machine instance receives a request to provide its identity token, the instance requests that token from the metadata server using the normal process for getting instance metadata. For example, you might use one of the following methods:

cURL

Create a curl request and include a value in the audience parameter. Optionally, you can include format parameter to specify whether or not you want to include project and instance details in the payload.

$ curl -H "Metadata-Flavor: Google" \
'http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=[AUDIENCE]&format=[FORMAT]'

where:

  • [AUDIENCE] is the unique URI agreed upon by both the instance and the system verifying the instance's identity. For example, the audience could be a URL for the connection between the two systems.
  • [FORMAT] is the optional parameter that specifies whether or not the project and instance details are included in the payload. Specify full to include this information in the payload or standard to omit the information from the payload. The default value is standard. Read Identity Token Format to learn complete details of the token format.

The metadata server responds to this request with a JSON Web Token signed using the RS256 algorithm. The token includes a Google signature and additional information in the payload. You can send this token to other systems and applications so that they can verify the token and confirm that the identity of your instance.

Python

You can submit a simple request from your instance to the metadata server using methods in the Python requests library. The following example requests and then prints an instance identity token. The token is unique to the instance that makes this request.

import requests

AUDIENCE_URL = 'http://www.example.com'
METADATA_HEADERS = {'Metadata-Flavor': 'Google'}
FORMAT = 'full'

# Construct a URL with the audience and format.
url = 'http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience={}&format={}'.format(AUDIENCE_URL, FORMAT)

# Request a token from the metadata server.
r = requests.get(url, headers=METADATA_HEADERS)

# Extract the token from the response.
token = r.text

print(token)

The metadata server responds to this request with a JSON Web Token signed using the RS256 algorithm. The token includes a Google signature and additional information in the payload. You can send this token to other systems and applications so that they can verify the token and confirm that the identity of your instance.

Verifying the token

After your application receives an instance identity token from a Compute Engine instance, it can verify the token using the following process.

  1. Receive the token from the virtual machine instance, decode the token using an RS256 JWT decoder, and read the header contents to obtain the kid value.

  2. Verify that the token is signed by checking the token against the public Google certificate. Each public certificate has a kid value that corresponds to the kid value in the token header.

  3. If the token is valid, compare the payload contents against the expected values. If the token payload includes details about the instance and the project, your application can check the instance_id, project_id, and zone values. Those values are a globally unique tuple that confirms your application is communicating with the correct instance in the desired project.

You can decode and verify the token using any tool that you like, but a common method is to use the libraries for your language of choice. For example, you can use the verify_token method from the Google OAuth 2.0 library for Python. The verify_token method matches the kid value to the appropriate certificate, verifies the signature, checks the audience claim, and returns the payload contents from the token.

# Import libraries for token verification
import google.auth.transport.requests
from google.oauth2 import id_token

# Receive token from VM over an SSL connection
token = …
…

# Verify token signature and store the token payload
request = google.auth.transport.requests.Request()
payload = id_token.verify_token(token, request=request, audience=audience)
…

After your application verifies the token and its contents, it can proceed to communicate with that instance over a secure connection and then close the connection when it is finished. For subsequent connections, request a new token from the instance and re-verify the identity of the instance.

Token contents

The instance identity token contains three primary parts:

The header includes the kid value to identify which public Oauth2 certificates you must use to verify the signature. The header also includes the alg value to confirm that the signature is generated using the RS256 algorithm.

{
  “alg”: “RS256”,
  "kid": "511a3e85d2452aee960ed557e2666a8c5cedd8ae",
}

Payload

The payload contains the aud audience claim. If the instance specified format=full when it requested the token, the payload also includes claims about the virtual machine instance and its project.

{
   "iss": "[TOKEN_ISSUER]",
   "iat": [ISSUED_TIME],
   "exp": [EXPIRED_TIME],
   "aud": "[AUDIENCE]",
   "sub": "[SUBJECT]",
   "azp": "[AUTHORIZED_PARTY]",
   "google": {
    "compute_engine": {
      "project_id": "[PROJECT_ID]",
      "project_number": [PROJECT_NUMBER],
      "zone": "[ZONE]",
      "instance_id": [INSTANCE_ID],
      "instance_name": "[INSTANCE_NAME]"
      "instance_creation_timestamp": [CREATION_TIMESTAMP]
    }
  }
}

where:

  • [TOKEN_ISSUER] is a URL identifying who issued the token. For Compute Engine, this value is https://accounts.google.com.
  • [ISSUED_TIME] is a unix timestamp indicating when the token was issued. This value updates each time the instance requests a token from the metadata server.
  • [EXPIRED_TIME] is a unix timestamp indicating when the token expires.
  • [AUDIENCE] is the unique URI agreed upon by both the instance and the system verifying the instance's identity. For example, the audience could be a URL for the connection between the two systems.
  • [SUBJECT] is the subject of the token, which is the unique ID for the service account that you associated with your instance.
  • [AUTHORIZED_PARTY] is the party to which the ID Token was issued which is the unique ID for the service account that you associated with your instance.
  • [PROJECT_ID] is the ID for the project where you created the instance.
  • [PROJECT_NUMBER] is the unique number for the project where you created the instance.
  • [ZONE] is the zone where the instance is located.
  • [INSTANCE_ID] is the unique ID for the instance to which this token belongs. This ID is unique and never reused.
  • [INSTANCE_NAME] is the name of the instance to which this token belongs. This name can be reused by several instances over time, so use the instance_id value to identify a unique instance ID.
  • [CREATION_TIMESTAMP] is a unix timestamp indicating when you created the instance.

Your payload might look similar to the following example:

{
  "iss": "https://accounts.google.com",
  "iat": 1496953245,
  "exp": 1496956845,
  "aud": "https://www.example.com",
  "sub": "107517467455664443765",
  "azp": "107517467455664443765",
  "google": {
    "compute_engine": {
      "project_id": "my-project",
      "project_number": 739419398126,
      "zone": "us-west1-a",
      "instance_id": "152986662232938449",
      "instance_name": "example",
      "instance_creation_timestamp": 1496952205
    }
  }
}

Signature

Google generates the signature by base64url encoding the header and the payload and concatenating the two values. You can check this value against the public Oauth2 certificates to verify the token.

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Compute Engine Documentation