Authway

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

See CHANGELOG.md for the current release. The apps and packages in this repo are versioned independently — the SDK badges below track their actual published versions.

NPM Packages:

GitHub Packages:

Features

• OAuth 2.0 / OIDC - Standards-compliant authentication with PKCE support
• Invitation-only onboarding by default - Every account starts from an invitation unless a tenant opens sign-up
• Magic-link and social sign-in - Passwordless email links and Google/GitHub/Microsoft/Apple, gated by the same sign-up policy
• Native apps - Desktop and command-line clients sign in through the system browser on a loopback port or their own URI scheme
• MFA (TOTP) - Time-based one-time passcodes with encrypted secrets and backup codes
• Account self-service - A signed-in user can delete their own account; sessions and tokens end with it
• Audit logging - Auth, admin and webhook actions recorded per tenant
• Webhooks - Signed deliveries of account, sign-in and client events
• Auto-Discovery - Apps only need the Authway API URL, the 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
• .NET client - Authway.Client for the administration API, typed refusals and webhook verification (clients/csharp)

See CHANGELOG.md for complete release notes, including recent security fixes.

Quick Start

Prerequisites

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

Installation

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

# Install dependencies
pnpm install

# The API reads a .env next to itself; the defaults match compose
cp apps/central/api/.env.example apps/central/api/.env
# Social sign-in is optional — set AUTHWAY_GOOGLE_* (and the GitHub/Microsoft/
# Apple equivalents) to enable a provider

# 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/

# 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 browser application (port 5173) — register its client first, see its README
pnpm --dir samples/react-sdk-sample dev

Access: http://localhost:9004

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

SDK Usage

React

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

function App() {
  return (
    <AuthwayProvider
      config={{
        domain: 'http://localhost:8080',
        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>
  )
}

Vanilla JS/TypeScript

import { AuthwayClient } from '@authway/client'

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

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

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

Documentation

docs/README.md is the documentation hub — setup, SDK reference, feature guides, backend integration, deployment and database. What Authway is for, and where it stops, is in the constitution and the scope.

• Samples - Example applications
  • ASP.NET sample - A server-side application that signs users in and keeps its own session
  • React sample - A browser application that signs users in and calls an API
  • ASP.NET API sample - An API that accepts Authway access tokens

Architecture

┌─────────────────┐
│  Consumer App   │  @authway/react or @authway/client
└────────┬────────┘
         │ GET /.well-known/authway-config
         ▼
┌─────────────────┐         ┌──────────────┐
│  Authway API    │◄────────┤ Ory Hydra    │
│  (port 8080)    │         │ (4444/4445)  │
└─────────┬───────┘         └──────────────┘
          │
          ▼
    ┌───────────┐
    │PostgreSQL │
    └───────────┘

Key Points:

• Apps discover everything from the Authway API (8080)
• The API serves the login screens' backend, the admin API and Authway's own APIs
• Hydra handles the OAuth 2.0 / OIDC protocol
• PostgreSQL stores users, tenants, and configurations

Project Structure

authway/
├── apps/
│   ├── central/api/          # Authway API (Go)
│   ├── central/admin/        # Admin console (React)
│   └── branding/auth-ui/     # Login screens (React)
│
├── clients/
│   └── csharp/               # Authway.Client (.NET) — administration API, webhooks
│
├── packages/
│   ├── client/               # @authway/client (TypeScript)
│   └── react/                # @authway/react
│
├── samples/
│   ├── asp-sample/           # Server-side application (ASP.NET Core)
│   ├── react-sdk-sample/     # Browser application (React)
│   └── asp-api/              # API accepting access tokens (ASP.NET Core)
│
└── docs/                     # Documentation

Development

Build SDKs

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

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

Run Tests

# SDK tests
pnpm test

# Backend tests
go test ./...

# Conformance scenarios against a running stack (see packages/conformance)
pnpm --filter @authway/conformance test

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

License

Apache License 2.0 - see LICENSE file for details.

Links

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