goth-fundamentals

Goth Fundamentals

Expert guidance for github.com/markbates/goth - a Go library providing simple, clean, idiomatic multi-provider OAuth authentication.

Installation

Install the package:

go get github.com/markbates/goth

Import in code:

import (
    "github.com/markbates/goth"
    "github.com/markbates/goth/gothic"
    "github.com/markbates/goth/providers/google"
)

Core Concepts

Provider Interface

Every authentication provider implements the goth.Provider interface:

type Provider interface {
    Name() string
    BeginAuth(state string) (Session, error)
    UnmarshalSession(string) (Session, error)
    FetchUser(Session) (User, error)
    Debug(bool)
    RefreshToken(refreshToken string) (*oauth2.Token, error)
    RefreshTokenAvailable() bool
}

Key methods:

• Name() - Returns provider identifier (e.g., "google", "microsoft")
• BeginAuth() - Initiates OAuth flow, returns session with auth URL
• FetchUser() - Retrieves user data after successful authentication
• RefreshToken() - Obtains new access token using refresh token

Session Interface

Sessions manage OAuth state throughout the authentication flow:

type Session interface {
    GetAuthURL() (string, error)
    Authorize(Provider, Params) (string, error)
    Marshal() string
}

User Struct

Authenticated user data returned after successful OAuth:

type User struct {
    RawData           map[string]interface{}
    Provider          string
    Email             string
    Name              string
    FirstName         string
    LastName          string
    NickName          string
    Description       string
    UserID            string
    AvatarURL         string
    Location          string
    AccessToken       string
    AccessTokenSecret string
    RefreshToken      string
    ExpiresAt         time.Time
    IDToken           string
}

Gothic Helper Package

The gothic package provides convenience functions for common web frameworks:

Key Functions

// Begin authentication - redirects to provider
gothic.BeginAuthHandler(res http.ResponseWriter, req *http.Request)

// Complete authentication - handles callback
gothic.CompleteUserAuth(res http.ResponseWriter, req *http.Request) (goth.User, error)

// Get user from session (if already authenticated)
gothic.GetFromSession(providerName string, req *http.Request) (string, error)

// Logout user
gothic.Logout(res http.ResponseWriter, req *http.Request) error

Provider Selection

Gothic uses the provider query parameter or URL path segment to identify which provider to use:

// Query parameter: /auth?provider=google
// Path segment: /auth/google

Override the provider getter if needed:

gothic.GetProviderName = func(req *http.Request) (string, error) {
    return mux.Vars(req)["provider"], nil
}

Basic Authentication Flow

Step 1: Register Providers

Initialize providers at application startup:

func init() {
    goth.UseProviders(
        google.New(
            os.Getenv("GOOGLE_CLIENT_ID"),
            os.Getenv("GOOGLE_CLIENT_SECRET"),
            "http://localhost:3000/auth/google/callback",
            "email", "profile",
        ),
    )
}

Step 2: Create Auth Routes

func main() {
    http.HandleFunc("/auth/", handleAuth)
    http.HandleFunc("/auth/callback/", handleCallback)
    http.HandleFunc("/logout", handleLogout)
    http.ListenAndServe(":3000", nil)
}

func handleAuth(w http.ResponseWriter, r *http.Request) {
    gothic.BeginAuthHandler(w, r)
}

func handleCallback(w http.ResponseWriter, r *http.Request) {
    user, err := gothic.CompleteUserAuth(w, r)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    // User authenticated - store in session, redirect, etc.
    fmt.Fprintf(w, "Welcome %s!", user.Name)
}

func handleLogout(w http.ResponseWriter, r *http.Request) {
    gothic.Logout(w, r)
    http.Redirect(w, r, "/", http.StatusTemporaryRedirect)
}

Step 3: Configure Session Store

Gothic uses gorilla/sessions by default:

import "github.com/gorilla/sessions"

func init() {
    key := os.Getenv("SESSION_SECRET")
    maxAge := 86400 * 30 // 30 days
    isProd := os.Getenv("ENV") == "production"

    store := sessions.NewCookieStore([]byte(key))
    store.MaxAge(maxAge)
    store.Options.Path = "/"
    store.Options.HttpOnly = true
    store.Options.Secure = isProd

    gothic.Store = store
}

Environment Variables Pattern

Store OAuth credentials securely using environment variables:

# .env (never commit this file)
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
MICROSOFT_CLIENT_ID=your-azure-app-id
MICROSOFT_CLIENT_SECRET=your-azure-secret
SESSION_SECRET=your-32-byte-random-string

Load with godotenv or similar:

import "github.com/joho/godotenv"

func init() {
    godotenv.Load()
}

Supported Providers (70+)

Goth includes providers for major platforms:

Category	Providers
Cloud/Enterprise	Google, Microsoft (Azure AD), Apple, Amazon, Okta, Auth0
Development	GitHub, GitLab, Bitbucket, Gitea
Social	Facebook, Twitter, Instagram, LinkedIn, Discord
Productivity	Slack, Salesforce, Shopify, Zoom
Other	Spotify, Twitch, PayPal, Stripe, Uber

Import provider packages individually:

import (
    "github.com/markbates/goth/providers/google"
    "github.com/markbates/goth/providers/azureadv2"
    "github.com/markbates/goth/providers/github"
)

Error Handling

Handle common authentication errors:

user, err := gothic.CompleteUserAuth(w, r)
if err != nil {
    switch {
    case strings.Contains(err.Error(), "access_denied"):
        // User denied access
        http.Redirect(w, r, "/login?error=denied", http.StatusTemporaryRedirect)
    case strings.Contains(err.Error(), "invalid_grant"):
        // Token expired or revoked
        http.Redirect(w, r, "/login?error=expired", http.StatusTemporaryRedirect)
    default:
        // Log and show generic error
        log.Printf("Auth error: %v", err)
        http.Error(w, "Authentication failed", http.StatusInternalServerError)
    }
    return
}

Token Refresh

For long-lived sessions, refresh tokens before expiry:

func refreshIfNeeded(provider goth.Provider, user *goth.User) error {
    if !provider.RefreshTokenAvailable() {
        return nil
    }

    if time.Until(user.ExpiresAt) > 5*time.Minute {
        return nil // Token still valid
    }

    token, err := provider.RefreshToken(user.RefreshToken)
    if err != nil {
        return err
    }

    user.AccessToken = token.AccessToken
    user.RefreshToken = token.RefreshToken
    user.ExpiresAt = token.Expiry
    return nil
}

Quick Reference

Task	Function/Pattern
Register providers	goth.UseProviders(provider1, provider2)
Start auth flow	gothic.BeginAuthHandler(w, r)
Complete auth	gothic.CompleteUserAuth(w, r)
Logout	gothic.Logout(w, r)
Get current provider	gothic.GetProviderName(r)
Configure session store	gothic.Store = yourStore
Access user data	user.Email, user.Name, user.AccessToken

Related Skills

• goth-providers - Detailed provider configuration (Google, Microsoft)
• goth-echo-security - Echo framework integration and security patterns

References

• Goth GitHub Repository
• Go Package Documentation