Documentation
¶
Overview ¶
Package oauthclient provides an OAuth 2.0 authorization-code client for third-party providers. It is dependency-free.
Index ¶
- func AuthorizationURL(authEndpoint, clientID, redirectURI string, scopes []string, ...) string
- func ExchangeCode(ctx context.Context, c oauth.ClientConfig, code, codeVerifier string) (*oauth.Token, error)
- func ParseGitHubUser(data []byte) (providerID, username, avatarURL string, err error)
- func ParseGitLabUser(data []byte) (providerID, username, avatarURL string, err error)
- func ParseGoogleUser(data []byte) (providerID, username, avatarURL string, err error)
- func RefreshAccessToken(ctx context.Context, c oauth.ClientConfig, refreshToken string) (*oauth.Token, error)
- type PKCEChallenge
- type Provider
- type ProviderConfig
- func NewGitHubConfig(clientID, clientSecret string, redirectURI RedirectURIFunc) *ProviderConfig
- func NewGitLabConfig(clientID, clientSecret, gitlabURL string, redirectURI RedirectURIFunc) *ProviderConfig
- func NewGoogleConfig(clientID, clientSecret string, redirectURI RedirectURIFunc) *ProviderConfig
- func (c *ProviderConfig) AuthURL(r *http.Request, state string) string
- func (c *ProviderConfig) FetchUser(ctx context.Context, accessToken string) (providerID, username, avatarURL string, err error)
- func (c *ProviderConfig) OAuthClientConfig(r *http.Request) oauth.ClientConfig
- func (c *ProviderConfig) RedirectURI(r *http.Request) string
- type RedirectURIFunc
- type RetrieveError
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AuthorizationURL ¶
func AuthorizationURL(authEndpoint, clientID, redirectURI string, scopes []string, state, codeChallenge string, extra url.Values) string
AuthorizationURL returns the provider authorization URL with the state param.
When codeChallenge is non-empty, S256 PKCE parameters are added; when empty, the emitted URL omits them. The extra parameters (e.g. access_type=offline and prompt=consent, which Google requires to issue a refresh token) are merged last and override the core parameters on key conflict; a nil or empty extra yields a URL identical to a flow without it.
func ExchangeCode ¶
func ExchangeCode(ctx context.Context, c oauth.ClientConfig, code, codeVerifier string) (*oauth.Token, error)
ExchangeCode exchanges an authorization code for tokens.
When codeVerifier is non-empty it is sent as the PKCE code_verifier; when empty the request body is identical to a flow without PKCE.
func ParseGitHubUser ¶
ParseGitHubUser parses the GitHub user info response.
func ParseGitLabUser ¶
ParseGitLabUser parses the GitLab user info response.
func ParseGoogleUser ¶
ParseGoogleUser parses the Google OpenID Connect userinfo response.
It uses the immutable "sub" claim as the provider ID and the email as the username. An unverified email is rejected, since the allowlist matches on it.
func RefreshAccessToken ¶
func RefreshAccessToken(ctx context.Context, c oauth.ClientConfig, refreshToken string) (*oauth.Token, error)
RefreshAccessToken exchanges a refresh token for a new access token.
It sends grant_type=refresh_token per RFC 6749 §6 and returns the new token. The returned token may include a new refresh token (rotation) or omit it (meaning the stored refresh token remains valid).
Types ¶
type PKCEChallenge ¶
type PKCEChallenge struct {
Verifier string // the secret code_verifier, kept by the caller for the token exchange
Challenge string // the S256 code_challenge sent on the authorization request
}
PKCEChallenge holds an S256 PKCE verifier and its derived code challenge (RFC 7636).
func NewPKCEChallenge ¶
func NewPKCEChallenge() (PKCEChallenge, error)
NewPKCEChallenge generates a random S256 PKCE verifier and challenge.
PKCE is recommended for all OAuth flows (GitHub supports it since 2025-07, GitLab has supported it for years). Callers that opt in pass the Challenge to AuthorizationURL and the Verifier to ExchangeCode.
type Provider ¶
type Provider interface {
RedirectURI(r *http.Request) string
AuthURL(r *http.Request, state string) string
OAuthClientConfig(r *http.Request) oauth.ClientConfig
}
Provider is the common interface for OAuth provider client configs.
type ProviderConfig ¶
type ProviderConfig struct {
ClientID string
ClientSecret string
RedirectURIFunc RedirectURIFunc
AuthEndpoint string
TokenURL string
UserInfoURL string
Scopes []string
// AuthParams are extra authorization-URL parameters merged into every
// AuthURL call (e.g. access_type=offline for Google offline access). Nil
// for providers that need none.
AuthParams url.Values
ParseUser func(data []byte) (providerID, username, avatarURL string, err error)
}
ProviderConfig is the OAuth client configuration for a provider.
func NewGitHubConfig ¶
func NewGitHubConfig(clientID, clientSecret string, redirectURI RedirectURIFunc) *ProviderConfig
NewGitHubConfig returns a ProviderConfig for github.com with scopes ["repo", "read:user"].
func NewGitLabConfig ¶
func NewGitLabConfig(clientID, clientSecret, gitlabURL string, redirectURI RedirectURIFunc) *ProviderConfig
NewGitLabConfig returns a ProviderConfig for a GitLab instance with scopes ["api", "read_user"]. gitlabURL defaults to "https://gitlab.com".
func NewGoogleConfig ¶
func NewGoogleConfig(clientID, clientSecret string, redirectURI RedirectURIFunc) *ProviderConfig
NewGoogleConfig returns a ProviderConfig for Google Sign-In (OpenID Connect) with scopes ["openid", "email", "profile"].
Google issues a refresh token only when the authorization request carries access_type=offline; prompt=consent forces re-issue on repeat logins. These are set as AuthParams so refresh works through the standard token lifecycle.
func (*ProviderConfig) AuthURL ¶
func (c *ProviderConfig) AuthURL(r *http.Request, state string) string
AuthURL returns the provider's authorization URL with the state param.
func (*ProviderConfig) FetchUser ¶
func (c *ProviderConfig) FetchUser(ctx context.Context, accessToken string) (providerID, username, avatarURL string, err error)
FetchUser fetches the authenticated user from the provider's userinfo endpoint.
func (*ProviderConfig) OAuthClientConfig ¶
func (c *ProviderConfig) OAuthClientConfig(r *http.Request) oauth.ClientConfig
OAuthClientConfig returns the generic OAuth client settings.
func (*ProviderConfig) RedirectURI ¶
func (c *ProviderConfig) RedirectURI(r *http.Request) string
RedirectURI returns the redirect URI for a request.
type RedirectURIFunc ¶
RedirectURIFunc returns the OAuth redirect URI from a request, resolved lazily per call. Mirrors the oauthserver.BaseURLFunc late-binding pattern.
type RetrieveError ¶
type RetrieveError struct {
StatusCode int // HTTP status code from the token endpoint
ErrorCode string // RFC 6749 "error"
ErrorDescription string // RFC 6749 "error_description"
ErrorURI string // RFC 6749 "error_uri"
Body []byte // raw response body for programmatic inspection
}
RetrieveError is returned when the token endpoint responds with a non-2xx status or includes an RFC 6749 error parameter.
func (*RetrieveError) Error ¶
func (e *RetrieveError) Error() string
Error formats the error for logging. It includes StatusCode, ErrorCode, and ErrorDescription but not the raw body.
Source Files