oauth

README

---

title: OAuth Plugin

Provides OAuth 2.0 authentication and claim-based authorization for endpoints.

Type

• Wrapper
• Swaggerer

Description

Implements OAuth 2.0 authentication with support for various providers (Google, GitHub, Auth0, Keycloak, Okta). Validates access tokens and manages method-level access permissions.

Authentication Flow

1. Initial Setup

   • Configure the OAuth plugin with provider credentials
   • Register your application with the OAuth provider
   • Set up redirect URL in both plugin config and provider settings

2. Authorization Flow

   • Client initiates auth by accessing: /oauth/authorize
   • Gateway redirects to provider's consent page
   • After user consent, provider redirects back to gateway's callback URL
   • Gateway exchanges the code for access token
   • Returns token to client for future requests

3. Protected Endpoint Access

   • Client includes token in requests: Authorization: Bearer <token>
   • Gateway validates token with provider
   • If valid and has required scopes, request proceeds
   • If invalid or insufficient scopes, returns 401/403

Configuration

oauth:
  provider: "google"           # OAuth provider (google, github, auth0, keycloak, okta)
  client_id: "xxx"            # OAuth Client ID
  client_secret: "xxx"        # OAuth Client Secret
  redirect_url: "http://localhost:8080/oauth/callback"  # OAuth callback URL
  auth_url: "/oauth/authorize" # Gateway's authorization endpoint (optional)
  callback_url: "/oauth/callback" # Gateway's callback endpoint (optional)
  scopes:                     # Required access scopes
    - "profile"
    - "email"
  token_header: "Authorization" # Header name for the token (default: "Authorization")
  user_info_url: ""          # User info endpoint URL (required for Auth0)
  introspection_url: ""      # Token introspection endpoint (required for Keycloak/Okta)
  authorization_rules:
    # Public access to health check methods
    - methods: ["GetHealth", "GetVersion"]
      allow_public: true

    # Only administrators can manage users
    - methods: ["CreateUser", "DeleteUser", "UpdateUser"]
      require_all_claims: true
      claim_rules:
        - claim: "roles"
          operation: "contains"
          value: "admin"
        - claim: "org.type"
          operation: "eq"
          value: "internal"

    # API access only for verified users
    - methods: ["GetUserProfile"]
      claim_rules:
        - claim: "email_verified"
          operation: "eq"
          value: "true"

    # Access only for specific organization
    - methods: ["GetOrganizationData", "UpdateOrganizationData"]
      require_all_claims: true
      claim_rules:
        - claim: "org.id"
          operation: "eq"
          value: "{{.OrganizationID}}"  # Support for request parameters
        - claim: "org.status"
          operation: "eq"
          value: "active"

    # Regular expression check
    - methods: ["GetDepartmentData"]
      claim_rules:
        - claim: "department"
          operation: "regex"
          value: "^(HR|Finance|IT)$"

Built-in Endpoints

The plugin automatically adds these endpoints to your gateway:

1. Authorization Endpoint

GET /oauth/authorize

Initiates the OAuth flow by redirecting to the provider's consent page.

2. Callback Endpoint

GET /oauth/callback

Handles the OAuth provider's redirect callback:

• Exchanges authorization code for access token
• Returns token to client
• Optionally redirects to specified URL with token

Provider-Specific Configuration

Google

oauth:
  provider: "google"
  client_id: "xxx.apps.googleusercontent.com"
  client_secret: "xxx"
  scopes:
    - "https://www.googleapis.com/auth/userinfo.profile"
    - "https://www.googleapis.com/auth/userinfo.email"

GitHub

oauth:
  provider: "github"
  client_id: "xxx"
  client_secret: "xxx"
  scopes:
    - "read:user"
    - "user:email"

Auth0

oauth:
  provider: "auth0"
  client_id: "xxx"
  client_secret: "xxx"
  user_info_url: "https://your-tenant.auth0.com/userinfo"
  scopes:
    - "openid"
    - "profile"
    - "email"

Keycloak

oauth:
  provider: "keycloak"
  client_id: "xxx"
  client_secret: "xxx"
  introspection_url: "https://your-keycloak/auth/realms/your-realm/protocol/openid-connect/token/introspect"
  scopes:
    - "openid"
    - "profile"

Okta

oauth:
  provider: "okta"
  client_id: "xxx"
  client_secret: "xxx"
  introspection_url: "https://your-org.okta.com/oauth2/v1/introspect"
  scopes:
    - "openid"
    - "profile"

Security Considerations

1. Always use HTTPS in production
2. Keep client_secret secure
3. Validate redirect_urls to prevent open redirect vulnerabilities
4. Implement state parameter to prevent CSRF attacks (implemented by default)
5. Validate tokens on every request
6. Use appropriate scopes - principle of least privilege
7. Configure proper CORS settings when using as API gateway
8. Regularly rotate client secrets
9. Monitor and log authentication attempts

