Authway

Modern OAuth 2.0 / OpenID Connect authentication system built on Ory Hydra with JavaScript/TypeScript SDKs.

NPM Packages:

GitHub Packages:

• OAuth 2.0 / OIDC - Standards-compliant authentication with PKCE support
• Auto-Discovery - Apps only need Auth Backend URL, rest is auto-discovered
• Dynamic Claims - Runtime user claims management
• Multi-Tenancy - Fully isolated tenant support
• Popup Login - No-redirect authentication flow with Google OAuth support
• i18n Support - Multi-language UI (Korean, English)
• TypeScript SDKs - @authway/client and @authway/react

• ✅ i18n (Internationalization) - Multi-language support for Auth UI (Korean, English)
• ✅ Language Switcher - User-selectable language with browser detection
• ✅ Auto-executing Popup Callback - @authway/client/popup-callback module for seamless popup flow
• ✅ Enhanced Logout - OIDC logout with post_logout_redirect_uri support
• ✅ Next.js Sample - Complete integration example with @authway/react

See CHANGELOG.md for complete release notes.

• Node.js 18+, pnpm 9+
• Go 1.25+
• Docker (for the backing services)

# Clone repository
git clone https://github.com/iyulab/authway.git
cd authway

# Install dependencies
pnpm install

# Each Go service reads a .env next to itself; the defaults match compose
cp apps/central/api/.env.example apps/central/api/.env
cp apps/branding/auth-api/.env.example apps/branding/auth-api/.env
# Fill in GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET — the Auth Backend requires them

# Start the backing services: Postgres, Redis, MailHog, Hydra
# (Postgres is published on 5433 and Redis on 6380 — the .env files point there)
docker compose up -d

On Windows, .\start-dev.ps1 starts everything below in one step. Otherwise run each in its own shell:

# Central API (port 8080) — applies database migrations on startup
cd apps/central/api && go run ./cmd/

# Auth Backend (port 8081)
cd apps/branding/auth-api && go run ./cmd/

# Login UI (port 3001) — Hydra redirects here for login and consent
cd apps/branding/auth-ui && npm run dev

# Admin console (port 3000)
cd apps/central/admin && npm run dev

# Sample app (port 9004)
cd samples/react-sdk-sample && pnpm dev

Access: http://localhost:9004

The APIs and UIs deliberately run natively rather than in containers — see the comment at the top of docker-compose.yml.

import { AuthwayProvider, useAuth } from '@authway/react'

function App() {
  return (
    <AuthwayProvider
      config={{
        domain: 'http://localhost:8081',
        clientId: 'your-client-id'
      }}
    >
      <Dashboard />
    </AuthwayProvider>
  )
}

function Dashboard() {
  const { isAuthenticated, user, loginWithPopup, logout } = useAuth()

  if (!isAuthenticated) {
    return <button onClick={() => loginWithPopup()}>Login</button>
  }

  return (
    <div>
      <h1>Welcome, {user.name}!</h1>
      <button onClick={() => logout()}>Logout</button>
    </div>
  )
}

import { AuthwayClient } from '@authway/client'

const client = new AuthwayClient({
  domain: 'http://localhost:8081',
  clientId: 'your-client-id'
})

await client.waitForReady()
await client.loginWithPopup()

const token = await client.getAccessToken()
const user = await client.getUser()

• Getting Started Guide - Complete setup and integration guide
• Backend Integration Guide - ASP.NET, Node.js, Go backend integration
• Client Registration - OAuth 2.0 client setup for Public and Confidential clients
• SDK Reference - API documentation for both SDKs
• OAuth Best Practices - Security guidelines and common patterns
• Popup Login Guide - Popup authentication with external OAuth providers
• Samples - Example applications
  • React SDK Sample - Full-featured React demo
  • Next.js Sample - Next.js App Router integration
  • ASP.NET SPA Sample - Backend + Frontend (React & Vanilla JS)

┌─────────────────┐
│  Consumer App   │  @authway/react or @authway/client
└────────┬────────┘
         │ GET /.well-known/authway-config
         ▼
┌─────────────────┐
│  Auth Backend   │  (port 8081) - App entry point
└────────┬────────┘
         │ Proxies to Central API
         ▼
┌─────────────────┐         ┌──────────────┐
│  Central API    │◄────────┤ Ory Hydra    │
│  (port 8080)    │         │ (4444/4445)  │
└─────────┬───────┘         └──────────────┘
          │
          ▼
    ┌───────────┐
    │PostgreSQL │
    └───────────┘

Key Points:

• Apps only connect to Auth Backend (8081)
• Central API (8080) is internal - never exposed directly
• Hydra handles OAuth 2.0 protocol
• PostgreSQL stores users, tenants, and configurations

authway/
├── apps/
│   ├── central/api/          # Core business logic (Go)
│   └── branding/auth-api/    # Auth backend (Go)
│
├── packages/
│   ├── client/               # @authway/client (TypeScript)
│   └── react/                # @authway/react
│
├── samples/
│   ├── react-sdk-sample/     # React demo
│   ├── nextjs-sample/        # Next.js App Router demo
│   └── asp-spa/              # ASP.NET + React/Vanilla JS
│
└── docs/                     # Documentation

# Build client SDK
cd packages/client && pnpm build

# Build React SDK
cd packages/react && pnpm build

# SDK tests
pnpm test

# Backend tests
cd apps/central/api && go test ./...

Contributions welcome! Please read CONTRIBUTING.md first.

MIT License - see LICENSE file for details.

• Documentation: ./docs/
• Issues: GitHub Issues
• Changelog: CHANGELOG.md