Skip to main content

High-level OAuth 2.0 powered by Deno KV.

Works with
It is unknown whether this package works with Bun
It is unknown whether this package works with Cloudflare Workers
It is unknown whether this package works with Node.js
This package works with Deno
It is unknown whether this package works with Browsers
JSR Score
100%
Published
2 months ago (0.11.0)
Deno KV OAuth logo

High-level OAuth 2.0 powered by Deno KV.

Docs CI codecov Built with the Deno Standard Library

Deno KV OAuth (Beta)

Features

Documentation

Check out the full documentation and API reference here.

How-to

Get Started with a Pre-Defined OAuth Configuration

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

  1. Create your OAuth application for your given provider.

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

    // server.ts
    import { createGitHubOAuthConfig, createHelpers } from "jsr:@deno/kv-oauth";
    
    const oauthConfig = createGitHubOAuthConfig();
    const {
      signIn,
      handleCallback,
      getSessionId,
      signOut,
    } = createHelpers(oauthConfig);
    
    async function handler(request: Request) {
      const { pathname } = new URL(request.url);
      switch (pathname) {
        case "/oauth/signin":
          return await signIn(request);
        case "/oauth/callback":
          const { response } = await handleCallback(request);
          return response;
        case "/oauth/signout":
          return await signOut(request);
        case "/protected-route":
          return await getSessionId(request) === undefined
            ? new Response("Unauthorized", { status: 401 })
            : new Response("You are allowed");
        default:
          return new Response(null, { status: 404 });
      }
    }
    
    Deno.serve(handler);
    
  3. Start your server with the necessary environment variables.

    GITHUB_CLIENT_ID=xxx GITHUB_CLIENT_SECRET=xxx deno run --unstable-kv --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

  1. Create your OAuth application for your given provider.

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

    // server.ts
    import {
      createHelpers,
      getRequiredEnv,
      type OAuth2ClientConfig,
    } from "jsr:@deno/kv-oauth";
    
    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",
    };
    const {
      signIn,
      handleCallback,
      getSessionId,
      signOut,
    } = createHelpers(oauthConfig);
    
    async function handler(request: Request) {
      const { pathname } = new URL(request.url);
      switch (pathname) {
        case "/oauth/signin":
          return await signIn(request);
        case "/another-dir/callback":
          const { response } = await handleCallback(request);
          return response;
        case "/oauth/signout":
          return await signOut(request);
        case "/protected-route":
          return await getSessionId(request) === undefined
            ? new Response("Unauthorized", { status: 401 })
            : new Response("You are allowed");
        default:
          return new Response(null, { status: 404 });
      }
    }
    
    Deno.serve(handler);
    
  3. Start your server with the necessary environment variables.

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

This is required for OAuth solutions that span more than one sub-domain.

  1. Create your OAuth application for your given provider.

  2. Create your web server using Deno KV OAuth's helpers factory function with cookie options defined.

    // server.ts
    import { createGitHubOAuthConfig, createHelpers } from "jsr:@deno/kv-oauth";
    
    const {
      signIn,
      handleCallback,
      signOut,
      getSessionId,
    } = createHelpers(createGitHubOAuthConfig(), {
      cookieOptions: {
        name: "__Secure-triple-choc",
        domain: "news.site",
      },
    });
    
    async function handler(request: Request) {
      const { pathname } = new URL(request.url);
      switch (pathname) {
        case "/oauth/signin":
          return await signIn(request);
        case "/oauth/callback":
          const { response } = await handleCallback(request);
          return response;
        case "/oauth/signout":
          return await signOut(request);
        case "/protected-route":
          return await getSessionId(request) === undefined
            ? new Response("Unauthorized", { status: 401 })
            : new Response("You are allowed");
        default:
          return new Response(null, { status: 404 });
      }
    }
    
    Deno.serve(handler);
    
  3. Start your server with the necessary environment variables.

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

