litestar-oauth¶

OAuth2 authentication plugin for Litestar.

litestar-oauth provides a clean, type-safe API for integrating OAuth2 providers into your Litestar applications. Features automatic route registration, built-in CSRF protection, and normalized user data across providers.

Getting Started

New to litestar-oauth? Start here for installation and your first OAuth flow.

Getting Started

Provider Guides

Configure OAuth providers: GitHub, Google, Discord, and more.

OAuth Providers

API Reference

Complete API documentation for all public classes and functions.

API Reference

Litestar Plugin

Deep integration with Litestar: routes, dependencies, and guards.

Quickstart

Key Features¶

Async-First Design: Native async/await throughout, built on httpx for HTTP operations
Provider Agnostic: Pre-built providers for GitHub, Google, Discord, and more
Type-Safe: Full typing with Protocol-based interfaces for IDE support and type checking
CSRF Protection: Built-in state management to prevent cross-site request forgery
Litestar Integration: Optional deep integration with Litestar’s DI, guards, and plugin system
Extensible: Easy to add custom providers for any OAuth2-compliant identity provider
Token Management: Automatic token handling with refresh token support
User Info Normalization: Consistent user data format across all providers

Quick Example¶

Here’s a taste of what using litestar-oauth looks like:

from litestar import Litestar
from litestar_oauth.contrib.litestar import OAuthPlugin, OAuthConfig

app = Litestar(
    plugins=[
        OAuthPlugin(
            config=OAuthConfig(
                redirect_base_url="https://example.com",
                github_client_id="your-client-id",
                github_client_secret="your-client-secret",
                google_client_id="your-google-id",
                google_client_secret="your-google-secret",
            )
        )
    ],
)

# Routes automatically registered:
# GET /auth/{provider}/login - Redirect to OAuth provider
# GET /auth/{provider}/callback - Handle OAuth callback

from litestar_oauth import OAuthService
from litestar_oauth.providers import GitHubOAuthProvider

# Configure providers
github = GitHubOAuthProvider(
    client_id="your-client-id",
    client_secret="your-client-secret",
)

# Create service and register provider
oauth_service = OAuthService()
oauth_service.register(github)

# Generate authorization URL
auth_url = await oauth_service.get_authorization_url(
    provider_name="github",
    redirect_uri="https://example.com/callback",
)

# After user authorizes, exchange code for token
provider = oauth_service.get_provider("github")
token = await provider.exchange_code(
    code="authorization-code",
    redirect_uri="https://example.com/callback",
)

# Fetch user information
user_info = await provider.get_user_info(token.access_token)
print(f"Welcome, {user_info.username}!")

Installation¶

uv add litestar-oauth

pip install litestar-oauth

pdm add litestar-oauth

poetry add litestar-oauth

Includes Litestar and httpx by default. For provider-specific extras:

# Apple Sign In (requires JWT signing)
uv add litestar-oauth[apple]

# All provider extras
uv add litestar-oauth[all]

Supported Providers¶

litestar-oauth includes built-in support for popular OAuth providers:

Provider	Class	Default Scopes
GitHub	`GitHubOAuthProvider`	`read:user`, `user:email`
Google	`GoogleOAuthProvider`	`openid`, `email`, `profile`
Discord	`DiscordOAuthProvider`	`identify`, `email`
Microsoft	`MicrosoftOAuthProvider`	`openid`, `email`, `profile`
GitLab	`GitLabOAuthProvider`	`read_user`, `email`
Twitter/X	`TwitterOAuthProvider`	`users.read`, `tweet.read`
Facebook	`FacebookOAuthProvider`	`email`, `public_profile`
LinkedIn	`LinkedInOAuthProvider`	`openid`, `email`, `profile`
Bitbucket	`BitbucketOAuthProvider`	`account`, `email`
Generic	`GenericOAuthProvider`	Configurable

litestar-oauth¶

Key Features¶

Quick Example¶

Installation¶

Supported Providers¶

Indices and tables¶