OAuth2Plugin Schema

The OAuth2Plugin schema defines the configuration for OAuth2 authentication in Rusty Beam. This plugin enables users to authenticate using OAuth2 providers (Google, GitHub, Azure AD, etc.) and sets the authenticated_user metadata for other plugins to use.

Security Note: All OAuth2 configuration values are read from environment variables for security. The environment variable names must be specified using the clientIdEnv, clientSecretEnv, and redirectUriEnv configuration properties.

Schema Definition

Schema URL: https://rustybeam.net/schema/OAuth2Plugin

Parent Schema: https://rustybeam.net/schema/AuthPlugin

Properties

Inheritance: This schema inherits properties from AuthPlugin (authfile, realm) and Plugin (library, plugin).

Property	Type	Cardinality	Description
redirectUriEnv	https://rustybeam.net/schema/Text	1	Environment variable name to read redirect URI from. Required.
name	https://rustybeam.net/schema/Text	0..1	Plugin instance name for identification. Defaults to "google-oauth2" if not specified.
clientIdEnv	https://rustybeam.net/schema/Text	1	Environment variable name to read client ID from. Required.
clientSecretEnv	https://rustybeam.net/schema/Text	1	Environment variable name to read client secret from. Required.
loginPath	https://rustybeam.net/schema/Text	0..1	The path where login requests will be handled. Defaults to "/auth/{name}/login" where {name} is the plugin instance name.
provider	https://rustybeam.net/schema/Text	0..1	The OAuth2 provider to use (google, github). Defaults to "google" unless the plugin name contains "github".

Configuration Example

<!-- Google OAuth2 configuration -->
<td itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/OAuth2Plugin">
    <span itemprop="library">file://./plugins/librusty_beam_oauth2.so</span>
    <span itemprop="clientIdEnv">GOOGLE_CLIENT_ID</span>
    <span itemprop="clientSecretEnv">GOOGLE_CLIENT_SECRET</span>
    <span itemprop="redirectUriEnv">GOOGLE_OAUTH2_CALLBACK</span>
</td>

<!-- GitHub OAuth2 configuration with explicit provider -->
<td itemprop="plugin" itemscope itemtype="https://rustybeam.net/schema/OAuth2Plugin">
    <span itemprop="library">file://./plugins/librusty_beam_oauth2.so</span>
    <span itemprop="name">github-oauth2</span>
    <span itemprop="clientIdEnv">GITHUB_CLIENT_ID</span>
    <span itemprop="clientSecretEnv">GITHUB_CLIENT_SECRET</span>
    <span itemprop="redirectUriEnv">GITHUB_REDIRECT_URI</span>
    <span itemprop="loginPath">/auth/github/signin</span>
    <span itemprop="provider">github</span>
</td>

Environment Variables

The plugin reads OAuth2 credentials from environment variables. The variable names must be specified in the configuration:

Variable	Required	Description	Example
`Variable specified by clientIdEnv`	Yes	OAuth2 client ID	`123456789.apps.googleusercontent.com`
`Variable specified by clientSecretEnv`	Yes	OAuth2 client secret	`GOCSPX-xxxxxxxxxxxxxxxxxxxx`
`Variable specified by redirectUriEnv`	Yes	OAuth2 redirect/callback URL	`http://localhost:3000/auth/google/callback`

Security: These credentials are sensitive and should be kept secure. Use environment variables or a secrets management system - never commit them to version control.

Setup Requirements

OAuth2 Provider Setup Required:

Register your application with your OAuth2 provider (Google, GitHub, Azure AD, etc.)
Obtain client ID and client secret
Configure redirect URI in provider settings
Set appropriate environment variables as configured

Endpoints

This plugin automatically provides these endpoints:

{loginPath} - Initiates OAuth2 flow (defaults to /auth/{name}/login)
{callback path from redirect URI} - Handles OAuth2 callback (derived from the redirect URI)
/auth/logout - Clears authentication session
/auth/user - Returns current user information as HTML with schema.org/Person microdata

Dynamic Paths: The login path can be configured using the loginPath property. The callback path is automatically derived from the redirect URI specified in the environment variable.

Integration

With Authorization Plugin

Users authenticated via OAuth2 are automatically granted the 'user' role. Administrators can be designated by adding their email to the administrators role in the authorization plugin configuration.

Metadata Set

The plugin sets the following metadata for other plugins to use:

authenticated_user - User's email address
user_name - User's display name

Security Considerations

Security Best Practices:

Use environment variables for credentials - never store them in configuration files
Keep OAuth2 client secrets confidential and never commit to version control
Use HTTPS in production for all OAuth2 URLs
Regularly rotate OAuth2 credentials
Restrict authorized redirect URIs to only necessary domains
Use a .env file for local development (excluded from version control)