oauth2

README

oauth2

OAuth2 module of disgo

Getting Started

OAuth2 can be used to authenticate users with Discord on your website. For this to work, you need to create an application on the Discord Developer Portal and get the client ID and secret. Next you need to put in your redirect URL.

Usage

See here for an example.

Documentation

Index

• Variables
• type Client
  • func New(id snowflake.ID, secret string, opts ...ConfigOpt) Client
• type Config
  • func DefaultConfig() *Config
  • func (c *Config) Apply(opts []ConfigOpt)
• type ConfigOpt
  • func WithLogger(logger log.Logger) ConfigOpt
  • func WithOAuth2(oauth2 rest.OAuth2) ConfigOpt
  • func WithRestClient(restClient rest.Client) ConfigOpt
  • func WithRestClientConfigOpts(opts ...rest.ConfigOpt) ConfigOpt
  • func WithSessionController(sessionController SessionController) ConfigOpt
  • func WithStateController(stateController StateController) ConfigOpt
  • func WithStateControllerOpts(opts ...StateControllerConfigOpt) ConfigOpt
• type Session
• type SessionController
  • func NewSessionController() SessionController
  • func NewSessionControllerWithSessions(sessions map[string]Session) SessionController
• type StateController
  • func NewStateController(opts ...StateControllerConfigOpt) StateController
• type StateControllerConfig
  • func DefaultStateControllerConfig() *StateControllerConfig
  • func (c *StateControllerConfig) Apply(opts []StateControllerConfigOpt)
• type StateControllerConfigOpt
  • func WithMaxTTL(maxTTL time.Duration) StateControllerConfigOpt
  • func WithNewStateFunc(newStateFunc func() string) StateControllerConfigOpt
  • func WithStates(states map[string]string) StateControllerConfigOpt

Variables

var (
	// ErrStateNotFound is returned when the state is not found in the SessionController.
	ErrStateNotFound = errors.New("state could not be found")

	// ErrAccessTokenExpired is returned when the access token has expired.
	ErrAccessTokenExpired = errors.New("access token expired. refresh the session")

	// ErrMissingOAuth2Scope is returned when a specific OAuth2 scope is missing.
	ErrMissingOAuth2Scope = func(scope discord.OAuth2Scope) error {
		return fmt.Errorf("missing '%s' scope", scope)
	}
)

Types

type Client

type Client interface {
	// ID returns the configured client ID
	ID() snowflake.ID
	// Secret returns the configured client secret
	Secret() string
	// Rest returns the underlying rest.OAuth2
	Rest() rest.OAuth2

	// SessionController returns the configured SessionController
	SessionController() SessionController
	// StateController returns the configured StateController
	StateController() StateController

	// GenerateAuthorizationURL generates an authorization URL with the given redirect URI, permissions, guildID, disableGuildSelect & scopes. State is automatically generated
	GenerateAuthorizationURL(redirectURI string, permissions discord.Permissions, guildID snowflake.ID, disableGuildSelect bool, scopes ...discord.OAuth2Scope) string
	// GenerateAuthorizationURLState generates an authorization URL with the given redirect URI, permissions, guildID, disableGuildSelect & scopes. State is automatically generated & returned
	GenerateAuthorizationURLState(redirectURI string, permissions discord.Permissions, guildID snowflake.ID, disableGuildSelect bool, scopes ...discord.OAuth2Scope) (string, string)

	// StartSession starts a new Session with the given authorization code & state
	StartSession(code string, state string, identifier string, opts ...rest.RequestOpt) (Session, error)
	// RefreshSession refreshes the given Session with the refresh token
	RefreshSession(identifier string, session Session, opts ...rest.RequestOpt) (Session, error)

	// GetUser returns the discord.OAuth2User associated with the given Session. Fields filled in the struct depend on the Session.Scopes
	GetUser(session Session, opts ...rest.RequestOpt) (*discord.OAuth2User, error)
	// GetMember returns the discord.Member associated with the given Session in a specific guild.
	GetMember(session Session, guildID snowflake.ID, opts ...rest.RequestOpt) (*discord.Member, error)
	// GetGuilds returns the discord.OAuth2Guild(s) the user is a member of. This requires the discord.OAuth2ScopeGuilds scope in the Session
	GetGuilds(session Session, opts ...rest.RequestOpt) ([]discord.OAuth2Guild, error)
	// GetConnections returns the discord.Connection(s) the user has connected. This requires the discord.OAuth2ScopeConnections scope in the Session
	GetConnections(session Session, opts ...rest.RequestOpt) ([]discord.Connection, error)
}

Client is a high level wrapper around Discord's OAuth2 API.

func New

func New(id snowflake.ID, secret string, opts ...ConfigOpt) Client

New returns a new OAuth2 client with the given ID, secret and ConfigOpt(s).

type Config

type Config struct {
	Logger                    log.Logger
	RestClient                rest.Client
	RestClientConfigOpts      []rest.ConfigOpt
	OAuth2                    rest.OAuth2
	SessionController         SessionController
	StateController           StateController
	StateControllerConfigOpts []StateControllerConfigOpt
}

