OAuth providers

Overview

An OAuth provider is a third-party service that implements the OAuth 2.0 authorization protocol. This integration enables applications to obtain limited access to user accounts on external services without requiring users to share credentials directly with the application.

Aura Auth delegates authentication and authorization to these trusted third parties. The provider manages user authentication, requests consent, and issues tokens, while Aura Auth provides the infrastructure to securely handle these flows within TypeScript applications.

For technical details on the underlying protocol, refer to the OAuth 2.0 Authorization Framework.

What you'll learn

• Implementation Patterns
• Supported Providers
• Advanced Configuration
  • Provider Factories
  • Modular Imports

Implementation Patterns

Aura Auth offers multiple ways to initialize OAuth providers, ranging from zero-configuration setups to highly customized factory functions.

Configuration Methods

Providers can be defined using three distinct patterns within the createAuth instance:

import { createAuth } from "@aura-stack/auth"
import { bitbucket } from "@aura-stack/auth/oauth/bitbucket"
import { builtInOAuthProviders } from "@aura-stack/auth/oauth/index"

export const auth = createAuth({
  oauth: [
    // 1. String Pattern: Automatic environment variable resolution
    "github",

    // 2. Object Pattern: Access via a single built-in collection
    builtInOAuthProviders.gitlab(),

    // 3. Factory Pattern: Direct import for optimal tree-shaking
    bitbucket(),
  ],
})

Supported Providers

The following OAuth providers are currently supported by Aura Auth:

Advanced Configuration

Built-in providers are implemented as lowercase factory functions. This architecture enables developers to override default settings while retaining automatic environment variable loading for sensitive credentials like Client IDs and Secrets.

Provider Factories

The builtInOAuthProviders object provides a centralized collection for all supported services. This approach is recommended when dynamic provider resolution is required.

import { createAuth } from "@aura-stack/auth"
import { builtInOAuthProviders } from "@aura-stack/auth/oauth/index"

export const auth = createAuth({
  oauth: [
    builtInOAuthProviders.github({
      scope: "read:user user:email repo", // Overriding default permissions
    }),
  ],
})

Modular Imports

For production environments where bundle size is critical, importing providers directly from their respective entry points ensures optimal tree-shaking.

import { createAuth } from "@aura-stack/auth"
import { github } from "@aura-stack/auth/oauth/github"

export const auth = createAuth({
  oauth: [
    github({
      scope: "read:user user:email repo",
    }),
  ],
})