Documentation
¶
Overview ¶
Package oauth adds "Sign in with GitHub, Google or any OpenID Connect provider" to a Tern app:
kit.WithPlugins(
sessions.New(secret),
oauth.New(oauth.Options{
Secret: secret,
Providers: []oauth.Provider{
oauth.GitHub(os.Getenv("GITHUB_CLIENT_ID"), os.Getenv("GITHUB_CLIENT_SECRET")),
oauth.Google(os.Getenv("GOOGLE_CLIENT_ID"), os.Getenv("GOOGLE_CLIENT_SECRET")),
},
OnLogin: func(ctx *kit.Ctx, id oauth.Identity) error {
user, err := users.FindOrCreate(ctx, id.Provider, id.Subject, id.Email)
if err != nil {
return err
}
return sessions.Get(ctx).Set("user", user.ID)
},
}),
)
Link to /auth/github/login (optionally with ?next=/somewhere) to sign in. The provider sends the user back to /auth/github/callback, which must be registered as the redirect URL with the provider. The flow uses PKCE, a state parameter and, for OpenID Connect, a nonce, kept in a short-lived encrypted cookie; ID tokens are verified against the provider's keys.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Identity ¶
type Identity struct {
// Provider is the provider's Name, such as "github".
Provider string
// Subject is the user's stable ID at the provider. Use Provider and
// Subject together to find the user; emails can change.
Subject string
Email string
EmailVerified bool
Name string
Username string // GitHub login, or preferred_username
Picture string
// Claims holds the ID token's claims, or the user API's response.
Claims map[string]any
// Token is the provider's token, to call its APIs for the user.
Token *oauth2.Token
}
Identity is who signed in.
type Options ¶
type Options struct {
Providers []*Provider
// Secret encrypts the cookie that carries the flow's state; at least
// 32 bytes. The sessions plugin's secret can be reused.
Secret string
// OnLogin is called after a successful sign-in, to find or create the
// user and sign them in. Returning an error, such as a kit.Redirect or
// kit.Error(403, ...), stops the sign-in; otherwise the user is sent to
// the next URL given to the login link, or "/".
OnLogin func(ctx *kit.Ctx, id Identity) error
// Path is where the plugin's routes are; the default is "/auth".
Path string
// URL is the app's public URL, such as "https://example.com", used to
// build redirect URLs. The default is taken from the request, which is
// right unless the app runs behind a proxy that changes the host.
URL string
// ErrorURL is where users go when a sign-in fails or is canceled, with
// ?error=<code>. The default is "/login".
ErrorURL string
// HTTPClient is used for requests to providers.
HTTPClient *http.Client
}
Options configure the plugin.
type Plugin ¶
type Plugin struct {
// contains filtered or unexported fields
}
Plugin is the oauth plugin.
type Provider ¶
type Provider struct {
// Name is the provider's path segment, as in /auth/<name>/login.
Name string
// Label is a display name, such as "GitHub".
Label string
// Config holds the client ID and secret, endpoints and scopes. The
// redirect URL is set by the plugin.
Config oauth2.Config
// Issuer is the OpenID Connect issuer URL. With it, the endpoints are
// discovered and the ID token is verified.
Issuer string
// UserInfo fetches the identity for providers without OpenID Connect.
UserInfo func(ctx context.Context, client *http.Client, token *oauth2.Token) (Identity, error)
// AuthParams are added to the authorization URL, such as
// prompt=select_account.
AuthParams map[string]string
// contains filtered or unexported fields
}
Provider is an OAuth 2.0 or OpenID Connect provider.
func GitHub ¶
GitHub signs in with a GitHub account. The identity's email is the user's primary verified email, if they have one.
Source Files