OpenAuth Documentation

OpenAuth is a standards-based, self-hosted authentication provider designed to work across various platforms including web apps, mobile apps, SPAs, APIs, and 3rd party clients.

Key Features

• Universal: Deploy as a standalone service or embed into existing applications; compatible with any framework.
• Self-hosted: Runs on your infrastructure (Node.js, Bun, AWS Lambda, or Cloudflare Workers).
• Standards-based: Implements OAuth 2.0 specifications, allowing any OAuth client to use it for access and refresh tokens.
• Customizable: Includes a themeable UI that can be customized or replaced with your own implementation.

A standard Starlight project follows this directory structure:

• src/content/docs/: Contains .md or .mdx files. Each file is automatically exposed as a route based on its filename.
• src/assets/: Place images here to embed them in Markdown using relative links.
• public/: Place static assets like favicons here.
• astro.config.mjs: The Astro configuration file.
• package.json: Project dependencies and scripts.
• tsconfig.json: TypeScript configuration.

.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   ├── docs/
│   │   └── config.ts
│   └── env.d.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json

To use Cloudflare KV for OpenAuth storage, import CloudflareStorage from @openauthjs/openauth/storage/cloudflare and initialize it with a namespace option. The resulting storage instance can then be passed to the issuer configuration.

import { CloudflareStorage } from "@openauthjs/openauth/storage/cloudflare"

const storage = CloudflareStorage({
  namespace: "my-namespace"
})

export default issuer({
  storage,
  // ...
})

For client-side applications without a backend, use the token flow with pkce: true. Use client.authorize to get a challenge and a URL, then use client.exchange with the verifier (stored during the challenge phase) to obtain tokens.

// 1. Start flow and store challenge
const { challenge, url } = await client.authorize(<redirect-uri>, "code", { pkce: true })
localStorage.setItem("challenge", JSON.stringify(challenge))
location.href = url

// 2. Exchange code using the verifier
const challengeData = JSON.parse(localStorage.getItem("challenge"))
const exchanged = await client.exchange(
  query.get("code"),
  redirect_uri,
  challengeData.verifier,
)

if (exchanged.err) throw new Error("Invalid code")
localStorage.setItem("access_token", exchanged.tokens.access)
localStorage.setItem("refresh_token", exchanged.tokens.refresh)

Subjects define the shape of the data stored in the JWT access token. OpenAuth uses the standard-schema specification, allowing you to use libraries like Valibot or Zod (v3.24.0+).

It is recommended to define subjects in a separate file so they can be shared between the server and the client.

import { object, string } from "valibot"

const subjects = createSubjects({
  user: object({
    userID: string(),
    workspaceID: string(),
  }),
})

The issuer function returns a Hono app. Deployment depends on your runtime:

• Bun/Cloudflare: Use export default app.
• AWS Lambda: Use hono/aws-lambda to wrap the app.
• Node.js: Use @hono/node-server to serve the app.

// Bun or Cloudflare
export default app

// Lambda
import { handle } from "hono/aws-lambda"
export const handler = handle(app)

// Node.js
import { serve } from "@hono/node-server"
serve(app)

Use the XProvider to implement authentication via X.com (formerly Twitter) in your OpenAuth issuer configuration. You must provide a clientID and clientSecret obtained from your X developer application.

import { XProvider } from "@openauthjs/openauth/provider/x"

export default issuer({
  providers: {
    x: XProvider({
      clientID: "1234567890",
      clientSecret: "0987654321"
    })
  }
})

To create a new Astro project using the Starlight template, use the following command:

npm create astro@latest -- --template starlight

For sites with a server component, use the code flow:

1. Authorize: Redirect the user using client.authorize(redirectUri, 'code').
2. Exchange: After redirection, exchange the code query parameter for tokens using client.exchange(code, redirectUri).
3. Verify: Use client.verify(subjects, accessToken) to validate the token. You can optionally pass a refresh token to automatically refresh expired access tokens.

You can optionally backup the in-memory store to a file so that the data is persisted when the issuer restarts. Provide a file path to the persist option.

MemoryStorage({
  persist: "./persist.json"
})