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 ¶
const CloudPlatformScope = "https://www.googleapis.com/auth/cloud-platform"
CloudPlatformScope is the OAuth scope GoogleADC requests by default.
Variables ¶
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.
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.
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
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.