Netzo Logo

Auth

Built-in authentication, user management and role-based access control (RBAC).

The Authentication module is a plug-and-play authentication solution for your application. The module provides unified authentication flows for multiple authentication providers, simple yet flexible user management and role-based access control (RBAC).

Authentication preview

When enabling authentication for any of the supported authentication providers, the following routes are added to your application

UI routes: brandable pages mounted at specific routes

  • /auth - serves the sign-in/up page for users to authenticate to the application.

API routes: endpoints used to handle authentication requests (auth flows)

  • /auth/{provider}/sign-in - handles sign-in requests (creates new auth session)
  • /auth/{provider}/callback - handles callback requests after sign-ins (internal)
  • /auth/sign-out - handles sign-out requests (clears existing auth session if any)

as well as middlewares to manage sessions, users and handle redirects.

Note that this module applies to all routes except those under the path configured for the REST module (defaults to /rest) if it is enabled. Authentication for those routes is handled by the REST module instead.
By design, the Authentication module is scoped to the workspace, rather than the individual projects that use it. This means that authentication users and sessions are shared across all projects within the workspace, making it easier to manage users and their roles. Still, each application can implement its own logic to manage users and roles as required.

Users

Authentication users are users that can authenticate to the application. Users can be added manually from the Users page, or automatically when a user signs in for the first time (provided that new registrations/sign-ups are enabled).

All active and inactive authentication users are listed in the Users page. Here, you can manage users and their roles. The role will determine the permissions each user has within the application, but this logic is to be implemented for each application as required via the helpers netzo provides.

Authentication users

Usage

Registration

Configure the app in a netzo.config.ts configuration file as shown below.

Note that at least one authentication provider must be configured to enable the Authentication module.
netzo.config.ts
import { defineConfig } from "netzo/mod.ts";
import * as netzo from "netzo/plugins/mod.ts";

export default defineConfig({
  plugins: [
    netzo.auth({
      title: "Sign In",
      description: "Sign in to access the app",
      caption: 'By signing in you agree to the <a href="/" target="_blank">Terms of Service</a>',
      providers: { /* refer to each individual provider */ }
    })
  ],
});
To skip authentication during development set the auth property to undefined as shown below.
export const netzo = await Netzo({
  auth: Deno.env.get("DENO_REGION") ? { providers: { /* ... */ } } : undefined,
});

Configuration

import type { OAuth2ClientConfig } from "https://deno.land/x/oauth2_client/mod.ts?s=OAuth2ClientConfig";

type AuthConfig = {
  /* Title shown above the sign-in/sign-up form */
  title?: string;
  /* Description shown above the sign-in/sign-up form */
  description?: string;
  /* Caption shown below the sign-in/sign-up form (useful for linking policies) */
  caption?: string;
  /* Configuration for each provider (at least one is required to enable module) */
  providers: {
    netzo?: NetzoClientConfig;
    email?: EmailClientConfig;
    google?: OAuth2ClientConfig;
    github?: OAuth2ClientConfig;
    gitlab?: OAuth2ClientConfig;
    auth0?: OAuth2ClientConfig;
    okta?: OAuth2ClientConfig;
  };
};

Environment Variables

To ease development, the Authentication module will attempt to load configuration defaults for each provider from environment variables. Replace the PROVIDER prefix with your given OAuth provider's name when starting your server. E.g. GOOGLE, GITHUB or AUTH0.

  • 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. Netzo sets the required permissions already via the default start task, so you don't need to worry about it when running with deno task start.

State

Authentication state like current session and user information is available via ctx.state.auth. Note that the authentication state can only be accessed via ctx: RouteContext in (server-side) routes. For usage in components or islands (client-side) you can pass results down as props.

routes/index.tsx
import { defineRoute } from "$fresh/server.ts";
import type { NetzoState } from 'netzo/mod.ts'

export default defineRoute<NetzoState>(async (req, ctx) => {
  const { sessionId, sessionUser } = ctx.state?.auth ?? {};
  const mustAuth = !!ctx.state?.auth && !sessionId;

  if (mustAuth) Response.redirect("/auth");

  return (
    <div>
      <h1>Welcome, {sessionUser.name}</h1>
      <a href="/auth/signout">Sign Out</a>
    </div>
  );
});

