Help us shape the future of Go! Take the 2026 Go Developer Survey

upstream

package
v2.6.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 6, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package upstream provides connectors for authenticating users with upstream OAuth2/OIDC providers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ClassifyError

func ClassifyError(operation string, err error) error

ClassifyError converts OAuth and transport errors into the connector contract.

func ClassifyHTTPStatus

func ClassifyHTTPStatus(operation string, status int, retryAfter string) error

ClassifyHTTPStatus classifies a provider HTTP status and optional Retry-After value.

Types

type Connector

type Connector interface {
	AuthCodeURL(state string, opts ...oauth2.AuthCodeOption) string
	Exchange(ctx context.Context, code string) (*Credential, error)
	Refresh(ctx context.Context, credential *Credential) (*Credential, error)
	GetIdentity(ctx context.Context, token *oauth2.Token) (Identity, error)
}

Connector is the interface for upstream OAuth2/OIDC providers. It handles the OAuth2 flow, credential renewal, and identity retrieval.

func NewConnector

func NewConnector(cfg config.ConnectorConfig, redirectURL, clientID, clientSecret string) (Connector, error)

NewConnector creates a new upstream connector based on the configuration. Supported types are "google", "github", and "generic". The redirect URL is automatically constructed as {issuerURL}/callback/{type}.

type ConnectorError

type ConnectorError struct {
	Kind       ErrorKind
	RetryAfter string
	Operation  string
}

ConnectorError is a sanitized, typed provider failure.

func (*ConnectorError) Error

func (e *ConnectorError) Error() string

Error returns a body- and credential-free provider error.

type Credential

type Credential struct {
	AccessToken       string    `json:"access_token"`
	TokenType         string    `json:"token_type,omitempty"`
	RefreshToken      string    `json:"refresh_token,omitempty"`
	AccessExpiry      time.Time `json:"access_expiry,omitempty"`
	RefreshExpiry     time.Time `json:"refresh_expiry,omitempty"`
	AccessNonExpiring bool      `json:"access_non_expiring,omitempty"`
}

Credential is the normalized, persistable upstream OAuth credential.

func NormalizeCredential

func NormalizeCredential(token *oauth2.Token, now time.Time, accessNonExpiring bool) *Credential

NormalizeCredential captures known expiry metadata before oauth2 token extras are lost.

func (*Credential) OAuthToken

func (c *Credential) OAuthToken() *oauth2.Token

OAuthToken creates the runtime oauth2 token without relying on raw extras.

type Email

type Email struct {
	Address  string
	Verified bool
	Primary  bool
}

Email is an email assertion returned by an upstream provider.

type ErrorKind

type ErrorKind string

ErrorKind classifies a provider failure without exposing response bodies or credentials.

const (
	ErrorUnauthorized  ErrorKind = "unauthorized"
	ErrorNoRotation    ErrorKind = "definitive_no_rotation"
	ErrorConfiguration ErrorKind = "configuration"
	ErrorTerminal      ErrorKind = "terminal"
	ErrorRateLimit     ErrorKind = "rate_limit"
	ErrorTemporary     ErrorKind = "temporary"
)

func ErrorInfo

func ErrorInfo(err error) (ErrorKind, string)

ErrorInfo returns a connector error's classification.

type GenericConnector

type GenericConnector struct {
	// contains filtered or unexported fields
}

GenericConnector implements OAuth2 authentication with generic OAuth2/OIDC providers.

func NewGenericConnector

func NewGenericConnector(cfg config.ConnectorConfig, redirectURL, clientID, clientSecret string) *GenericConnector

NewGenericConnector creates a new generic OAuth2 connector with the provided configuration.

func (*GenericConnector) AuthCodeURL

func (c *GenericConnector) AuthCodeURL(state string, opts ...oauth2.AuthCodeOption) string

AuthCodeURL returns the URL to redirect users to for OAuth2 authentication.

func (*GenericConnector) Exchange

func (c *GenericConnector) Exchange(ctx context.Context, code string) (*Credential, error)

Exchange exchanges an authorization code for an access token.

func (*GenericConnector) GetIdentity

func (c *GenericConnector) GetIdentity(ctx context.Context, token *oauth2.Token) (Identity, error)

GetIdentity retrieves the stable subject and email assertions from the userinfo endpoint.

func (*GenericConnector) Refresh

func (c *GenericConnector) Refresh(ctx context.Context, credential *Credential) (*Credential, error)

Refresh renews a generic OAuth credential and preserves an omitted refresh token.

type GitHubConnector

type GitHubConnector struct {
	// contains filtered or unexported fields
}

GitHubConnector implements OAuth2 authentication with GitHub.

func NewGitHubConnector

func NewGitHubConnector(cfg config.ConnectorConfig, redirectURL, clientID, clientSecret string) *GitHubConnector

NewGitHubConnector creates a new GitHub OAuth2 connector with the provided configuration. It supports both github.com and GitHub Enterprise instances.

func (*GitHubConnector) AuthCodeURL

func (c *GitHubConnector) AuthCodeURL(state string, opts ...oauth2.AuthCodeOption) string

AuthCodeURL returns the URL to redirect users to for GitHub OAuth2 authentication.

func (*GitHubConnector) Exchange

func (c *GitHubConnector) Exchange(ctx context.Context, code string) (*Credential, error)

Exchange exchanges an authorization code for an access token from GitHub.

func (*GitHubConnector) GetIdentity

func (c *GitHubConnector) GetIdentity(ctx context.Context, token *oauth2.Token) (Identity, error)

GetIdentity retrieves the stable user ID and every email assertion from GitHub.

func (*GitHubConnector) Refresh

func (c *GitHubConnector) Refresh(ctx context.Context, credential *Credential) (*Credential, error)

Refresh renews a GitHub OAuth credential when GitHub supplied a refresh token.

type GoogleConnector

type GoogleConnector struct {
	// contains filtered or unexported fields
}

GoogleConnector implements OAuth2 authentication with Google.

func NewGoogleConnector

func NewGoogleConnector(cfg config.ConnectorConfig, redirectURL, clientID, clientSecret string) *GoogleConnector

NewGoogleConnector creates a new Google OAuth2 connector with the provided configuration.

func (*GoogleConnector) AuthCodeURL

func (c *GoogleConnector) AuthCodeURL(state string, opts ...oauth2.AuthCodeOption) string

AuthCodeURL returns the URL to redirect users to for Google OAuth2 authentication. If a hosted domain is configured, it adds the hd parameter to restrict authentication.

func (*GoogleConnector) Exchange

func (c *GoogleConnector) Exchange(ctx context.Context, code string) (*Credential, error)

Exchange exchanges an authorization code for an access token from Google.

func (*GoogleConnector) GetIdentity

func (c *GoogleConnector) GetIdentity(ctx context.Context, token *oauth2.Token) (Identity, error)

GetIdentity retrieves the stable subject and email assertions from Google's userinfo endpoint.

func (*GoogleConnector) Refresh

func (c *GoogleConnector) Refresh(ctx context.Context, credential *Credential) (*Credential, error)

Refresh renews a Google OAuth credential and preserves an omitted refresh token.

type Identity

type Identity struct {
	Subject string
	Emails  []Email
}

Identity is a stable upstream subject and all of its email assertions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL