Package idtoken provides functionality for generating and validating ID tokens, with configurable options for audience, custom claims, and token formats.
For more information on ID tokens, see https://cloud.google.com/docs/authentication/token-types#id.
Functions
func NewCredentials
func NewCredentials(opts *Options) (*auth.Credentials, error)NewCredentials creates a [cloud.google.com/go/auth.Credentials] that returns ID tokens configured by the opts provided. The parameter opts.Audience must not be empty. If both opts.CredentialsFile and opts.CredentialsJSON are empty, an attempt will be made to detect credentials from the environment (see [cloud.google.com/go/auth/credentials.DetectDefault]). Only service account, impersonated service account, external account and Compute credentials are supported.
Example
setAuthorizationHeader
package main
import (
"context"
"net/http"
"cloud.google.com/go/auth/credentials/idtoken"
"cloud.google.com/go/auth/httptransport"
)
func main() {
ctx := context.Background()
audience := "http://example.com"
creds, err := idtoken.NewCredentials(&idtoken.Options{
Audience: audience,
})
if err != nil {
// Handle error.
}
token, err := creds.Token(ctx)
if err != nil {
// Handle error.
}
req, err := http.NewRequest(http.MethodGet, audience, nil)
if err != nil {
// Handle error.
}
httptransport.SetAuthHeader(token, req)
}
ComputeTokenFormat
type ComputeTokenFormat intComputeTokenFormat dictates the the token format when requesting an ID token from the compute metadata service.
ComputeTokenFormatDefault, ComputeTokenFormatStandard, ComputeTokenFormatFull, ComputeTokenFormatFullWithLicense
const (
// ComputeTokenFormatDefault means the same as [ComputeTokenFormatFull].
ComputeTokenFormatDefault ComputeTokenFormat = iota
// ComputeTokenFormatStandard mean only standard JWT fields will be included
// in the token.
ComputeTokenFormatStandard
// ComputeTokenFormatFull means the token will include claims about the
// virtual machine instance and its project.
ComputeTokenFormatFull
// ComputeTokenFormatFullWithLicense means the same as
// [ComputeTokenFormatFull] with the addition of claims about licenses
// associated with the instance.
ComputeTokenFormatFullWithLicense
)Options
type Options struct {
// Audience is the `aud` field for the token, such as an API endpoint the
// token will grant access to. Required.
Audience string
// ComputeTokenFormat dictates the the token format when requesting an ID
// token from the compute metadata service. Optional.
ComputeTokenFormat ComputeTokenFormat
// CustomClaims specifies private non-standard claims for an ID token.
// Optional.
CustomClaims map[string]interface{}
// CredentialsFile sources a JSON credential file from the provided
// filepath. If provided, do not provide CredentialsJSON. Optional.
CredentialsFile string
// CredentialsJSON sources a JSON credential file from the provided bytes.
// If provided, do not provide CredentialsJSON. Optional.
CredentialsJSON []byte
// Client configures the underlying client used to make network requests
// when fetching tokens. If provided this should be a fully-authenticated
// client. Optional.
Client *http.Client
}Options for the configuration of creation of an ID token with [NewCredentials].
Payload
type Payload struct {
Issuer string `json:"iss"`
Audience string `json:"aud"`
Expires int64 `json:"exp"`
IssuedAt int64 `json:"iat"`
Subject string `json:"sub,omitempty"`
Claims map[string]interface{} `json:"-"`
}Payload represents a decoded payload of an ID token.
func ParsePayload
ParsePayload parses the given token and returns its payload.
Warning: This function does not validate the token prior to parsing it.
ParsePayload is primarily meant to be used to inspect a token's payload. This is useful when validation fails and the payload needs to be inspected.
Note: A successful Validate() invocation with the same token will return an identical payload.
func Validate
Validate is used to validate the provided idToken with a known Google cert URL. If audience is not empty the audience claim of the Token is validated. Upon successful validation a parsed token Payload is returned allowing the caller to validate any additional claims.
Validator
type Validator struct {
// contains filtered or unexported fields
}Validator provides a way to validate Google ID Tokens
func NewValidator
func NewValidator(opts *ValidatorOptions) (*Validator, error)NewValidator creates a Validator that uses the options provided to configure a the internal http.Client that will be used to make requests to fetch JWKs.
func (*Validator) Validate
func (v *Validator) Validate(ctx context.Context, idToken string, audience string) (*Payload, error)Validate is used to validate the provided idToken with a known Google cert URL. If audience is not empty the audience claim of the Token is validated. Upon successful validation a parsed token Payload is returned allowing the caller to validate any additional claims.
ValidatorOptions
type ValidatorOptions struct {
// Client used to make requests to the certs URL. Optional.
Client *http.Client
}ValidatorOptions provides a way to configure a [Validator].