Errors

The Authentication module automatically handles errors and redirects during the authentication process. Redirecting to /auth?error=... ` will automatically display for the user to see. This is useful in case you need to handle authentication errors manually.

For instance, the /auth?error=You do not have access to this application will render the following error page:

Authentication error

Advanced

This module is meant to provide the most essential authentication features in a simple and easy to use bundle. If you need more advanced features, you can always implement your own authentication including integrating with popular authentication libraries and services.

Providers

Authentication providers is how users can authenticate to the application. Multiple authentication providers can be configured for the application in the netzo.config.ts configuration file as shown below.

Authentication providers

Netzo

netzo.config.ts
import { defineConfig } from "netzo/mod.ts";
import * as netzo from "netzo/plugins/mod.ts";

export default defineConfig({
  plugins: [
    netzo.auth({
      providers: {
        netzo: {}
      }
    })
  ],
});

Email

Coming soon...

Google

netzo.config.ts
import { defineConfig } from "netzo/mod.ts";
import * as netzo from "netzo/plugins/mod.ts";

export default defineConfig({
  plugins: [
    netzo.auth({
      providers: {
      google: {
        clientId: Deno.env.get('GOOGLE_CLIENT_ID')!,
        clientSecret: Deno.env.get('GOOGLE_CLIENT_SECRET')!,
        }
      }
    })
  ],
});

GitHub

netzo.config.ts
import { defineConfig } from "netzo/mod.ts";
import * as netzo from "netzo/plugins/mod.ts";

export default defineConfig({
  plugins: [
    netzo.auth({
      providers: {
      github: {
        clientId: Deno.env.get('GITHUB_CLIENT_ID')!,
        clientSecret: Deno.env.get('GITHUB_CLIENT_SECRET')!,
        }
      }
    })
  ],
});

GitLab

netzo.config.ts
import { defineConfig } from "netzo/mod.ts";
import * as netzo from "netzo/plugins/mod.ts";

export default defineConfig({
  plugins: [
    netzo.auth({
      providers: {
      gitlab: {
        clientId: Deno.env.get('GITLAB_CLIENT_ID')!,
        clientSecret: Deno.env.get('GITLAB_CLIENT_SECRET')!,
        }
      }
    })
  ],
});

Slack

netzo.config.ts
import { defineConfig } from "netzo/mod.ts";
import * as netzo from "netzo/plugins/mod.ts";

export default defineConfig({
  plugins: [
    netzo.auth({
      providers: {
      slack: {
        clientId: Deno.env.get('SLACK_CLIENT_ID')!,
        clientSecret: Deno.env.get('SLACK_CLIENT_SECRET')!,
        }
      }
    })
  ],
});

Auth0

netzo.config.ts
import { defineConfig } from "netzo/mod.ts";
import * as netzo from "netzo/plugins/mod.ts";

export default defineConfig({
  plugins: [
    netzo.auth({
      providers: {
      auth0: {
        clientId: Deno.env.get('AUTH0_CLIENT_ID')!,s
        clientSecret: Deno.env.get('AUTH0_CLIENT_SECRET')!,
        domain: Deno.env.get('AUTH0_DOMAIN')!
        }
      }
    })
  ],
});

Okta

netzo.config.ts
import { defineConfig } from "netzo/mod.ts";
import * as netzo from "netzo/plugins/mod.ts";

export default defineConfig({
  plugins: [
    netzo.auth({
      providers: {
        okta: {
          clientId: Deno.env.get('OKTA_CLIENT_ID')!,
          clientSecret: Deno.env.get('OKTA_CLIENT_SECRET')!,
          domain: Deno.env.get('OKTA_DOMAIN')!
        }
      }
    })
  ],
});

REST

Adds a RESTful API on top of the NetzoDB database powered by Deno KV

UnoCSS

Supercharge development with Netzo\'s UnoCSS plugin, a utility-first CSS framework for rapid UI styling and development.