package idtoken

import "cloud.google.com/go/auth/credentials/idtoken"

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.

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.

Source Files ¶

cache.go compute.go file.go idtoken.go validate.go