Get Started with Fresh

  1. Create your OAuth application for your given provider.

  2. Create your OAuth configuration and Fresh plugin.

    // plugins/kv_oauth.ts
    import { createGitHubOAuthConfig, createHelpers } from "jsr:@deno/kv-oauth";
    import type { Plugin } from "$fresh/server.ts";
    
    const { signIn, handleCallback, signOut, getSessionId } = createHelpers(
      createGitHubOAuthConfig(),
    );
    
    export default {
      name: "kv-oauth",
      routes: [
        {
          path: "/signin",
          async handler(req) {
            return await signIn(req);
          },
        },
        {
          path: "/callback",
          async handler(req) {
            // Return object also includes `accessToken` and `sessionId` properties.
            const { response } = await handleCallback(req);
            return response;
          },
        },
        {
          path: "/signout",
          async handler(req) {
            return await signOut(req);
          },
        },
        {
          path: "/protected",
          async handler(req) {
            return await getSessionId(req) === undefined
              ? new Response("Unauthorized", { status: 401 })
              : new Response("You are allowed");
          },
        },
      ],
    } as Plugin;
    
  3. Add the plugin to your Fresh app.

  4. Start your Fresh server with the necessary environment variables.

    GITHUB_CLIENT_ID=xxx GITHUB_CLIENT_SECRET=xxx deno task start
    

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.

  1. Create your OAuth application for your given provider.

  2. Start the demo with the necessary environment variables.

    TWITTER_CLIENT_ID=xxx TWITTER_CLIENT_SECRET=xxx deno task demo
    

Concepts

Redirects after Sign-In and Sign-Out

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:

  1. 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.
  2. 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.
  3. 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:

  1. Auth0
  2. AWS Cognito User Pool
  3. AzureAD
  4. AzureADB2C
  5. Discord
  6. Dropbox
  7. Facebook
  8. GitHub
  9. GitLab
  10. Google
  11. Logto
  12. Notion
  13. Okta
  14. Patreon
  15. Slack
  16. Spotify
  17. Twitter

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.

  1. PROVIDER_CLIENT_ID - Client ID of a given OAuth application.
  2. PROVIDER_CLIENT_SECRET - Client secret of a given OAuth application.
  3. PROVIDER_DOMAIN (optional) - Server domain of a given OAuth application. Required for Auth0, AzureADB2C, AWS Cognito, and Okta.

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

Built with Deno KV OAuth

  1. Deno KV OAuth live demo
  2. Deno SaaSKit - A modern SaaS template built on Fresh and uses a custom Deno KV OAuth plugin.
  3. KV SketchBook - Dead simple sketchbook app.
  4. Fresh + Deno KV OAuth demo - A demo of Deno KV OAuth working in the Fresh web framework.
  5. Oak + Deno KV OAuth demo - A demo of Deno KV OAuth working in the Oak web framework.
  6. Ultra + Deno KV OAuth demo - A demo of Deno KV OAuth working in the Ultra web framework.
  7. Hono + Deno KV OAuth demo - A demo of Deno KV OAuth working in the Hono web framework.
  8. Cheetah + Deno KV OAuth demo - A demo of Deno KV OAuth working in the Cheetah web framework.
  9. Paquet - A web app shop
  10. Fastro + Deno KV OAuth live demo - A simple, reusable fastro module that implements Deno KV.

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.

Contributing Guide

Check out the contributing guide here.

Security Policy

Check out the security policy here.

Built and signed on
GitHub Actions
View transparency log

Add Package

deno add @deno/kv-oauth

Import symbol

import * as mod from "@deno/kv-oauth";

Add Package

npx jsr add @deno/kv-oauth

Import symbol

import * as mod from "@deno/kv-oauth";

Add Package

yarn dlx jsr add @deno/kv-oauth

Import symbol

import * as mod from "@deno/kv-oauth";

Add Package

pnpm dlx jsr add @deno/kv-oauth

Import symbol

import * as mod from "@deno/kv-oauth";

Add Package

bunx jsr add @deno/kv-oauth

Import symbol

import * as mod from "@deno/kv-oauth";