Authorization Rules

The plugin supports flexible claim-based authorization rules that can be applied to specific methods or groups of methods.

Rule Configuration

oauth:
  # ... other oauth config ...
  authorization_rules:
    # Public access to health check methods
    - methods: ["GetHealth", "GetVersion"]
      allow_public: true

    # Only administrators can manage users
    - methods: ["CreateUser", "DeleteUser", "UpdateUser"]
      require_all_claims: true
      claim_rules:
        - claim: "roles"
          operation: "contains"
          value: "admin"
        - claim: "org.type"
          operation: "eq"
          value: "internal"

    # API access only for verified users
    - methods: ["GetUserProfile"]
      claim_rules:
        - claim: "email_verified"
          operation: "eq"
          value: "true"

    # Access only for specific organization
    - methods: ["GetOrganizationData", "UpdateOrganizationData"]
      require_all_claims: true
      claim_rules:
        - claim: "org.id"
          operation: "eq"
          value: "{{.OrganizationID}}"  # Support for request parameters
        - claim: "org.status"
          operation: "eq"
          value: "active"

    # Regular expression check
    - methods: ["GetDepartmentData"]
      claim_rules:
        - claim: "department"
          operation: "regex"
          value: "^(HR|Finance|IT)$"

Supported Operations

• eq - Exact value match
• ne - Value is not equal
• contains - Array contains value
• regex - Value matches regular expression
• exists - Check if claim exists

Claim Path Syntax

Supports access to nested fields using dot notation and array indices:

• email - simple field
• org.name - nested field
• groups[0] - array element
• org.departments[0].name - combination of nesting

Dynamic Values

Request parameters are supported in rule values using Go template syntax:

• {{.ParamName}} - value from request parameters
• {{.Method}} - method name
• {{.Path}} - request path

Examples

1. Basic Role-Based Authorization:

authorization_rules:
  - methods: ["CreateUser", "DeleteUser"]
    claim_rules:
      - claim: "roles"
        operation: "contains"
        value: "admin"

1. Organization Membership Check:

authorization_rules:
  - methods: ["GetOrganizationData"]
    require_all_claims: true
    claim_rules:
      - claim: "org.id"
        operation: "eq"
        value: "{{.OrganizationID}}"
      - claim: "org.status"
        operation: "eq"
        value: "active"

1. Email Domain Check:

authorization_rules:
  - methods: ["InternalAPI"]
    claim_rules:
      - claim: "email"
        operation: "regex"
        value: "@company\\.com$"

1. Public Methods:

authorization_rules:
  - methods: ["GetPublicData", "Health"]
    allow_public: true

Configuration Examples

1. Public API with Location-Restricted Events

This example demonstrates how to configure a public API where all methods are accessible to everyone, except for specific methods that require users to be located in Berlin. This can be useful for local community events, regional features, or location-specific content.

oauth:
  provider: "github"
  client_id: "xxx"
  client_secret: "xxx"
  redirect_url: "http://localhost:8080/oauth/callback"
  scopes:
    - "read:user"
    - "user:email"
  authorization_rules:
    # Default rule - make all methods public
    - methods: ["*"]
      allow_public: true

    # Override for Berlin-only community events
    - methods: 
        - "RegisterForBerlinCommunityEvent"
        - "GetBerlinEventDetails"
        - "UpdateBerlinEventRegistration"
      require_all_claims: true
      claim_rules:
        - claim: "location"
          operation: "eq"
          value: "Berlin"

    # Optional: Additional rules can be added for specific methods
    - methods: ["UpdateUserProfile"]
      claim_rules:
        - claim: "type"
          operation: "eq"
          value: "User"

Documentation

Index

• type AuthResponse
• type AuthorizationRule
• type ClaimRule
• type Config
  • func (c Config) Doc() string
  • func (c Config) GetOAuthConfig() *oauth2.Config
  • func (c Config) Tag() string
  • func (c *Config) WithDefaults()
• type Connector
  • func (c *Connector) Query(ctx context.Context, endpoint model.Endpoint, params map[string]any) ([]map[string]any, error)
• type Plugin
  • func (p *Plugin) Doc() string
  • func (p *Plugin) Enrich(swag *huma.OpenAPI) *huma.OpenAPI
  • func (p *Plugin) HandleAuthorize(w http.ResponseWriter, r *http.Request)
  • func (p *Plugin) HandleCallback(w http.ResponseWriter, r *http.Request)
  • func (p *Plugin) RegisterRoutes(mux *http.ServeMux)
  • func (p *Plugin) Wrap(connector connectors.Connector) (connectors.Connector, error)
