Deno KV OAuth

Docs CI codecov

High-level OAuth 2.0 powered by Deno KV.

Note: this project is in beta. API design and functionality are subject to change.

Features

Live Demo

You can also check out a live demo at https://kv-oauth.deno.dev, which uses Github as the OAuth 2.0 provider. Source code is located in demo.ts.

Usage

Check out the full documentation and API reference here.

Getting Started

This example uses GitHub as the OAuth 2.0 provider. However, you can use any provider you like.

  1. Create your OAuth 2.0 application for your given provider.

  2. Create your pre-configured or custom OAuth 2.0 client instance.

    // Pre-configured OAuth 2.0 client
    import { createGitHubOAuth2Client } from "https://deno.land/x/deno_kv_oauth@$VERSION/mod.ts";
    
    const oauth2Client = createGitHubOAuth2Client();
  3. Using the OAuth 2.0 client instance, insert the authentication flow functions into your authentication routes.

    // Sign-in, callback and sign-out handlers
    import {
      createGitHubOAuth2Client,
      handleCallback,
      signIn,
      signOut,
    } from "https://deno.land/x/deno_kv_oauth@$VERSION/mod.ts";
    
    const oauth2Client = createGitHubOAuth2Client();
    
    async function handleSignIn(request: Request) {
      return await signIn(request, oauth2Client);
    }
    
    async function handleOAuth2Callback(request: Request) {
      return await handleCallback(request, oauth2Client);
    }
    
    async function handleSignOut(request: Request) {
      return await signOut(request);
    }
  4. Use Deno KV OAuth's helper functions where needed.

    // Protected route
    import {
      createGitHubOAuth2Client,
      getSessionAccessToken,
      getSessionId,
    } from "https://deno.land/x/deno_kv_oauth@$VERSION/mod.ts";
    
    const oauth2Client = createGitHubOAuth2Client();
    
    async function handleAccountPage(request: Request) {
      const sessionId = await getSessionId(request);
      const isSignedIn = sessionId !== undefined;
    
      if (!isSignedIn) return new Response(null, { status: 404 });
    
      const accessToken = await getSessionAccessToken(oauth2Client, sessionId);
      return Response.json({ isSignedIn, accessToken });
    }
  5. 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.

Pre-configured OAuth 2.0 Clients

This module comes with a suite of pre-configured OAuth 2.0 clients for the following providers:

  1. Discord
  2. Dropbox
  3. Facebook
  4. GitHub
  5. GitLab
  6. Google
  7. Notion
  8. Patreon
  9. Slack
  10. Spotify
  11. Twitter

Each function is typed so that their respective platform's requirements are met.

If there's a pre-configured OAuth 2.0 client for a provider you'd like added, please submit a pull request or create a new issue.

Custom OAuth 2.0 Client

If you require custom OAuth 2.0 configuration, you must define your client using new OAuth2Client() from the oauth2_client module. E.g.:

import { OAuth2Client } from "https://deno.land/x/oauth2_client/mod.ts";

const client = new OAuth2Client({
  clientId: Deno.env.get("CUSTOM_CLIENT_ID")!,
  clientSecret: Deno.env.get("CUSTOM_CLIENT_SECRET")!,
  authorizationEndpointUri: "https://custom.com/oauth/authorize",
  tokenUri: "https://custom.com/oauth/token",
  redirectUri: "https://my-site.com",
});

Environment Variables

  • KV_PATH (optional) - defines the path that Deno KV uses. See the API reference for further details.
  • ${PROVIDER}_CLIENT_ID and ${PROVIDER}_CLIENT_SECRET - required when creating a pre-configured OAuth 2.0 client for a given provider. E.g. for Twitter, the environment variable keys are TWITTER_CLIENT_ID and TWITTER_CLIENT_SECRET. See the list below for specifics.

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

Running the Demo

Run deno task demo to start the demo application. The task uses environment variables defined in a .env file at the root of this folder.

By default, the demo uses GitHub with a minimal scope. Use the PROVIDER and SCOPE environment variables, if you'd like to change this behavior. E.g. for Twitter:

PROVIDER=Twitter SCOPE=users.read deno task demo

Contributing

Before submitting a pull request, please run deno task ok and ensure all checks pass. This checks formatting, linting, types and runs tests.

Adding a Pre-configured OAuth 2.0 Client

In the pull request, please do the following:

  1. Share a screenshot of the demo web page running on your local machine. This confirms that the newly created OAuth 2.0 client is working correctly.
  2. Ensure the code example snippet is reproducible.
  3. Add the provider to the README's list of pre-configured OAuth 2.0 clients, in alphabetical order.

In the Wild

Check out these projects powered by Deno KV OAuth 2.0:

  1. Deno SaaSKit / Deno Hunt - A modern SaaS template built on Fresh.
  2. KV SketchBook - Dead simple sketchbook app.
  3. Fresh + Deno KV OAuth demo - A demo of Deno KV OAuth working in the Fresh web framework.
  4. Oak + Deno KV OAuth demo - A demo of Deno KV OAuth working in the Oak web framework.

Do you have a project powered by Deno KV OAuth 2.0 that you'd like to share? Please submit a pull request adding that project to this list.