Stay organized with collections Save and categorize content based on your preferences.
Before an application sends sensitive information to a virtual machine (VM) instance, the application can verify the identity of the instance by 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 RS256 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:
Google's instance authentication methods have the following benefits:
To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
For more information, see Set up authentication for a local development environment.
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 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:
VM1 establishes a secure connection to Host1 over a secure connection protocol of your choice, such as HTTPS.
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.
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.
VM1 sends the identity token to Host1 over the existing secure connection.
Host1 decodes the identity token to obtain the token header and payload values.
Host1 verifies that the token is signed by Google by checking the audience value and verifying the certificate signature against the public Google certificate.
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.
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:
cURLCreate a curl request and include a value in the audience parameter. Optionally, you can include the format parameter to specify whether or not you want to include project and instance details in the payload. If using the full format, you can include the licenses parameter to specify whether or not you want to include license codes in the payload.
curl -H "Metadata-Flavor: Google" \ 'http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=AUDIENCE&format=FORMAT&licenses=LICENSES'
Replace the following:
AUDIENCE: 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: 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. For more information, see Identity token format.LICENSES: an optional parameter that specifies whether license codes for images associated with this instance are included in the payload. Specify TRUE to include this information or FALSE to omit this information from the payload. The default value is FALSE. Has no effect unless format is fullThe 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.
PythonYou 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.
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 tokenAfter your application receives an instance identity token from a Compute Engine instance, it can verify the token using the following process.
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.
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.
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.
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 contentsThe 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",
}
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. When requesting a full format token, specifying licenses=TRUE will also include claims about the licenses associated with the instance.
{
"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],
"instance_confidentiality": [INSTANCE_CONFIDENTIALITY],
"license_id": [
"[LICENSE_1]",
...
"[LICENSE_N]"
]
}
}
}
Where:
[TOKEN_ISSUER]: a URL identifying who issued the token. For Compute Engine, this value is https://accounts.google.com.[ISSUED_TIME]: 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]: a unix timestamp indicating when the token expires.[AUDIENCE]: 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]: the subject of the token, which is the unique ID for the service account that you associated with your instance.[AUTHORIZED_PARTY]: 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]: the ID for the project where you created the instance.[PROJECT_NUMBER]: the unique number for the project where you created the instance.[ZONE]: the zone where the instance is located.[INSTANCE_ID]: the unique ID for the instance to which this token belongs. This ID is unique within the project and zone.[INSTANCE_NAME]: the name of the instance to which this token belongs. If your project uses zonal DNS, this name can be reused across zones, so use a combination of the project_id, zone, and the instance_id values to identify a unique instance ID. Projects with global DNS enabled have unique instance name across the project.[CREATION_TIMESTAMP]: a Unix timestamp indicating when you created the instance.[INSTANCE_CONFIDENTIALITY]: 1 if the instance is a confidential VM.[LICENSE_1] through [LICENSE_N]: the license codes for images associated with this 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,
"instance_confidentiality": 1,
"license_id": [
"1000204"
]
}
}
}
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 nextExcept as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-07 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-07 UTC."],[[["Compute Engine instances can request unique instance identity tokens signed by Google, which are JSON Web Tokens (JWT) that include details about the instance."],["These tokens are used by applications to verify the identity of a Compute Engine instance before transmitting sensitive data, ensuring the connection is valid."],["Each token is unique, expires within one hour, and is generated only when requested from instance metadata, reducing the risk of unauthorized reuse."],["Verification of the token involves decoding the token, checking its signature against Google's public certificates, and comparing the payload contents to the expected values, thus confirming the instance's identity."],["Instances can request identity tokens from the metadata server, specifying an audience URI and optionally, format and license details, allowing for customized token payloads."]]],[]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4