High-level OAuth 2.0 powered by Deno KV.

Deno KV OAuth (Beta)

Features

Uses Deno KV for persistent session storage.
Uses oauth2_client for OAuth workflows.
Automatically handles the authorization code flow with Proof Key for Code Exchange (PKCE) and client redirection.
Provides pre-defined OAuth configurations for popular providers.
Works locally and in the cloud, including Deno Deploy.
Based on the Web API’s Request and Response interfaces.
Works with Fresh, Deno.serve() and Oak and other web frameworks.

Documentation

Check out the full documentation and API reference here.

How-to

Get Started with Fresh

The minimum required version for plugins in Fresh is 1.3.0 If you’re not performing anything special in the sign-in, sign-out and callback handlers, you can add the Fresh plugin to your project. This automatically handles GET /oauth/signin, GET /oauth/callback and GET /oauth/signout routes.

Create your OAuth 2.0 application for your given provider.

Create your pre-defined or custom OAuth configuration and configure Fresh to use the plugin.

// main.ts
import { start } from "$fresh/server.ts";
import {
  createGithubOAuthConfig,
  kvOAuthPlugin,
} from "https://deno.land/x/deno_kv_oauth@$VERSION/mod.ts";
import manifest from "./fresh.gen.ts";

await start(manifest, {
  plugins: [
    kvOAuthPlugin(createGithubOAuthConfig()),
  ],
});

Start your server with the necessary environment variables.

GITHUB_CLIENT_ID=xxx GITHUB_CLIENT_SECRET=xxx deno run --unstable --allow-env --allow-net server.ts

See the Fresh + Deno KV OAuth demo for an example and Fresh’s plugin documentation for more information on plugins.

Get Started with a Pre-Defined OAuth Configuration

See here for the list of OAuth providers with pre-defined configurations.

Create your OAuth application for your given provider.

Create your web server using Deno KV OAuth’s request handlers, helpers and pre-defined OAuth configuration.

// server.ts
import {
  createGitHubOAuthConfig,
  getSessionId,
  handleCallback,
  signIn,
  signOut,
} from "https://deno.land/x/deno_kv_oauth@$VERSION/mod.ts";

const oauthConfig = createGitHubOAuthConfig();

async function handler(request: Request) {
  const { pathname } = new URL(request.url);
  switch (pathname) {
    case "/oauth/signin":
      return await signIn(request, oauthConfig);
    case "/oauth/callback":
      const { response } = await handleCallback(request, oauthConfig);
      return response;
    case "/oauth/signout":
      return signOut(request);
    case "/protected-route":
      return getSessionId(request) === undefined
        ? new Response("Unauthorized", { status: 401 })
        : new Response("You are allowed");
    default:
      return new Response(null, { status: 404 });
  }
}

Deno.serve(handler);

Start your server with the necessary environment variables.

GITHUB_CLIENT_ID=xxx GITHUB_CLIENT_SECRET=xxx deno run --unstable --allow-env --allow-net server.ts

Check out a full implementation in the demo source code which runs https://kv-oauth.deno.dev.

Get Started with a Custom OAuth Configuration

Create your OAuth application for your given provider.

Create your web server using Deno KV OAuth’s request handlers and helpers, and custom OAuth configuration.

// server.ts
import {
  getRequiredEnv,
  getSessionId,
  handleCallback,
  type OAuth2ClientConfig,
  signIn,
  signOut,
} from "https://deno.land/x/deno_kv_oauth@$VERSION/mod.ts";

const oauthConfig: OAuth2ClientConfig = {
  clientId: getRequiredEnv("CUSTOM_CLIENT_ID"),
  clientSecret: getRequiredEnv("CUSTOM_CLIENT_SECRET"),
  authorizationEndpointUri: "https://custom.com/oauth/authorize",
  tokenUri: "https://custom.com/oauth/token",
  redirectUri: "https://my-site.com/another-dir/callback",
};

async function handler(request: Request) {
  const { pathname } = new URL(request.url);
  switch (pathname) {
    case "/oauth/signin":
      return await signIn(request, oauthConfig);
    case "/another-dir/callback":
      const { response } = await handleCallback(request, oauthConfig);
      return response;
    case "/oauth/signout":
      return signOut(request);
    case "/protected-route":
      return getSessionId(request) === undefined
        ? new Response("Unauthorized", { status: 401 })
        : new Response("You are allowed");
    default:
      return new Response(null, { status: 404 });
  }
}

Deno.serve(handler);

Start your server with the necessary environment variables.

CUSTOM_CLIENT_ID=xxx CUSTOM_CLIENT_SECRET=xxx deno run --unstable --allow-env --allow-net server.ts

Run the Demo Locally

The demo uses GitHub as the OAuth provider. You can change the OAuth configuration by setting the oauthConfig constant as mentioned above.

Create your OAuth application for your given provider.

Start the demo with the necessary environment variables.

TWITTER_CLIENT_ID=xxx TWITTER_CLIENT_SECRET=xxx deno task demo

Concepts

The URL that the client is redirected to upon successful sign-in or sign-out is determined by the request made to the sign-in or sign-out endpoint. This value is set in the following order of precedence:

The value of the success_url URL parameter of the request URL, if defined. E.g. a request to http://example.com/signin?success_url=/success redirects the client to /success after successful sign-in.
The value of the Referer header, if of the same origin as the request. E.g. a request to http://example.com/signin with Referer header http://example.com/about redirects the client to http://example.com/about after successful sign-in.
The root path, “/”. E.g. a request to http://example.com/signin without the Referer header redirects the client to http://example.com after successful sign-in.

Pre-Defined OAuth Configurations

Providers

The following providers have pre-defined OAuth configurations:

Environment Variables

These must be set when starting a server with a pre-defined OAuth configuration. Replace the PROVIDER prefix with your given OAuth provider’s name when starting your server. E.g. DISCORD, GOOGLE, or SLACK.

PROVIDER_CLIENT_ID - Client ID of a given OAuth application.
PROVIDER_CLIENT_SECRET - Client secret of a given OAuth application.
PROVIDER_DOMAIN (optional) - Server domain of a given OAuth application. Only required for Okta and Auth0.

Note: reading environment variables requires the --allow-env[=<VARIABLE_NAME>...] permission flag. See the manual for further details.

Built with Deno KV OAuth

Deno KV OAuth live demo
Deno SaaSKit - A modern SaaS template built on Fresh and uses a custom Deno KV OAuth plugin.
KV SketchBook - Dead simple sketchbook app.
Fresh + Deno KV OAuth demo - A demo of Deno KV OAuth working in the Fresh web framework.
Oak + Deno KV OAuth demo - A demo of Deno KV OAuth working in the Oak web framework.
Ultra + Deno KV OAuth demo - A demo of Deno KV OAuth working in the Ultra web framework.
Hono + Deno KV OAuth demo - A demo of Deno KV OAuth working in the Hono web framework.
Cheetah + Deno KV OAuth demo - A demo of Deno KV OAuth working in the Cheetah web framework.
Paquet - A web app shop

Do you have a project powered by Deno KV OAuth that you’d like to share? Feel free to let us know in a new issue.

Known Issues

Twitch is not supported as an OAuth provider because it does not support PKCE. See #79 and this post for more information.

Deno KV OAuth (Beta)

Features

Documentation

How-to

Get Started with Fresh

Get Started with a Pre-Defined OAuth Configuration

Get Started with a Custom OAuth Configuration

Run the Demo Locally

Concepts

Redirects after Sign-In and Sign-Out

Pre-Defined OAuth Configurations

Providers

Environment Variables

Built with Deno KV OAuth

Known Issues