• type PluginBundle
  • func New(cfg Config) (PluginBundle, error)

Types

type AuthResponse

type AuthResponse struct {
	AccessToken string `json:"access_token"`
	TokenType   string `json:"token_type"`
	ExpiresIn   int    `json:"expires_in,omitempty"`
}

type AuthorizationRule

type AuthorizationRule struct {
	// Methods defines the list of methods to which the rule applies
	Methods []string `yaml:"methods"`

	// AllowPublic allows public access without a token
	AllowPublic bool `yaml:"allow_public"`

	// RequireAllClaims determines if all ClaimRules must be true (AND)
	// If false, one true rule is sufficient (OR)
	RequireAllClaims bool `yaml:"require_all_claims"`

	// ClaimRules list of claim validation rules
	ClaimRules []ClaimRule `yaml:"claim_rules"`
}

AuthorizationRule defines an authorization rule for a method or group of methods

type ClaimRule

type ClaimRule struct {
	// Claim defines the path to the value in JWT or user data (e.g., "email", "groups[0]", "org.name")
	Claim string `yaml:"claim"`

	// Operation defines the comparison operation ("eq", "ne", "contains", "regex", "exists")
	Operation string `yaml:"operation"`

	// Value is the expected value for comparison
	Value string `yaml:"value"`
}

ClaimRule represents a rule for checking a claim value

type Config

type Config struct {
	// Provider specifies the OAuth provider ("google", "github", "auth0", "keycloak", "okta")
	Provider string `yaml:"provider"`

	// ProviderAuthURL specifies oauth2.Endpoint AuthURL if Provider is unknown
	ProviderAuthURL string `yaml:"provider_auth_url"`

	// ProviderTokenURL specifies oauth2.Endpoint TokenURL if Provider is unknown
	ProviderTokenURL string `yaml:"provider_token_url"`

	// ClientID is the OAuth Client ID
	ClientID string `yaml:"client_id"`

	// ClientSecret is the OAuth Client Secret
	ClientSecret string `yaml:"client_secret"`

	// RedirectURL for OAuth flow
	RedirectURL string `yaml:"redirect_url"`

	// Scopes defines required access scopes
	Scopes []string `yaml:"scopes"`

	// TokenHeader defines the header name for the token (default: "Authorization")
	TokenHeader string `yaml:"token_header"`

	// AuthURL is the gateway's authorization endpoint path (default: "/oauth/authorize")
	AuthURL string `yaml:"auth_url"`

	// CallbackURL is the gateway's callback endpoint path (default: "/oauth/callback")
	CallbackURL string `yaml:"callback_url"`

	// UserInfoURL is the endpoint for retrieving user information (required for Auth0)
	UserInfoURL string `yaml:"user_info_url"`

	// IntrospectionURL is the token introspection endpoint (required for Keycloak and Okta)
	IntrospectionURL string `yaml:"introspection_url"`

	// AuthorizationRules defines authorization rules for methods
	AuthorizationRules []AuthorizationRule `yaml:"authorization_rules"`
}

Config represents OAuth plugin configuration

func (Config) Doc

func (c Config) Doc() string

func (Config) GetOAuthConfig

func (c Config) GetOAuthConfig() *oauth2.Config

GetOAuthConfig returns oauth2.Config for the specified provider

func (Config) Tag

func (c Config) Tag() string

func (*Config) WithDefaults

func (c *Config) WithDefaults()

WithDefaults sets default values for the config fields

type Connector

type Connector struct {
	connectors.Connector
	// contains filtered or unexported fields
}

func (*Connector) Query

func (c *Connector) Query(ctx context.Context, endpoint model.Endpoint, params map[string]any) ([]map[string]any, error)

type Plugin

type Plugin struct {
	// contains filtered or unexported fields
}

func (*Plugin) Doc

func (p *Plugin) Doc() string

func (*Plugin) Enrich

func (p *Plugin) Enrich(swag *huma.OpenAPI) *huma.OpenAPI

func (*Plugin) HandleAuthorize

func (p *Plugin) HandleAuthorize(w http.ResponseWriter, r *http.Request)

func (*Plugin) HandleCallback

func (p *Plugin) HandleCallback(w http.ResponseWriter, r *http.Request)

func (*Plugin) RegisterRoutes

func (p *Plugin) RegisterRoutes(mux *http.ServeMux)

func (*Plugin) Wrap

func (p *Plugin) Wrap(connector connectors.Connector) (connectors.Connector, error)

type PluginBundle

type PluginBundle interface {
	plugins.Wrapper
	plugins.Swaggerer
	plugins.HTTPServer
}

func New

func New(cfg Config) (PluginBundle, error)