Documentation
¶
Overview ¶
Package tokengrant is what every OAuth grant the platform makes without a browser shares when it calls a token endpoint: the bounded client the request is sent through, the scrub a failure is read through before anyone sees it, the reading of an RFC 6749 section 5.2 refusal, and the password grant's token source (#2689). internal/upstreamauth builds the authenticators from it; it knows nothing about connections beyond the values it is handed.
Index ¶
Constants ¶
const FetchTimeout = 30 * time.Second
FetchTimeout caps how long a single token-endpoint request can take. Without it the default Go http.Client has no timeout and an unreachable IdP would hang every call until the OS-level dial timeout fires (minutes). 30 seconds matches the order of magnitude of the upstream call_timeout while staying generous for IdPs with slow first-token issuance.
const MaxDescriptionRunes = 300
MaxDescriptionRunes bounds how much of an upstream's error_description the platform repeats in a tool error and an alert.
Variables ¶
This section is empty.
Functions ¶
func Description ¶
Description makes an upstream's error_description safe to repeat in a tool error and an email: control characters become spaces, runs of whitespace collapse, and the text is cut at MaxDescriptionRunes.
func IsRefusal ¶
IsRefusal reports whether an RFC 6749 section 5.2 error code is a refusal an operator fixes at the upstream or in the connection: the grant or its user is not accepted (invalid_grant), the client is not recognized (invalid_client), the client may not use this grant (unauthorized_client), or a scope it names is not one the endpoint issues (invalid_scope). Other codes describe a malformed request, which is the platform's fault rather than the connection's.
func NewClient ¶
NewClient builds the http.Client a token request is sent through, on the outbound chain (the platform's User-Agent, its span and metrics), bounded by FetchTimeout.
When caBundlePEM is set the bundle is appended to the system root pool and attached to a dedicated transport: public CAs remain trusted, and the bundle never substitutes for them. A bundle that does not parse leaves the default transport, and the request fails its TLS handshake on the normal error path. Client mTLS material is deliberately not plumbed here: presenting a client certificate to the IdP is a decision that should not piggy-back on the upstream's.
func Scrub ¶
Scrub rebuilds a failed token request's error from its non-sensitive parts. The library's *oauth2.RetrieveError carries the IdP's response body, which can hold material from a partial grant exchange, and a *url.Error carries the token URL, whose query or userinfo can hold a credential an operator embedded in it. The result carries no prefix; the caller states it in its kind's voice.
func WithoutSecrets ¶
WithoutSecrets removes each secret from text. An upstream that echoes a submitted password in its error_description would otherwise put it in a tool error, an audit row and a connection test result. An empty secret is skipped.
Types ¶
type Password ¶
type Password struct {
TokenURL string
ClientID string
ClientSecret string
Username string
Password string
Scopes []string
// InParams sends the client credentials as form parameters rather than
// HTTP Basic. With no client secret they are always parameters, which
// omit what is empty: the header style would send "Basic Og==".
InParams bool
// Fill returns a value as it is sent: a stored-secret placeholder read,
// anything else unchanged.
Fill func(ctx context.Context, value string) (string, error)
}
Password is what the RFC 6749 section 4.3 resource owner password grant posts: the client and the API user (#2689). Any of the four credentials may name a stored secret; Fill reads each for the request it is sent on.
type PasswordSource ¶
type PasswordSource struct {
// contains filtered or unexported fields
}
PasswordSource is the oauth2.TokenSource behind a password grant connection's token cache. It holds the refresh token the last response carried, in memory only, and renews with it before falling back to the password; nothing it holds is stored.
func NewPasswordSource ¶
func NewPasswordSource(ctx context.Context, p Password) *PasswordSource
NewPasswordSource returns the source. ctx carries the token-request client (oauth2.HTTPClient); oauth2.TokenSource has no per-call context.
func (*PasswordSource) Granted ¶
func (s *PasswordSource) Granted() (user string, scopes []string, ok bool)
Granted reports the user the endpoint last issued a token for and the scopes it carries, and false before the first.
func (*PasswordSource) Redact ¶
func (s *PasswordSource) Redact(text string) string
Redact removes from text the password and client secret the last request sent.
func (*PasswordSource) Token ¶
func (s *PasswordSource) Token() (*oauth2.Token, error)
Token renews the access token: with the held refresh token when there is one, and with the password when there is none or the upstream refuses it. A refresh that fails for any other reason (network, a 5xx) is returned and the refresh token kept, since the password would not reach the upstream either. The token returned carries no refresh token.