blob: 450a639799d028edc6edbc097cd720b30b3677ca [file] [log] [blame]
// Copyright 2019 The LUCI Authors.
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// See the License for the specific language governing permissions and
// limitations under the License.
// Package vmtoken implements parsing and verification of signed GCE VM metadata
// tokens.
// See
// Intended to be used from a server environment (e.g. from a GAE), since it
// depends on a bunch of luci/server packages that require a properly configured
// context.
package vmtoken
import (
// Header is the name of the HTTP header where the GCE VM metadata token is
// expected.
const Header = "X-Luci-Gce-Vm-Token"
// Payload is extracted from a verified GCE VM metadata token.
// It identifies a VM that produced the token and the target audience for
// the token (as it was supplied to the GCE metadata endpoint via 'audience'
// request parameter when generating the token).
type Payload struct {
Project string // GCE project name, e.g. "my-bots" or ""
Zone string // GCE zone name where the VM is, e.g. "us-central1-b"
Instance string // VM instance name, e.g. "my-instance-1"
Audience string // 'aud' field inside the token, usually the server URL
// Verify parses a GCE VM metadata token, verifies its signature and expiration
// time, and extracts interesting parts of it into Payload struct.
// Does NOT verify the audience field. This is responsibility of the caller.
// The token is in JWT form (three dot-separated base64-encoded strings). It is
// expected to be signed by Google OAuth2 backends using RS256 algo.
func Verify(c context.Context, jwt string) (*Payload, error) {
// Grab root Google OAuth2 keys to verify JWT signature. They are most likely
// already cached in the process memory.
certs, err := signing.FetchGoogleOAuth2Certificates(c)
if err != nil {
return nil, err
return verifyImpl(c, jwt, certs)
// signatureChecker is used to mock signing.PublicCertificates in tests.
type signatureChecker interface {
CheckSignature(key string, signed, signature []byte) error
func verifyImpl(c context.Context, jwt string, certs signatureChecker) (*Payload, error) {
chunks := strings.Split(jwt, ".")
if len(chunks) != 3 {
return nil, errors.Reason("bad JWT: expected 3 components separated by '.'").Err()
// Check the header, grab the key ID from it.
var hdr struct {
Alg string `json:"alg"`
Kid string `json:"kid"`
if err := unmarshalB64JSON(chunks[0], &hdr); err != nil {
return nil, errors.Annotate(err, "bad JWT header").Err()
if hdr.Alg != "RS256" {
return nil, errors.Reason("bad JWT: only RS256 alg is supported, not %q", hdr.Alg).Err()
if hdr.Kid == "" {
return nil, errors.Reason("bad JWT: missing the signing key ID in the header").Err()
// Need a raw binary blob with the signature to verify it.
sig, err := base64.RawURLEncoding.DecodeString(chunks[2])
if err != nil {
return nil, errors.Annotate(err, "bad JWT: can't base64 decode the signature").Err()
// Check that "b64(hdr).b64(payload)" part of the token matches the signature.
// If it does, we know the token was created by Google.
if err = certs.CheckSignature(hdr.Kid, []byte(chunks[0]+"."+chunks[1]), sig); err != nil {
return nil, errors.Annotate(err, "bad JWT: bad signature").Err()
// Decode the payload. There should be no errors here generally, the encoded
// payload is signed and the signature was already verified. Note that for the
// sake of completeness and documentation we decode all fields usually present
// in the token, even though we use only subset of them below.
var payload struct {
Aud string `json:"aud"` // audience
Azp string `json:"azp"` // authorized party (GCE VM service account ID)
Email string `json:"email"` // GCE VM service account email
EmailVerified bool `json:"email_verified"` // always true
Exp int64 `json:"exp"` // "expiry", as unix timestamp
Iat int64 `json:"iat"` // "issued at", as unix timestamp
Iss string `json:"iss"` // issuer name
Sub string `json:"sub"` // subject (GCE VM service account ID)
Google struct {
ComputeEngine struct {
InstanceCreationTimestamp int64 `json:"instance_creation_timestamp"`
InstanceID string `json:"instance_id"`
InstanceName string `json:"instance_name"`
ProjectID string `json:"project_id"`
ProjectNumber int64 `json:"project_number"`
Zone string `json:"zone"`
} `json:"compute_engine"`
} `json:"google"`
if err = unmarshalB64JSON(chunks[1], &payload); err != nil {
return nil, errors.Annotate(err, "bad JWT payload").Err()
// Tokens can either be in "full" or "standard" format. We want "full", since
// "standard" doesn't have details about the VM.
if payload.Google.ComputeEngine.ProjectID == "" {
return nil, errors.Reason("no google.compute_engine in the GCE VM token, use 'full' format").Err()
// Check token's "issued at" and "expiry" claims. Allow some leeway for clock
// discrepancy between us and Google OAuth2 backend.
const allowedDriftSec = 30
switch now := clock.Now(c).Unix(); {
case now < payload.Iat-allowedDriftSec:
return nil, errors.Reason("bad JWT: too early (now %d < iat %d)", now, payload.Iat).Err()
case now > payload.Exp+allowedDriftSec:
return nil, errors.Reason("bad JWT: expired (now %d > exp %d)", now, payload.Exp).Err()
// The caller is supposed to check 'aud' claim to finish the verification.
return &Payload{
Project: payload.Google.ComputeEngine.ProjectID,
Zone: payload.Google.ComputeEngine.Zone,
Instance: payload.Google.ComputeEngine.InstanceName,
Audience: payload.Aud,
}, nil
func unmarshalB64JSON(blob string, out interface{}) error {
raw, err := base64.RawURLEncoding.DecodeString(blob)
if err != nil {
return errors.Annotate(err, "not base64").Err()
if err := json.Unmarshal(raw, out); err != nil {
return errors.Annotate(err, "not JSON").Err()
return nil
// pldKey is the key to a *Payload in the context.
var pldKey = "pld"
// withPayload returns a new context with the given *Payload installed.
func withPayload(c context.Context, p *Payload) context.Context {
return context.WithValue(c, &pldKey, p)
// getPayload returns the *Payload installed in the current context. May be nil.
func getPayload(c context.Context) *Payload {
p, _ := c.Value(&pldKey).(*Payload)
return p
// Clear returns a new context without a GCE VM metadata token installed.
func Clear(c context.Context) context.Context {
return context.WithValue(c, &pldKey, nil)
// Has returns whether the current context contains a valid GCE VM metadata
// token.
func Has(c context.Context) bool {
return getPayload(c) != nil
// Hostname returns the hostname of the VM stored in the current context.
func Hostname(c context.Context) string {
p := getPayload(c)
if p == nil {
return ""
return p.Instance
// CurrentIdentity returns the identity of the VM stored in the current context.
func CurrentIdentity(c context.Context) string {
p := getPayload(c)
if p == nil {
return "gce:anonymous"
// GCE hostnames must be unique per project, so <instance, project> suffices.
return fmt.Sprintf("gce:%s:%s", p.Instance, p.Project)
// Matches returns whether the current context contains a GCE VM metadata
// token matching the given identity.
func Matches(c context.Context, host, zone, proj string) bool {
p := getPayload(c)
if p == nil {
return false
logging.Debugf(c, "expecting VM token from %q in %q in %q", host, zone, proj)
return p.Instance == host && p.Zone == zone && p.Project == proj
// Middleware embeds a Payload in the context if the request contains a GCE VM
// metadata token.
func Middleware(c *router.Context, next router.Handler) {
if tok := c.Request.Header.Get(Header); tok != "" {
// TODO(smut): Support requests to other modules, versions.
aud := "https://" + info.DefaultVersionHostname(c.Context)
logging.Debugf(c.Context, "expecting VM token for: %s", aud)
switch p, err := Verify(c.Context, tok); {
case transient.Tag.In(err):
logging.WithError(err).Errorf(c.Context, "transient error verifying VM token")
http.Error(c.Writer, "error: failed to verify VM token", http.StatusInternalServerError)
case err != nil:
logging.WithError(err).Errorf(c.Context, "invalid VM token")
http.Error(c.Writer, "error: invalid VM token", http.StatusUnauthorized)
case p.Audience != aud:
logging.Errorf(c.Context, "received VM token intended for: %s", p.Audience)
http.Error(c.Writer, "error: VM token audience mismatch", http.StatusUnauthorized)
logging.Debugf(c.Context, "received VM token from %q in %q in %q for: %s", p.Instance, p.Zone, p.Project, p.Audience)
c.Context = withPayload(c.Context, p)
func init() {
warmup.Register("gce/vmtoken", func(c context.Context) error {
_, err := signing.FetchGoogleOAuth2Certificates(c)
return err