Documentation
¶
Overview ¶
Package github provides chok's GitHub OAuth 2.0 implementation of account.AuthProvider.
Wire it via chok.yaml — chok bundles this provider through the account/providers/blessed curator, so applications need no Go code:
account:
enabled: true
oauth_callback_frontend_url: "https://app.example.com/auth/finish"
providers:
github:
enabled: true
client_id: "${GITHUB_CLIENT_ID}"
client_secret: "${GITHUB_CLIENT_SECRET}"
redirect_url: "https://app.example.com/auth/github/callback"
enterprise_url: "https://github.company.com" # optional
Protocol note: GitHub does NOT speak OIDC, so unlike the google provider we cannot validate an ID Token. Trust comes from HTTPS endpoint pinning + access-token-bound REST calls. The OAuth state parameter (Module-generated) is the CSRF defense.
GitHub's `/user` endpoint may return an empty email when the user has hidden their primary in privacy settings; we fall back to `/user/emails` to find a primary + verified address. Without the `user:email` scope (default) /user/emails returns 404, so requests MUST keep that scope present.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Factory ¶
func Factory(rawCfg any) (account.AuthProvider, error)
Factory is the account.ProviderFactory implementation registered for "github". chok's parts.DefaultAccountBuilder / account.RegisterConfiguredProviders look it up via account.LookupProviderFactory("github") and invoke it with the per-provider yaml block.
Types ¶
type Options ¶
type Options struct {
// Enabled mirrors the kill switch in yaml. When false the factory
// short-circuits before validating client_id/secret, so an
// operator can keep `enabled: false` as a staging stanza.
Enabled bool `mapstructure:"enabled"`
// ClientID and ClientSecret come from a GitHub OAuth App
// (Settings → Developer settings → OAuth Apps). Required when
// Enabled is true. ClientSecret is masked by chok.config.Redact /
// AccountOptions.GoString through the `*secret*` heuristic.
ClientID string `mapstructure:"client_id"`
ClientSecret string `mapstructure:"client_secret"`
// RedirectURL must match a callback URL registered against the
// GitHub OAuth App byte-for-byte (scheme + host + path).
RedirectURL string `mapstructure:"redirect_url"`
// Scopes overrides the default set ("read:user", "user:email").
// `user:email` is required for the email-fallback path against
// /user/emails when /user.email is hidden. Removing it without
// understanding the email-flow consequence breaks /login on any
// account that has hidden its email — be very deliberate.
Scopes []string `mapstructure:"scopes"`
// EnterpriseURL points to a self-hosted GitHub Enterprise Server
// install (e.g. "https://github.company.com"). When set, all
// auth/token endpoints AND REST API calls are rooted there
// instead of github.com / api.github.com. Empty = github.com.
EnterpriseURL string `mapstructure:"enterprise_url"`
}
Options is the typed config decoded from chok.yaml's account.providers.github block.