OAuth2 Plugin

Overview

The OAuth2 plugin for Authula allows you to integrate third-party OAuth2 providers into your authentication flow, enabling users to sign in using their accounts from popular services like Google, GitHub, and Discord.

Features

• Third-Party Authentication — Allow users to authenticate using existing accounts from OAuth2-enabled providers
• Multiple Provider Support — Configure and enable multiple OAuth2 providers simultaneously (Google, GitHub, Discord)
• Automatic Token Management — Handles authorization requests, token exchanges, and user profile retrieval
• Security Best Practices — Built-in support for secure credential management via environment variables

Supported Providers

• Discord — Enable sign-in with Discord accounts
• GitHub — Allow users to authenticate using their GitHub credentials
• Google — Integrate Google OAuth2 for seamless user authentication

Each provider guide includes step-by-step instructions for obtaining credentials, configuring the provider, and testing the integration.

Configuration

Standalone Mode:

[plugins.oauth2]
enabled = true

# SECURITY NOTE: It is recommended to set the 'client_secret' for each provider via their
# respective environment variables as shown in the .env.example file rather than hardcoding it here.
[plugins.oauth2.providers.google]
enabled = true
client_id = "your-client-id"
client_secret = "your-client-secret"
redirect_url = "http://localhost:8080/auth/oauth2/callback/google"
scopes = []

Library Mode:

import (
  oauth2plugin "github.com/Authula/authula/plugins/oauth2"
  oauth2plugintypes "github.com/Authula/authula/plugins/oauth2/types"
)

oauth2plugin.New(oauth2plugintypes.OAuth2PluginConfig{
  Enabled: true,
  Providers: map[string]oauth2plugintypes.ProviderConfig{
    "google": {
      Enabled:      true,
      ClientID:     os.Getenv("GOOGLE_CLIENT_ID"),
      ClientSecret: os.Getenv("GOOGLE_CLIENT_SECRET"),
      RedirectURL:  "https://yourdomain.com/auth/oauth2/callback/google",
    },
  },
})

API Reference

Database Schema

This plugin doesn't create any database tables.

Plugin Capabilities

This plugin doesn't have any hooks and capabilities.

Security Recommendations

• Use Environment Variables for Secrets — Never hardcode client_secret values in your TOML configuration. Use environment variables as shown in the .env.example file.
• Secure Redirect URLs — Ensure redirect URLs use HTTPS in production to prevent token interception.
• Validate Provider Scopes — Only request the minimum scopes necessary for your application to reduce security exposure.

Client Plugin

If you're using the Authula SDK, add the plugin to the SDK like so:

import { createClient } from "authula";
import { OAuth2Plugin } from "authula/plugins";

export const authulaClient = createClient({
  url: "http://localhost:8080/auth",
  plugins: [
    // other plugins...
    new OAuth2Plugin(),
  ],
});