auth

Documentation

Overview

Package auth defines the authentication layer of the application.

Index

• Constants
• func GenerateProviders(ctx context.Context, config Config, redirectURL string) (pp map[string]Provider, err error)
• func GetClaimsFromRequest(r *http.Request) (claims jwt.Claims, ok bool)
• type Auth
  • func (a *Auth) CallBack() http.HandlerFunc
  • func (a *Auth) Login() http.HandlerFunc
  • func (a *Auth) Logout() http.HandlerFunc
  • func (a *Auth) Middleware(next http.Handler) http.Handler
• type Config
• type GitHubProvider
  • func (p *GitHubProvider) DisplayName() string
  • func (p *GitHubProvider) GetIdentity(ctx context.Context, token *oauth2.Token) (userID string, userName string, err error)
• type OIDCClaims
• type OIDCProvider
  • func (p *OIDCProvider) DisplayName() string
  • func (p *OIDCProvider) GetIdentity(ctx context.Context, token *oauth2.Token) (userID string, userName string, err error)
• type Provider
• type ProviderConfig
• type ProviderType

Constants

const (
	// TokenCookieKey is the key of the cookie stored in the context.
	TokenCookieKey = "session_token"
)

Functions

func GenerateProviders

func GenerateProviders(
	ctx context.Context,
	config Config,
	redirectURL string,
) (pp map[string]Provider, err error)

GenerateProviders generates a map of provider based on the given configuration.

func GetClaimsFromRequest

func GetClaimsFromRequest(r *http.Request) (claims jwt.Claims, ok bool)

GetClaimsFromRequest is a helper function to fetch the JWT session token from an HTTP request.

Types

type Auth

type Auth struct {
	JWTSecret jwt.Secret
	Providers map[string]Provider
}

Auth is a service that provides HTTP handlers and middlewares used for authentication.

func (*Auth) CallBack

func (a *Auth) CallBack() http.HandlerFunc

CallBack is the handler called after login.

It:

1. Fetches the accessToken 2. Fetches some user info and wrap them in a JWT token 3. Store the JWT token in a cookie for the browser.

func (*Auth) Login

func (a *Auth) Login() http.HandlerFunc

Login is the handler that redirect to the authentication page of the OAuth Provider.

func (*Auth) Logout

func (a *Auth) Logout() http.HandlerFunc

Logout removes session cookies and redirect to home.

func (*Auth) Middleware

func (a *Auth) Middleware(next http.Handler) http.Handler

Middleware is an authentication guard for HTTP servers.

type Config

type Config struct {
	Providers     []ProviderConfig `yaml:"providers"`
	SelfHostUsers bool             `yaml:"selfHostUsers"`
}

Config is the authentication configuration definition for the application.

type GitHubProvider

type GitHubProvider struct {
	Name string
	*oauth2.Config
}

GitHubProvider is a authentication provider which uses OAuth2 from GitHub and GitHub API as identity provider.

func (*GitHubProvider) DisplayName

func (p *GitHubProvider) DisplayName() string

DisplayName returns the display name of the provider.

func (*GitHubProvider) GetIdentity

func (p *GitHubProvider) GetIdentity(
	ctx context.Context,
	token *oauth2.Token,
) (userID string, userName string, err error)

GetIdentity fetches the identity of the authenticated user from the GitHub API.

It returns <provider>:<user id>.

type OIDCClaims

type OIDCClaims struct {
	jwt.RegisteredClaims
	Name  string `json:"name"`
	Email string `json:"email"`
}

OIDCClaims are the standard fields given by an OIDC provider.

type OIDCProvider

type OIDCProvider struct {
	Name string
	*oauth2.Config

	*oidc.Provider
}

OIDCProvider is a authentication provider which uses OpenID Connect.

func (*OIDCProvider) DisplayName

func (p *OIDCProvider) DisplayName() string

DisplayName returns the public name of the authenticated user.

func (*OIDCProvider) GetIdentity

func (p *OIDCProvider) GetIdentity(
	ctx context.Context,
	token *oauth2.Token,
) (userID string, userName string, err error)

GetIdentity fetches the identity of the authenticated user from the ID token.

It returns <provider>:<user id>.

type Provider

type Provider interface {
	// AuthCodeURL returns the URL of the consent page that asks for permissions.
	AuthCodeURL(state string, opts ...oauth2.AuthCodeOption) string
	// Exchange converts a code into an OAuth2 token.
	Exchange(ctx context.Context, code string, opts ...oauth2.AuthCodeOption) (*oauth2.Token, error)

	// DisplayName is the provider's name that can be displayed publicly.
	DisplayName() string
	GetIdentity(
		ctx context.Context,
		token *oauth2.Token,
	) (userID string, userName string, err error)
}

Provider is the interface that defines the necessary methods of authentication providers.

type ProviderConfig

type ProviderConfig struct {
	Type         ProviderType `yaml:"type"`
	Name         string       `yaml:"name"`
	ClientID     string       `yaml:"clientID"`
	ClientSecret string       `yaml:"clientSecret"`
	Endpoint     string       `yaml:"endpoint"`
}

ProviderConfig is the configuration of one provider to achieve the OAuth2 flow.

type ProviderType

type ProviderType string

ProviderType is a string uses the indentify edge cases in authentication.

const (
	// ProviderGitHub is the type of the authentication provider that uses GitHub OAuth2.
	ProviderGitHub ProviderType = "github"
	// ProviderOIDC is the generic type of authentication provider that uses OIDC.
	ProviderOIDC ProviderType = "oidc"
)