Config is the configuration for the OAuth2 client

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig is the configuration which is used by default

func (*Config) Apply

func (c *Config) Apply(opts []ConfigOpt)

Apply applies the given ConfigOpt(s) to the Config

type ConfigOpt

type ConfigOpt func(config *Config)

ConfigOpt can be used to supply optional parameters to New

func WithLogger

func WithLogger(logger log.Logger) ConfigOpt

WithLogger applies a custom logger to the OAuth2 client

func WithOAuth2

func WithOAuth2(oauth2 rest.OAuth2) ConfigOpt

WithOAuth2 applies a custom rest.OAuth2 to the OAuth2 client

func WithRestClient

func WithRestClient(restClient rest.Client) ConfigOpt

WithRestClient applies a custom rest.Client to the OAuth2 client

func WithRestClientConfigOpts

func WithRestClientConfigOpts(opts ...rest.ConfigOpt) ConfigOpt

WithRestClientConfigOpts applies rest.ConfigOpt for the rest.Client to the OAuth2 client

func WithSessionController

func WithSessionController(sessionController SessionController) ConfigOpt

WithSessionController applies a custom SessionController to the OAuth2 client

func WithStateController

func WithStateController(stateController StateController) ConfigOpt

WithStateController applies a custom StateController to the OAuth2 client

func WithStateControllerOpts

func WithStateControllerOpts(opts ...StateControllerConfigOpt) ConfigOpt

WithStateControllerOpts applies all StateControllerConfigOpt(s) to the StateController

type Session

type Session interface {
	// AccessToken allows requesting user information
	AccessToken() string

	// RefreshToken allows refreshing the AccessToken
	RefreshToken() string

	// Scopes returns the discord.OAuth2Scope(s) of the Session
	Scopes() []discord.OAuth2Scope

	// TokenType returns the discord.TokenType of the AccessToken
	TokenType() discord.TokenType

	// Expiration returns the time.Time when the AccessToken expires and needs to be refreshed
	Expiration() time.Time

	// Webhook returns the discord.IncomingWebhook when the discord.OAuth2ScopeWebhookIncoming is set
	Webhook() *discord.IncomingWebhook
}

Session represents a discord access token response (https://discord.com/developers/docs/topics/oauth2#authorization-code-grant-access-token-response)

type SessionController

type SessionController interface {
	// GetSession returns the Session for the given identifier or nil if none was found
	GetSession(identifier string) Session

	// CreateSession creates a new Session from the given identifier, access token, refresh token, scope, token type, expiration and webhook
	CreateSession(identifier string, accessToken string, refreshToken string, scopes []discord.OAuth2Scope, tokenType discord.TokenType, expiration time.Time, webhook *discord.IncomingWebhook) Session

	// CreateSessionFromResponse creates a new Session from the given identifier and discord.AccessTokenResponse payload
	CreateSessionFromResponse(identifier string, response discord.AccessTokenResponse) Session
}

SessionController lets you manage your Session(s)

func NewSessionController

func NewSessionController() SessionController

NewSessionController returns a new empty SessionController

func NewSessionControllerWithSessions

func NewSessionControllerWithSessions(sessions map[string]Session) SessionController

NewSessionControllerWithSessions returns a new SessionController with the given Session(s)

type StateController

type StateController interface {
	// GenerateNewState generates a new random state to be used as a state.
	GenerateNewState(redirectURI string) string

	// ConsumeState validates a state and returns the redirect url or nil if it is invalid.
	ConsumeState(state string) string
}

StateController is responsible for generating, storing and validating states.

func NewStateController

func NewStateController(opts ...StateControllerConfigOpt) StateController

NewStateController returns a new empty StateController.

type StateControllerConfig

type StateControllerConfig struct {
	States       map[string]string
	NewStateFunc func() string
	MaxTTL       time.Duration
}

StateControllerConfig is the configuration for the StateController

func DefaultStateControllerConfig

func DefaultStateControllerConfig() *StateControllerConfig

DefaultStateControllerConfig is the default configuration for the StateController

func (*StateControllerConfig) Apply

func (c *StateControllerConfig) Apply(opts []StateControllerConfigOpt)

Apply applies the given StateControllerConfigOpt(s) to the StateControllerConfig

type StateControllerConfigOpt

type StateControllerConfigOpt func(config *StateControllerConfig)

StateControllerConfigOpt is used to pass optional parameters to NewStateController

func WithMaxTTL

func WithMaxTTL(maxTTL time.Duration) StateControllerConfigOpt

WithMaxTTL sets the maximum time to live for a state

func WithNewStateFunc

func WithNewStateFunc(newStateFunc func() string) StateControllerConfigOpt

WithNewStateFunc sets the function which is used to generate a new random state

func WithStates

func WithStates(states map[string]string) StateControllerConfigOpt

WithStates loads states from an existing map