Before an application sends sensitive information to a virtual machine (VM)instance, the application can verify the identity of the instance by usinginstance identity tokens signed by Google. Each instance has a uniqueJSON Web Token (JWT) that includes details about the instance as well asGoogle'sRS256 signature.Your applications can verify the signature against Google'spublic Oauth2 certificatesto confirm the identity of the instance with which they have established aconnection.

Compute Engine generates signed instance tokens only when aninstance requests them from instance metadata. Instances areable to access only their own unique token and not the tokens for any otherinstances.

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

• When you start an instance for the first time, your applications might need toensure that the instance they connected to has a valid identity before theytransmit sensitive information to the instance.
• When your policies require you to store credentials outside of theCompute Engine environment and you regularly sendthose credentials to your instances for temporary use. Your applicationscan confirm the identities of instances each time they need to transmitcredentials.

Google's instance authentication methods have the following benefits:

• Compute Engine creates a unique token each time an instancerequests it, and each token expires within one hour. You can configure yourapplications to accept an instance's identity token only once, which reducesthe risk that the token can be reused by an unauthorized system.
• Signed metadata tokens use theRFC 7519 open industry standard and theOpenID Connect 1.0,identity layer, so existing tooling and libraries will work seamlesslywith the identity tokens.

Before you begin

• Understand how toretrieve instance metadata values.
• Understand thebasics of JSON Web Tokens so that you know how to use them in your applications.
• Understand how tocreate and enable service accounts on your instances. Your instances must have a service account associated with them so that they can retrieve their identity tokens. The service account does not require any IAM permissions to retrieve these identity tokens.
• If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

  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:

  gcloudauthapplication-defaultlogin

  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.

Verifying the identity of an instance

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

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

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

3. Google generates a new unique instance identity token in JWT format andprovides it to VM1. The payload of the token includes several detailsabout the instance and also includes the audience URI. ReadToken Contents for a complete description of the tokencontents.

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

5. Host1 decodes the identity token to obtain the token header andpayload values.

6. Host1verifies that the token is signed by Google bychecking the audience value and verifying the certificate signatureagainst thepublic Google certificate.

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

Obtaining the instance identity token

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

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

importrequestsAUDIENCE_URL="http://www.example.com"METADATA_HEADERS={"Metadata-Flavor":"Google"}METADATA_VM_IDENTITY_URL=("http://metadata.google.internal/computeMetadata/v1/""instance/service-accounts/default/identity?""audience={audience}&format={format}&licenses={licenses}")FORMAT="full"LICENSES="TRUE"defacquire_token(audience:str=AUDIENCE_URL,format:str="standard",licenses:bool=True)->str:"""    Requests identity information from the metadata server.    Args:        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 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`.        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 `full`.    Returns:        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.    """# Construct a URL with the audience and format.url=METADATA_VM_IDENTITY_URL.format(audience=audience,format=format,licenses=licenses)# Request a token from the metadata server.r=requests.get(url,headers=METADATA_HEADERS)# Extract and return the token from the response.r.raise_for_status()returnr.text

Verifying the token

After your application receives an instance identity token from aCompute Engine instance, it can verify the tokenusing the following process.

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

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

   Caution: Only tokens signed using the Google certificate can be trusted toassertproperties of the Compute Engine workload.

3. If the token is valid, compare the payload contents against the expectedvalues. If the token payload includes details about the instance and theproject, your application can check theinstance_id,project_id, andzone values. Those values are a globally unique tuple that confirmsyour application is communicating with the correct instancein the desired project.

You can decode and verify the token using any tool that you like, but acommon method is to use the libraries for your language of choice. For example,you can use theverify_token method from theGoogle OAuth 2.0 libraryfor Python. Theverify_token method matches thekid value to the appropriatecertificate, verifies the signature, checks the audience claim, and returns thepayload contents from the token.

importgoogle.auth.transport.requestsfromgoogle.oauth2importid_tokendefverify_token(token:str,audience:str)->dict:"""Verify token signature and return the token payload.    Args:        token: the JSON Web Token received from the metadata server to            be verified.        audience: the unique URI agreed upon by both the instance and the            system verifying the instance's identity.    Returns:        Dictionary containing the token payload.    """request=google.auth.transport.requests.Request()payload=id_token.verify_token(token,request=request,audience=audience)returnpayload

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

Token contents

The instance identity token contains three primary parts:

• Header
• Payload
• Signature

Header

The header includes thekid value to identify whichpublic Oauth2 certificatesyou must use to verify the signature. The header also includes thealgvalue to confirm that the signature is generated using theRS256 algorithm.

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

Payload

The payload contains theaud audience claim. If the instancespecifiedformat=full when it requested the token, the payload alsoincludes claims about the virtual machine instance and its project.When requesting a full format token, specifyinglicenses=TRUE will alsoinclude claims about the licenses associated with the instance.

{"iss":"[TOKEN_ISSUER]","iat":[ISSUED_TIME],"exp":[EXPIRED_TIME],"aud":"[AUDIENCE]","sub":"[SUBJECT]","azp":"[AUTHORIZED_PARTY]","email":"[EMAIL]","email_verified":"[EMAIL_VERIFIED]","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. ForCompute Engine, this value ishttps://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 metadataserver.
• [EXPIRED_TIME]: a unix timestamp indicating when the token expires.
• [AUDIENCE]: the unique URI agreed upon by both the instance andthe system verifying the instance's identity. For example, the audiencecould be a URL for the connection between the two systems.
• [SUBJECT]: the subject of the token, which is the uniqueID for the service account that you associated with your instance.
• [AUTHORIZED_PARTY]: the party to which the ID Token was issued which isthe unique ID for the service account that you associated with your instance.
• [EMAIL]: The email address of the service account associated with the instance.
• [EMAIL_VERIFIED]:true if email of the service account has been verified.
• [PROJECT_ID]: the ID for the project where you created the instance.
• [PROJECT_NUMBER]: the unique number for the project where you createdthe instance.
• [ZONE]: the zone where the instance is located.
• [INSTANCE_ID]: the unique ID for the instance to which this tokenbelongs. This ID is unique within the project and zone.
• [INSTANCE_NAME]: the name of the instance to which this tokenbelongs. If your project useszonal DNS,this name can be reused across zones, so use a combination of theproject_id,zone, and theinstance_id values to identify a uniqueinstance ID. Projects with global DNS enabled have unique instance nameacross the project.
• [CREATION_TIMESTAMP]: a Unix timestamp indicating when you created theinstance.
• [INSTANCE_CONFIDENTIALITY]:1 if the instance is aconfidential VM.
• [LICENSE_1] through[LICENSE_N]: thelicense codesfor 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","email":"739419398126-compute@developer.gserviceaccount.com","email_verified":true,"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"]}}}

Signature

Google generates the signature by base64url encoding the header andthe payload and concatenating the two values. You can check this valueagainst thepublic Oauth2 certificatesto verify the token.

What's next

• Review theGoogle Cloud Well-Architected Framework.
• Authenticate workloads to other workloads over mTLS.