Documentation
¶
Overview ¶
Package oauthproxy lets preview and development deployments sign in with a provider through the one callback URL registered at the provider, better- auth's oauth-proxy plugin. A provider console takes a fixed list of callback URLs, and a preview deployment's URL is new every push; with this plugin the console lists only production's callback.
The flow, with the same plugin and the same secret on every deployment:
- On a preview, a provider wrapped by Wrap sends the browser to the provider with production's callback as redirect_uri and, as state, a sealed package naming the preview's own state and callback.
- Production's callback finds the package (a Before hook on the oauth plugin's callback operation), checks that the preview's origin is one it trusts, and redirects the browser to the preview's callback with the preview's state and the authorization code sealed for it. Production exchanges nothing and writes nothing.
- The preview's own oauth callback runs as always (flow cookie, state, account linking, sign-up rules); the wrapped provider opens the sealed code and exchanges it with the provider itself, with production's redirect_uri and the PKCE verifier that never left the preview.
What travels is an authorization code, not a profile: it is sealed (AES-256-GCM under a key derived from the shared secret, bound to the provider and the preview callback, valid MaxAge), and it is useless without the PKCE verifier only the preview holds. Whoever holds the secret can relay codes but cannot assert an identity to a deployment, as better-auth's encrypted-profile design allows. That design is available opt-in, with a warning at every start, as PassProfile.
Index ¶
- Constants
- Variables
- func DeploymentURL(getenv func(string) string, fallback string) string
- type Option
- type Plugin
- func (p *Plugin) Init(a *auth.Auth) error
- func (p *Plugin) IsProduction(callback string) bool
- func (p *Plugin) Name() string
- func (p *Plugin) OperationHooks() []auth.OperationHook
- func (p *Plugin) OptionErr() error
- func (p *Plugin) Requires() []string
- func (p *Plugin) Validate(c *auth.Config) error
- func (p *Plugin) Wrap(prov oauth.Provider) *Proxied
- type Proxied
- func (x *Proxied) ApplyPosted(raw string, prof *oauth.Profile)
- func (x *Proxied) AuthCodeURL(state, challenge, redirectURI string) string
- func (x *Proxied) AuthCodeURLForRequest(ctx context.Context, state, challenge, redirectURI string, ...) string
- func (x *Proxied) AuthCodeURLWithParams(state, challenge, redirectURI string, rp oauth.RequestParams) string
- func (x *Proxied) Discover(ctx context.Context, hc *http.Client) error
- func (x *Proxied) EndSession(ctx context.Context, hc *http.Client) (string, error)
- func (x *Proxied) Exchange(ctx context.Context, hc *http.Client, code, verifier, redirectURI string) (oauth.Profile, error)
- func (x *Proxied) ExpectedIssuer() string
- func (x *Proxied) FetchProfileWith(ctx context.Context, hc *http.Client, ts oauth.TokenSet) (oauth.Profile, error)
- func (x *Proxied) Label() string
- func (x *Proxied) Load(ctx context.Context, hc *http.Client) error
- func (x *Proxied) Name() string
- func (x *Proxied) OptionalScopeList() []string
- func (x *Proxied) PostsBack() bool
- func (x *Proxied) Refresh(ctx context.Context, hc *http.Client, rt auth.Token) (oauth.TokenSet, error)
- func (x *Proxied) Revoke(ctx context.Context, hc *http.Client, ts oauth.TokenSet) error
- func (x *Proxied) Unwrap() oauth.Provider
Constants ¶
const ( // DefaultMaxAge is how long a sealed state or code is accepted, // better-auth's maxAge: a relay takes a second; the provider sign-in // between the two takes the state's TTL, so the state gets StateMaxAge. //ds:def id=oauthproxy-defaultmaxage-4k8wq2nv owner=@khanakia stability=stable DefaultMaxAge = 60 * time.Second // StateMaxAge bounds a sealed state: the person signs in at the provider // between the start and production's callback, as long as the oauth // plugin's own state lives by default. //ds:def id=oauthproxy-statemaxage-7n2xk5qm owner=@khanakia stability=stable StateMaxAge = 10 * time.Minute )
Defaults and formats.
const DefaultExchangeTimeout = 10 * time.Second
DefaultExchangeTimeout bounds production's code exchange under PassProfile when HTTPClient is not given.
const PluginName = "oauthproxy"
PluginName is the plugin's permanent identity.
const RelayErrorInvalidCode = "invalid_code"
RelayErrorInvalidCode is the error parameter production relays to the preview when, under PassProfile, its own code exchange failed: better- auth's invalid_code. The preview's oauth callback then answers oauth.provider_denied and redirects to the flow's error page.
const SkipHeader = "X-Skip-OAuth-Proxy"
SkipHeader on the request that starts a sign-in turns proxying off for it, better-auth's x-skip-oauth-proxy: any non-empty value. For a preview whose callback the provider does list, or a test.
const WarnPassProfile = "" /* 177-byte string literal not displayed */
WarnPassProfile is logged at every start under PassProfile.
Variables ¶
var ( // ErrNoProductionURL is a configuration error: ProductionURL is required. ErrNoProductionURL = errors.New("oauthproxy: ProductionURL is required and must be an absolute http(s) URL") // ErrNoSecret is a configuration error: neither WithSecret nor // auth.WithSecret was given, so nothing can be sealed. ErrNoSecret = errors.New("oauthproxy: pass oauthproxy.WithSecret (the same on every deployment) or auth.WithSecret") // ErrNotWrapped is a configuration error: the plugin is registered but // no provider was wrapped, so it can do nothing on a preview. ErrNotWrapped = errors.New("oauthproxy: wrap at least one oauth provider with Plugin.Wrap") // ErrInvalidState is a sealed state that does not open, is too old, or // names an untrusted preview: production refuses to relay it. ErrInvalidState = auth.NewError("oauthproxy.invalid_state", http.StatusBadRequest, "The sign-in could not be completed. Start again.") // ErrInvalidCode is a relayed code that does not open or is too old: the // preview refuses to exchange it. ErrInvalidCode = auth.NewError("oauthproxy.invalid_code", http.StatusBadRequest, "The sign-in could not be completed. Start again.") // ErrMissingProfile is better-auth's missing_profile: under PassProfile // the preview's callback arrived with neither a sealed profile nor an // error. The oauth callback logs it and answers oauth.provider_failed. ErrMissingProfile = errors.New("oauthproxy: missing_profile: the relayed callback carries no profile") )
Errors.
Functions ¶
func DeploymentURL ¶
DeploymentURL infers this deployment's URL from the host's environment, better-auth's vendor URL inference, for auth.WithBaseURL on a preview:
auth.WithBaseURL(oauthproxy.DeploymentURL(os.Getenv, "http://localhost:8080"))
getenv is passed in (os.Getenv in an app) so nothing is read behind the caller's back; fallback is returned when no variable holds a usable URL.
Types ¶
type Option ¶
type Option func(*Plugin)
Option configures the plugin.
func HTTPClient ¶
HTTPClient sets the client production exchanges codes with under PassProfile. Default: DefaultExchangeTimeout and no redirect followed, the oauth plugin's own rule for provider calls.
func PassProfile ¶
func PassProfile() Option
PassProfile is better-auth's oauth-proxy design, opt-in: production exchanges the authorization code itself, with production's redirect_uri and a PKCE verifier the preview sealed into the state, and relays the profile and the provider's tokens to the preview sealed (AES-256-GCM, bound to the provider and the preview callback, valid MaxAge). The preview's own callback opens it and signs in as always (flow cookie and state checked first, single use with the state). Use it when only production can exchange a code (a client secret production alone holds), or to match a better-auth deployment.
Risk, which is why it is off by default and Init logs WarnPassProfile at every start: a deployment that accepts a sealed profile trusts whoever holds the proxy secret to say who signed in. With the default relay, the secret lets someone relay codes but never assert an identity. Turn it on on every participating deployment; one without it refuses a state that asks production to exchange (invalid_state) and a relayed profile (invalid_code).
func ProductionCallback ¶
ProductionCallback overrides how production's callback URL is found from the preview's: by default the preview callback's path on the production origin, which holds when every deployment mounts the routes alike.
func ProductionURL ¶
ProductionURL is the deployment whose callback URL the provider has, better-auth's productionURL. Sign-ins on that origin are not proxied.
func WithSecret ¶
WithSecret sets the secret the proxy keys are derived from, better-auth's secret option. It must be the same on every participating deployment; previous secrets still open values sealed under them. Without it the app's auth.WithSecret is used, which then must be shared too.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is the proxy plugin. Build it with New, wrap providers with Wrap, and register it beside the oauth plugin on every deployment.
func (*Plugin) IsProduction ¶
IsProduction reports whether a callback URL is on the production origin, where nothing is proxied.
func (*Plugin) OperationHooks ¶
func (p *Plugin) OperationHooks() []auth.OperationHook
OperationHooks adds the relay before the oauth callback of every wrapped provider.
func (*Plugin) OptionErr ¶
OptionErr is every error the options recorded, such as auth.ErrNilOption naming an option given nil; auth.New refuses to start while it is not nil (auth.OptionChecker).
type Proxied ¶
type Proxied struct {
// contains filtered or unexported fields
}
Proxied is a provider wrapped by Wrap. On the production origin it is the provider itself; elsewhere it sends the sign-in through production. It forwards the provider's optional capabilities (discovery, issuer check, request parameters, form posts, refresh, revoke, profile reads, logout); an ID-token sign-in and a provider-initiated flow are not proxied, so a wrapped provider does not offer them.
func (*Proxied) ApplyPosted ¶
ApplyPosted applies a form-post user field, if the provider reads one.
func (*Proxied) AuthCodeURL ¶
AuthCodeURL is the provider's URL; off production it carries production's callback and a sealed state naming this deployment's state and callback.
func (*Proxied) AuthCodeURLForRequest ¶
func (x *Proxied) AuthCodeURLForRequest(ctx context.Context, state, challenge, redirectURI string, rp oauth.RequestParams) string
AuthCodeURLForRequest is the oauth plugin's start: AuthCodeURL (with the request's parameters when the provider takes them), unproxied when the request carries SkipHeader.
func (*Proxied) AuthCodeURLWithParams ¶
func (x *Proxied) AuthCodeURLWithParams(state, challenge, redirectURI string, rp oauth.RequestParams) string
AuthCodeURLWithParams is AuthCodeURL with request parameters, when the provider takes them.
func (*Proxied) EndSession ¶
EndSession is the provider's logout URL, or "" for none.
func (*Proxied) Exchange ¶
func (x *Proxied) Exchange(ctx context.Context, hc *http.Client, code, verifier, redirectURI string) (oauth.Profile, error)
Exchange trades the code; off production a sealed code is the one production relayed, opened and exchanged with production's callback.
func (*Proxied) ExpectedIssuer ¶
ExpectedIssuer is the provider's RFC 9207 issuer, or "" for none. Production relays iss, so the check runs on the preview unchanged.
func (*Proxied) FetchProfileWith ¶
func (x *Proxied) FetchProfileWith(ctx context.Context, hc *http.Client, ts oauth.TokenSet) (oauth.Profile, error)
FetchProfileWith reads the profile, or answers oauth.ErrProfileUnsupported.
func (*Proxied) OptionalScopeList ¶
OptionalScopeList is the provider's optional scopes, or none.
func (*Proxied) Refresh ¶
func (x *Proxied) Refresh(ctx context.Context, hc *http.Client, rt auth.Token) (oauth.TokenSet, error)
Refresh refreshes with the provider, or fails for one that cannot.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package oauthpopup runs a provider sign-in in a popup and hands the new session to the page that opened it, better-auth's oauth-popup plugin.
|
Package oauthpopup runs a provider sign-in in a popup and hands the new session to the page that opened it, better-auth's oauth-popup plugin. |