More and more Services that _you_ deploy on Google Cloud can have automatic perimeter authentication enabled by default. What i mean by that is you can now deploy a Cloud Function or Cloud Run instance and automatically enforce IAM policies that allow only certain identities through that you allow. These clients that access your service must present a Google Issued OpenID Connect token.
I often find customers asking how to provide these tokens and so I wrote up this article to help point users on how to acquire and validate ID tokens. The samples provided here are as-is but they do work.
NOTE: Ultimately, a variation of this article will reside on Google Cloud’s documentation. Until that is live, i’ll keep this blog available or later on, redirect to that
Anyway..lets get started:
This section covers authenticating against security perimeters which requires clients present valid OpenID Connect tokens. These security perimeters do not protect Google APIs but your services deployed behind certain Google Cloud Products. For example, if you deploy to Cloud Functions or an application on Cloud Run, you can enable a perimeter such that any client that wants to invoke the function or your application must present an ID token issued by Google.
These tokens are not Oauth2 access_tokens you would use to call a Google Service or API directly such as a Google Compute Engine API or Cloud Storage Bucket but id_tokens that assert identity and are signed by Google.
This section covers authenticating against security perimeters which requires clients present valid OpenID Connect…
What is an id_token?
OpenIDConnect (OIDC) tokens are signed JSON Web Tokens JWT used to assert identity and do not necessarily carry any implicit authorization against a resource. These tokens will just declare who the caller is and any service that the token is sent to can verify the token’s integrity by verifying the signature payload provided with the JWT. For more information, see the links in the References section below
If the ID Token is signed and issued by Google, that token can be used as a token against GCP service perimeters because the service can decode the token, verify its signature and finally identify the caller using values within the JWT claim. For example, the JWT header and payload below describes a token that was issued by google (
"iss": "https://accounts.google.com"), identifies the caller (
"email": "svc_account@.project.gserviceaccount.com"), has not expired (the service will check the
exp: field), and finally will verify the JWT is intended for the service or not to
Note: the subject (
sub) claim in the token above represents the unique internal Google identifier account representing the ID Token.
Whats an Audience?
aud: field describes the service name this token was created to invoke. If a service receives an id_token, it must verify its integrity (signature), validity (is it expired) and if the aud: field is the predefined name it expects to see. If the names do not match, the service should reject the token as it could be a replay intended for another system.
Both Google Service Accounts and Users can get id_tokens but with an important distinction: User login oauth flows issue id_tokens statically bound to the web or oauth2 client_id the flow as associated with. That is, if a user logs into a web application involving oauth2, the id_token that the provider issues to the browser will have the aud: field bound to the oauth2 client_id.
Service Accounts on the other hand, can participate in a flow where it can receive and id_token from google with an aud: field it specified earlier. These token types issued by Service Accounts are generally the ones discussed in this article.
Sources of Google Issued ID Tokens
There are several ways to get a Google-issued id_token for a Service Account
Service Account JSON certificate
If you have a Google-issued Service account certificate file locally, you can sign the JWT with specific claims and exchange that with google to get a google-issued id_token. While specifying the claims to sign, a predefined claim called target_audience which when set will be used by Google oauth endpoint and reinterpreted as the aud: field in the id_token.
The flow using a json is:
- 1. Use the service account JSON file to sign a JWT with intended final audience set as target_audience.
- 2. Exchange the signed JWT with Google token endpoint: https://www.googleapis.com/oauth2/v3/certs
- 3. Google will verify the signature and identify the aller as the Service Account (since the caller had possession of the private key), then issue an id_token with the aud: field set to what the target_audience was set.
- 4. Return the id_token in the response back to the client.
If a metadata server is available while running on Compute Engine, Appengine 2nd Generation, Cloud Functions or even Kubernetes engine, getting an id_token is simple: query the server itself for the token and provide the audience field the token should be for.
For example, the following
curl command on any platform with metadata server will return an id_token:
curl -s \
-H 'Metadata-Flavor: Google' \ http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=https://example.com`
Google Cloud IAM Credentials API provides a way for one service account to generate short lived tokens on behalf of another. One of the token types it can issue is an
id_token via the generateIdToken() endpoint. Making Authorized Requests Once you have an id_token, provide that in the request Authorization header as:
Authorization: Bearer id_token
curl -v -H "Authorization: Bearer id_token" \
Services Accepting OIDC tokens for authentication
The following platforms use Google OIDC tokens for access controls. If you deploy an application behind any of of these services, you can optionally enable IAM access controls. What that will do is require any inbound access to a service to provide a valid Google OIDC token.
Furthermore, the token must have its aud: field set to the service name being invoked. For example, to invoke a Cloud Run service, you must setup IAM access for the users (see Managing access via IAM and any ID token provided must have be signed with the aud: field set to the service name itself. If the Cloud Run service is https://svc.-hash-.zone.cloud.run, the audience field must be set to the same
- Google Cloud Run
- Google Cloud Functions
- Google Identity Aware Proxy
- Google Cloud Endpoints (if using Google OIDC)
You can also deploy your own service outside of these services and verifying an OpenID Connect token. In this mode, your application that receives an OIDC token will need to manually verify its validity and audience field. You can use application frameworks like to do this like Spring Security, proxies like Envoy or even higher level Services like Istio.
For detailed implementation, see:
- Automatic OIDC: Using Cloud Scheduler, Tasks, and PubSub to make authenticated calls to Cloud Run, Cloud Functions or your Server
Services that include OIDC tokens in webhooks
Other services also support automatically including an OIDC token along with a webhook request
For example, you can configure Cloud Scheduler to emit an OIDC token with a preset audience. When a scheduled tasks fires, an http webhook url will be called and within the header payload, the OIDC token will get transmitted within the
Authorization header. The webhook target can be your own application or any of the services listed in the previous section. If your application is running outside of these services listed under
Services Accepting OIDC tokens for authentication, you will need to parse and verify the OIDC token.
For detailed implementation, see:
How to get an ID Token
There are several flows to get an ID Token available. The snippets below demonstrate how to
- Get an IDToken
- Verify an IDToken
- Issue an authenticated request using the IDToken
Each while using
- Service Account JSON certificate
- Compute Engine Credentials
Disclaimer: the following snippets potentially use 3rd party libraries and is not supported by Google
Several samples below are just temprorary solutions: google-cloud libraries should eventually support creating and validating ID tokens. The library/language sets where there are pending PRs for this feature is cited below
gcloud auth activate-service-account \
--key-file=/path/to/svc_account.jsongcloud auth print-identity-token --audience=https://example.com
- 7/10/19: gcloud supports only getting an IDToken for Service Account JSON
- google-oauth flavor: https://github.com/salrashid123/oauth2
- raw flows: golang/GoogleIDToken.go
- metadata: https://code-review.googlesource.com/c/gocloud/+/42110
How to verify an ID Token?
You can verify OIDC tokens manually if the inbound framework you deployed an application to does automatically perform the validation. In these cases, you the snippets provided above describe how to use google and other libraries to download the public certificates used to sign the JWT
- Google Public Certificate URL https://www.googleapis.com/oauth2/v3/certs
Any validation should not just involve verifying the public certificate and validity but also that the audience claim matches the service being invoked. For more information, see Validating an ID Token. You can find samples here that implement validation.
It is recommend to always verify locally but for debugging, you can use the tokenInfo endpoint or services that decode like jwt.io.