Documentation
¶
Overview ¶
Package oauthclient implements the client side of OAuth 2.1 authorization code flows against protected resources: discovery of the resource's authorization server (RFC 9728 and RFC 8414), dynamic client registration (RFC 7591) with a pre-registered fallback, PKCE, resource indicators (RFC 8707), issuer validation (RFC 9207), token refresh with rotation, and revocation (RFC 7009). The admin service uses it to run browser-based flows on behalf of users and to refresh the resulting tokens.
Index ¶
- Variables
- func CallbackPage(connector, errMsg, redirectURL string) string
- func GenerateState() (string, error)
- func GenerateVerifier() string
- func IsReservedAuthorizationParam(key string) bool
- func TokenExpiring(tok *oauth2.Token, obtainedOn time.Time) bool
- type Client
- func (c *Client) AuthCodeURL(state, verifier string) string
- func (c *Client) Exchange(ctx context.Context, code, verifier string, hc *http.Client) (*oauth2.Token, error)
- func (c *Client) Refresh(ctx context.Context, tok *oauth2.Token, hc *http.Client) (*oauth2.Token, error)
- func (c *Client) Revoke(ctx context.Context, tok *oauth2.Token, hc *http.Client) error
- func (c *Client) ValidateIssuer(iss string) error
- type DiscoverOptions
Constants ¶
This section is empty.
Variables ¶
var ErrAuthorizationRequired = errors.New("authorization required")
ErrAuthorizationRequired is returned when a user's authorization is missing or gone for good (for example, a revoked refresh token), so the user must authorize again.
Functions ¶
func CallbackPage ¶
CallbackPage renders the page shown at the end of a browser-based authorization flow. It notifies the window that opened the popup (the chat) and closes itself; if it was not opened as a popup, it offers a link back to redirectURL. errMsg is empty on success.
func GenerateState ¶
GenerateState returns a random, URL-safe state parameter.
func GenerateVerifier ¶
func GenerateVerifier() string
GenerateVerifier returns a random PKCE code verifier.
func IsReservedAuthorizationParam ¶
IsReservedAuthorizationParam reports whether an authorization request parameter is set by the flow itself, and so can't be configured.
func TokenExpiring ¶
TokenExpiring reports whether a token should be refreshed before use: it has an expiry, and that expiry is within the refresh leeway. obtainedOn is when the token was issued or last refreshed. The leeway is maxRefreshLeeway, capped at half the token's lifetime, so short-lived tokens are not refreshed on every use.
Types ¶
type Client ¶
type Client struct {
// ServerURL is the protected resource the client was discovered for.
ServerURL string `json:"server_url"`
// RedirectURL is the redirect URI the client was registered with.
RedirectURL string `json:"redirect_url"`
// Resource is the RFC 8707 resource indicator sent in authorization and token requests.
Resource string `json:"resource"`
Issuer string `json:"issuer"`
// IssParameterSupported is true if the authorization server always sends the RFC 9207 "iss" parameter in authorization responses.
IssParameterSupported bool `json:"iss_parameter_supported,omitempty"`
AuthorizationEndpoint string `json:"authorization_endpoint"`
TokenEndpoint string `json:"token_endpoint"`
RevocationEndpoint string `json:"revocation_endpoint,omitempty"`
ClientID string `json:"client_id"`
ClientSecret string `json:"client_secret,omitempty"`
ClientAuthStyle string `json:"client_auth_style,omitempty"` // "basic", "post" or empty for auto-detect
Scopes []string `json:"scopes,omitempty"`
// AuthorizationParams are extra query parameters for the authorization endpoint, for servers that need non-standard ones
// (e.g. Google's access_type=offline, without which it issues no refresh token).
AuthorizationParams map[string]string `json:"authorization_params,omitempty"`
}
Client is the discovered OAuth configuration for a protected resource together with the client Rill uses with it. It is shared by all users of a connector; tokens are stored separately per user.
func Discover ¶
func Discover(ctx context.Context, opts *DiscoverOptions) (*Client, error)
Discover discovers the authorization server of a protected resource and registers a client with it (or uses the pre-registered one).
func (*Client) AuthCodeURL ¶
AuthCodeURL returns the URL to send the user's browser to.
func (*Client) Exchange ¶
func (c *Client) Exchange(ctx context.Context, code, verifier string, hc *http.Client) (*oauth2.Token, error)
Exchange exchanges an authorization code for a token.
func (*Client) Refresh ¶
func (c *Client) Refresh(ctx context.Context, tok *oauth2.Token, hc *http.Client) (*oauth2.Token, error)
Refresh obtains a new token using the refresh token, sending the resource indicator (RFC 8707). If the server rotates the refresh token, the new one is returned; otherwise the old one is kept.
func (*Client) Revoke ¶
Revoke revokes the token at the authorization server, if it supports revocation. Revoking the refresh token also ends the access tokens of its grant (RFC 7009 section 2.1).
func (*Client) ValidateIssuer ¶
ValidateIssuer checks the "iss" parameter of an authorization response (RFC 9207), which defends against mix-up attacks when Rill talks to several authorization servers through the same redirect URI. It is required when the authorization server advertises support for it; otherwise it is optional, but must match when present.
type DiscoverOptions ¶
type DiscoverOptions struct {
ServerURL string
RedirectURL string
// ClientID and ClientSecret are pre-registered client credentials, used when the authorization server does not support dynamic client registration.
ClientID string
ClientSecret string
// Scopes to request. Defaults to all scopes the server advertises.
Scopes []string
// AuthorizationParams are extra query parameters for the authorization endpoint (see Client.AuthorizationParams).
AuthorizationParams map[string]string
// HTTPClient is used for all requests; see safehttp.NewHTTPClient.
HTTPClient *http.Client
}
DiscoverOptions are the inputs for Discover.
Source Files