--- name: goth-fundamentals description: This skill should be used when the user asks to "set up goth", "install goth", "oauth in go", "authentication in golang", "goth package", "goth basics", or mentions "github.com/markbates/goth". Provides foundational guidance for the Goth multi-provider authentication library. keywords: [goth, oauth2, authentication, multi-provider, go] disable-model-invocation: false user-invocable: true --- # Goth Fundamentals Expert guidance for github.com/markbates/goth - a Go library providing simple, clean, idiomatic multi-provider OAuth authentication. ## Installation Install the package: ```bash go get github.com/markbates/goth ``` Import in code: ```go 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: ```go 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: ```go type Session interface { GetAuthURL() (string, error) Authorize(Provider, Params) (string, error) Marshal() string } ``` ### User Struct Authenticated user data returned after successful OAuth: ```go 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 ```go // 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: ```go // Query parameter: /auth?provider=google // Path segment: /auth/google ``` Override the provider getter if needed: ```go 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: ```go 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 ```go 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: ```go 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: ```bash # .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: ```go 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: ```go 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: ```go 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: ```go 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](https://github.com/markbates/goth) - [Go Package Documentation](https://pkg.go.dev/github.com/markbates/goth)