idtoken

Documentation

Overview

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.

Index

• func NewCredentials(opts *Options) (*auth.Credentials, error)
• type ComputeTokenFormat
• type Options
• type Payload
  • func ParsePayload(idToken string) (*Payload, error)
  • func Validate(ctx context.Context, idToken string, audience string) (*Payload, error)
• type Validator
  • func NewValidator(opts *ValidatorOptions) (*Validator, error)
  • func (v *Validator) Validate(ctx context.Context, idToken string, audience string) (*Payload, error)
• type ValidatorOptions

Examples

• NewCredentials (SetAuthorizationHeader)

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 may not be empty.

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)
}

Types

type ComputeTokenFormat

type ComputeTokenFormat int

ComputeTokenFormat dictates the the token format when requesting an ID token from the compute metadata service.

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
)

type 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 overrides detection logic and sources a credential file
	// from the provided filepath. Optional.
	CredentialsFile string
	// CredentialsJSON overrides detection logic and uses the JSON bytes as the
	// source for the credential. 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.

type 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

func ParsePayload(idToken string) (*Payload, error)

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

func 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.

type 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.

type 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.