auth

package
v0.15.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package auth resolves the credential a provider profile declares.

Resolution happens when the profile is opened, not on the first request: a profile whose key is missing or whose Google credentials cannot be found fails at construction, naming what is missing (requirement R1). A secret never appears in an error, a log line or a String().

OAuth2ClientCredentials is the one kind whose material changes while a provider is open: it exchanges a client id and secret for a short-lived access token, caches it, and fetches a new one before it expires or after the server answers 401.

How the credential is put on the wire is the dialect's business — OpenAI-shaped servers take a bearer token, Anthropic an x-api-key header, Gemini its own — so a Credential exposes the material and one helper for the common case, BearerTransport.

Index

Constants

View Source
const CloudPlatformScope = "https://www.googleapis.com/auth/cloud-platform"

CloudPlatformScope is the OAuth scope GoogleADC requests by default.

Variables

View Source
var ErrNoADC = errors.New("auth: no Google Application Default Credentials")

ErrNoADC is the error Resolve wraps when GoogleADC finds no Application Default Credentials, so a host can offer its own remedy (`gcloud auth application-default login`) with errors.Is rather than by matching text.

Functions

This section is empty.

Types

type Config

type Config struct {
	Kind Kind `json:"kind" yaml:"kind"`
	// Env names the environment variable holding the key or token, for
	// APIKey and Bearer.
	Env string `json:"env,omitempty" yaml:"env,omitempty"`
	// AltEnv lists further variables tried in order when Env is unset,
	// for a vendor whose key goes by two names (Gemini's GOOGLE_API_KEY
	// and GEMINI_API_KEY).
	AltEnv []string `json:"alt_env,omitempty" yaml:"alt_env,omitempty"`
	// Scopes overrides the OAuth scopes GoogleADC requests, and lists
	// the scopes OAuth2ClientCredentials asks for (none by default).
	Scopes []string `json:"scopes,omitempty" yaml:"scopes,omitempty"`

	// TokenURL is OAuth2ClientCredentials' token endpoint. In a profile
	// it may use ${VAR} and ${VAR:-default}, read at Resolve as params
	// are; by the time Config.Resolve sees it, it is a URL.
	TokenURL string `json:"token_url,omitempty" yaml:"token_url,omitempty"`
	// ClientIDEnv and ClientSecretEnv name the environment variables
	// holding OAuth2ClientCredentials' client id and secret. The values
	// are never written to a profile.
	ClientIDEnv     string `json:"client_id_env,omitempty" yaml:"client_id_env,omitempty"`
	ClientSecretEnv string `json:"client_secret_env,omitempty" yaml:"client_secret_env,omitempty"`
	// Audience is sent as the token request's audience parameter, for an
	// identity provider that requires one (Auth0, some Okta setups).
	Audience string `json:"audience,omitempty" yaml:"audience,omitempty"`
	// ClientAuth is how the client authenticates to the token endpoint:
	// "basic" (HTTP Basic, the default RFC 6749 recommends) or "post"
	// (client_id and client_secret in the form body).
	ClientAuth string `json:"client_auth,omitempty" yaml:"client_auth,omitempty"`
}

Config is the auth block of a profile.

func (Config) Resolve

func (c Config) Resolve(ctx context.Context, opts Options) (*Credential, error)

Resolve reads the secret or finds the Google credentials c declares.

func (Config) Validate

func (c Config) Validate() error

Validate checks the block's shape without touching the environment.

type Credential

type Credential struct {
	// contains filtered or unexported fields
}

Credential is a resolved Config.

func (*Credential) BearerTransport

func (c *Credential) BearerTransport(base http.RoundTripper) http.RoundTripper

BearerTransport returns a RoundTripper that sets "Authorization: Bearer <token>" on every request (and, for GoogleADC credentials that name one, the X-Goog-User-Project quota project), fetching the token per request so an access token is refreshed as it expires. For None it returns base unchanged. A nil base means http.DefaultTransport.

For OAuth2ClientCredentials, a 401 answer drops the token that was refused and the request is sent once more with a new one: a token revoked or expired early is replaced without the caller seeing it. Only once, so a credential the server keeps refusing surfaces as the second 401. The retry layer sits outside this transport and does not retry a 401, so the request is never sent more than twice for it.

func (*Credential) Kind

func (c *Credential) Kind() Kind

Kind reports how the credential authenticates.

func (*Credential) Secret

func (c *Credential) Secret() string

Secret returns the static key or token for APIKey and Bearer, and "" otherwise. For a dialect whose SDK takes the key directly.

func (*Credential) String

func (c *Credential) String() string

String describes the credential without its secret.

func (*Credential) Token

func (c *Credential) Token(ctx context.Context) (string, error)

Token returns a current token: the static secret for APIKey and Bearer, a fresh access token for GoogleADC and OAuth2ClientCredentials, "" for None.

type Kind

type Kind string

Kind names how a profile authenticates.

const (
	// APIKey is a static key read from an environment variable.
	APIKey Kind = "api_key"
	// Bearer is a static bearer token read from an environment variable.
	// It differs from APIKey only in intent; both are sent the same way
	// by OpenAI-shaped dialects.
	Bearer Kind = "bearer"
	// GoogleADC is Google Application Default Credentials: the credential
	// Gemini-on-Vertex and Claude-on-Vertex already use, and the one
	// Vertex AI's partner-model endpoint takes.
	GoogleADC Kind = "google_adc"
	// None sends no credential: a self-hosted server on a trusted
	// network.
	None Kind = "none"
	// OAuth2ClientCredentials exchanges a client id and secret for an
	// access token at TokenURL (RFC 6749 §4.4), the credential a model
	// behind an authenticating gateway usually takes: Apigee, Azure API
	// Management with Entra ID, Kong or Okta OIDC, SAP AI Core. The token
	// is cached and refreshed before it expires, so a session may outlive
	// any one token.
	OAuth2ClientCredentials Kind = "oauth2_client_credentials" //nolint:gosec // a kind name, not a credential
)

type Options

type Options struct {
	// Getenv replaces os.Getenv.
	Getenv func(string) string
	// DetectGoogle replaces ADC detection.
	DetectGoogle func(ctx context.Context, scopes []string) (TokenSource, error)
	// HTTPClient sends OAuth2ClientCredentials' token requests. Nil means
	// a client on http.DefaultTransport with a 30-second timeout.
	HTTPClient *http.Client
}

Options adjusts resolution. The zero value reads the process environment and real Google credentials.

type QuotaProjecter added in v0.6.4

type QuotaProjecter interface {
	QuotaProject(ctx context.Context) (string, error)
}

QuotaProjecter is implemented by a TokenSource whose credentials name a quota project: the project Google bills and quota-checks requests against when it differs from the credentials' own (user ADC with `gcloud auth application-default set-quota-project`, or GOOGLE_CLOUD_QUOTA_PROJECT). Optional.

type TokenSource

type TokenSource interface {
	Token(ctx context.Context) (string, error)
}

TokenSource yields a current access token. *auth.Credentials from cloud.google.com/go/auth satisfies it through tokenSource below.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL