goauth

GoAuth

GoAuth is a comprehensive Go authentication library designed to simplify OAuth 2.0, JWT, and other authentication methods for API services. It provides a unified configuration system for handling multiple authentication types and services, making it easy to create authenticated *http.Client instances from a single JSON configuration file.

Features

• Unified Credentials Management: Single JSON configuration format for multiple authentication types and services
• Multiple Authentication Types: OAuth 2.0, JWT, Basic Auth, GCP Service Account, and custom header/query authentication
• 40+ OAuth 2.0 Providers: Pre-configured endpoints for popular services
• Multiple Grant Types: Authorization Code, Client Credentials, Password, JWT Bearer, SAML2 Bearer, and Refresh Token
• PKCE Support: Proof Key for Code Exchange for enhanced security
• SCIM User Model: Canonical user information retrieval across services using SCIM schema
• CLI Tools: Command-line utilities for token generation and API requests
• Multi-Service OAuth: Support for applications using multiple OAuth providers (e.g., "Login with Google" and "Login with Facebook")

Installation

go get github.com/grokify/goauth

Requirements: Go 1.24+

Supported OAuth 2.0 Providers

GoAuth includes pre-configured OAuth 2.0 endpoints for the following services:

Additional service-specific packages are available for: Auth0, Metabase, Salesforce, SuccessFactors, Visa, SparkPost, and Zendesk.

Authentication Types

GoAuth supports the following authentication types:

OAuth 2.0 Grant Types

• authorization_code - Authorization Code flow
• client_credentials - Client Credentials flow
• password - Resource Owner Password Credentials
• urn:ietf:params:oauth:grant-type:jwt-bearer - JWT Bearer
• urn:ietf:params:oauth:grant-type:saml2-bearer - SAML2 Bearer
• refresh_token - Refresh Token
• account_credentials - Account Credentials (Zoom Server-to-Server)

Configuration

Credentials Set (Multiple Accounts)

GoAuth uses a JSON configuration format that supports multiple credentials:

{
  "credentials": {
    "my-google-app": {
      "service": "google",
      "type": "oauth2",
      "oauth2": {
        "clientID": "your-client-id",
        "clientSecret": "your-client-secret",
        "redirectURL": "https://example.com/callback",
        "scope": ["email", "profile"],
        "grantType": "authorization_code"
      }
    },
    "my-ringcentral-app": {
      "service": "ringcentral",
      "type": "oauth2",
      "oauth2": {
        "clientID": "your-client-id",
        "clientSecret": "your-client-secret",
        "grantType": "password",
        "username": "your-username",
        "password": "your-password"
      }
    },
    "my-api-key": {
      "type": "headerquery",
      "headerquery": {
        "serverURL": "https://api.example.com",
        "header": {
          "X-API-Key": "your-api-key"
        }
      }
    }
  }
}

Credential Types

OAuth 2.0 Credentials

{
  "service": "github",
  "type": "oauth2",
  "oauth2": {
    "serverURL": "https://api.github.com",
    "clientID": "your-client-id",
    "clientSecret": "your-client-secret",
    "redirectURL": "https://example.com/callback",
    "scope": ["repo", "user"],
    "grantType": "authorization_code",
    "pkce": false
  }
}

Basic Auth Credentials

{
  "type": "basic",
  "basic": {
    "username": "your-username",
    "password": "your-password",
    "serverURL": "https://api.example.com",
    "allowInsecure": false
  }
}

JWT Credentials

{
  "type": "jwt",
  "jwt": {
    "issuer": "your-issuer",
    "privateKey": "your-private-key",
    "signingMethod": "HS256"
  }
}

Supported signing methods: ES256, ES384, ES512, HS256, HS384, HS512

Header/Query Credentials

{
  "type": "headerquery",
  "headerquery": {
    "serverURL": "https://api.example.com",
    "header": {
      "Authorization": "Bearer your-token",
      "X-Custom-Header": "value"
    },
    "query": {
      "api_key": "your-api-key"
    }
  }
}

Usage

Creating an HTTP Client

package main

import (
    "context"
    "github.com/grokify/goauth"
)

func main() {
    ctx := context.Background()

    // From credentials file with account key
    client, err := goauth.NewClient(ctx, "credentials.json", "my-google-app")
    if err != nil {
        panic(err)
    }

    // Use client for API requests
    resp, err := client.Get("https://api.example.com/resource")
}

Loading Credentials Set

package main

import (
    "context"
    "github.com/grokify/goauth"
)

func main() {
    ctx := context.Background()

    // Load credentials set from file
    set, err := goauth.ReadFileCredentialsSet("credentials.json", true)
    if err != nil {
        panic(err)
    }

    // Get specific credentials
    creds, err := set.Get("my-google-app")
    if err != nil {
        panic(err)
    }

    // Create client from credentials
    client, err := creds.NewClient(ctx)
    if err != nil {
        panic(err)
    }

    // List all account keys
    accounts := set.Accounts()
}

CLI-based Token Retrieval

For authorization code flow without a web server:

package main

import (
    "context"
    "github.com/grokify/goauth"
)

func main() {
    ctx := context.Background()

    creds, _ := goauth.NewCredentialsFromSetFile("credentials.json", "my-app", false)

    // This will print the authorization URL and prompt for the code
    client, err := creds.NewClientCLI(ctx, "random-state")
    if err != nil {
        panic(err)
    }
}

Canonical User Information (SCIM)

GoAuth provides ClientUtil implementations that satisfy the OAuth2Util interface for retrieving canonical user information:

type OAuth2Util interface {
    SetClient(*http.Client)
    GetSCIMUser() (scim.User, error)
}

Google

import "github.com/grokify/goauth/google"

googleClientUtil := google.NewClientUtil(googleOAuth2HTTPClient)
scimUser, err := googleClientUtil.GetSCIMUser()

Facebook

import "github.com/grokify/goauth/facebook"

fbClientUtil := facebook.NewClientUtil(fbOAuth2HTTPClient)
scimUser, err := fbClientUtil.GetSCIMUser()

RingCentral

import "github.com/grokify/goauth/ringcentral"

rcClientUtil := ringcentral.NewClientUtil(rcOAuth2HTTPClient)
scimUser, err := rcClientUtil.GetSCIMUser()

Also available for: Aha, Zoom, Metabase, Zendesk, and Salesforce.

CLI Tools

GoAuth includes command-line tools for authentication tasks:

goauth

Main token retrieval tool supporting all authentication types:

go run cmd/goauth/main.go --credentials credentials.json --account my-app

goapi

Make authenticated API requests:

go run cmd/goapi/main.go --credentials credentials.json --account my-app --url https://api.example.com/resource

Package Structure

Test Redirect URL

This repo includes a generic test OAuth 2 redirect page for headless (no-UI) applications. Configure your OAuth 2 redirect URI to:

https://grokify.github.io/goauth/oauth2callback/

This page displays the Authorization Code which you can copy and paste into your CLI application.

Example Applications

• Multi-Service OAuth Demo: github.com/grokify/beegoutil - Beego-based demo showing Google and Facebook authentication
• Examples Directory: See examples/ and service-specific cmd/ directories for usage examples

Contributing

Contributions are welcome. Please submit pull requests or create issues for bugs and feature requests.

License

GoAuth is available under the MIT License.