Documentation
¶
Overview ¶
Package oauth implements optional authorization-code sign-in for already linked external identities. Linking and provisioning are separate policies.
Index ¶
- Constants
- func Contract() plugin.Definition
- func PruneExpired(ctx context.Context, store storage.Store, before time.Time, limit int) (int64, error)
- type Account
- type Callback
- type Completed
- type Config
- type Plugin
- func (p *Plugin) Accounts(ctx context.Context) ([]Account, error)
- func (p *Plugin) Bind(a *sigil.Auth) error
- func (p *Plugin) Complete(ctx context.Context, ip netip.Addr, c Callback) (Completed, error)
- func (p *Plugin) CompleteLink(ctx context.Context, ip netip.Addr, c Callback) (string, error)
- func (p *Plugin) Definition() plugin.Definition
- func (p *Plugin) Start(ctx context.Context, ip netip.Addr, providerID, returnURL string) (Started, error)
- func (p *Plugin) StartLink(ctx context.Context, ip netip.Addr, providerID, returnURL string) (Started, error)
- func (p *Plugin) Unlink(ctx context.Context, accountID string) error
- type Provider
- type Started
Constants ¶
const CompleteOperation plugin.Operation = "oauth.complete"
CompleteOperation names the audit event recorded when a callback is rejected. Successful completion is recorded by core as plugin.SessionIssue or AccountLink.
const ID = "oauth"
const Lifetime = 5 * time.Minute
Variables ¶
This section is empty.
Functions ¶
func Contract ¶
func Contract() plugin.Definition
Contract returns the plugin's declarative API description for side-effect free export through sigil.Describe (for example by the sigil CLI). It is not a runnable registration: its handlers have no bound Auth and fail closed.
func PruneExpired ¶
func PruneExpired(ctx context.Context, store storage.Store, before time.Time, limit int) (int64, error)
PruneExpired deletes at most limit (1..1000) authorization transactions whose expiry, clamped to database time, is at or before cutoff, and returns the count. Expired transactions are never redeemable, so nothing usable is removed. It needs only the store: persisted ledger ownership survives disablement, so the table stays bounded while the plugin is disabled. A store where the plugin was never installed is ErrUnsupported. Transactions carry no user reference; a deleted user's pending link transaction expires here and cannot complete meanwhile because its session is gone.
Types ¶
type Account ¶
type Account struct {
ID string `json:"id"`
Namespace string `json:"namespace"`
Subject string `json:"subject"`
}
Account is a credential-free owned external identity view.
type Callback ¶
type Callback struct {
Provider, RedirectURL, Issuer string
State, BrowserBinding, Code sigil.Secret
Error string
}
Callback contains the original provider response. RedirectURL is the fixed callback URL, never derived from forwarded headers. Error denotes denial.
type Completed ¶
type Completed struct {
Session sigil.IssuedSession
ReturnURL string
}
type Config ¶
type Config struct {
Store storage.Store
Protector sigil.Protector
Providers []Provider
ReturnURLs []string // Exact HTTPS destinations, without query or fragment.
HTTPClient *http.Client
}
Config resources belong to the Auth passed to Bind. HTTPClient is copied; its transport must honor contexts and must not log credentials. The engine imposes a timeout and rejects redirects on all server-to-provider requests.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
func (*Plugin) Accounts ¶
Accounts lists the current actor's links. Recent authentication is required.
func (*Plugin) CompleteLink ¶
CompleteLink consumes provider proof and links to the initiating session's owner. It never signs in, switches users, merges accounts or refreshes recency.
func (*Plugin) Definition ¶
func (p *Plugin) Definition() plugin.Definition
func (*Plugin) StartLink ¶
func (p *Plugin) StartLink(ctx context.Context, ip netip.Addr, providerID, returnURL string) (Started, error)
StartLink binds explicit provider authorization to the current recent session. No email claim authorizes linking, including a provider-verified email.
func (*Plugin) Unlink ¶
Unlink removes an owned record by its non-bearer ID. Under one owner lock it checks remaining configured login methods, deletes the exact revision and invalidates all sessions/challenges. A password counts only for verified email; disabled providers and optional magic-link delivery do not count as fallback.
type Provider ¶
type Provider struct {
ID, Namespace, ClientID, AuthorizationURL, TokenURL, RedirectURL string
ClientSecret sigil.Secret
Scopes []string
PKCE bool
Issuer, JWKSURL string // Both set for OIDC; only RS256 is enabled.
OAuthIdentity func(context.Context, *http.Client, sigil.Secret) (string, error)
}
Provider is trusted host configuration. Namespace is immutable and includes the exact issuer for OIDC. OAuthIdentity must use the provider's authenticated identity API; never infer identity from an email or an unverified JWT. Access tokens are transient and must not be retained by OAuthIdentity.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package github configures GitHub OAuth 2.0 sign-in for the oauth plugin.
|
Package github configures GitHub OAuth 2.0 sign-in for the oauth plugin. |
|
Package google configures Google OpenID Connect sign-in for the oauth plugin.
|
Package google configures Google OpenID Connect sign-in for the oauth plugin. |
|
internal
|
|
|
providertest
Package providertest is the PostgreSQL fixture shared by the provider adapter integration tests.
|
Package providertest is the PostgreSQL fixture shared by the provider adapter integration tests. |