DEV Community: Kiran Krishnan

Adding SAML Single Sign-On to an Express App: A Step-by-Step Guide 🚀🚀

Kiran Krishnan — Mon, 04 Sep 2023 06:45:50 +0000

In this article, you'll learn how add SAML SSO login to an Express.js app. You'll use SAML Jackson with Auth0 to authenticate users and protect routes.

boxyhq / jackson

🔥 Streamline your web application's authentication with Jackson, an SSO service supporting SAML and OpenID Connect protocols. Beyond enterprise-grade Single Sign-On, it also supports Directory Sync via the SCIM 2.0 protocol for automatic user and group provisioning/de-provisioning. 🤩

SAML Jackson: Open Source Enterprise SSO And Directory Sync

SAML Jackson bridges or proxies a SAML login flow to OAuth 2.0 or OpenID Connect, abstracting away all the complexities of the SAML protocol. It also supports Directory Sync via the SCIM 2.0 protocol for automatic user and group provisioning/de-provisioning.

We now also support OpenID Connect providers.

Directory Sync

SAML Jackson also supports Directory Sync based on the SCIM 2.0 protocol.

Directory sync helps organizations automate the provisioning and de-provisioning of their users. As a result, it streamlines the user lifecycle management process by saving valuable organizational hours, creating a single truth source of the user identity data, and facilitating them to keep the data secure.

For complete documentation, visit boxyhq.com/docs/directory-sync/overview

🌟 Why star this repository?

If you find this project helpful, please consider supporting us by starring the repository and sharing it with others. This helps others find the project…

View on GitHub

You can also access the full code at the GitHub repository.

Let’s get started!

Prerequisites

To follow along with this article, you’ll need the following:

Node.js installed on your computer
Basic knowledge about Node.js and Express.js

Setting up the database

Make sure you have a PostgreSQL database ready. You can use any PostgreSQL database you want.

If you're on macOS, you can use DBngin to create a PostgreSQL database. It's free and easy to use.

Configure the Identity Provider

We'll use the Auth0 as our identity provider. An Identity Provider (IdP) is a service that manage user accounts for your app.

First, go to the Auth0 signup page, then create an account.
Go to Dashboard > Applications > Applications.
Click the Create Application button.
Give your new application a name.
Choose Regular Web Applications as an application type and the click Create.
Go to the app you created, then click the Addons tab.
In the SAML2 Web App box, click the slider to enable the Addon.
Go to the Usage tab and download the Identity Provider Metadata.
Go to the Settings tab and make below changes.
Add http://localhost:3000/sso/acs as your Application Callback URL that receives the SAML response.
Paste the following JSON for Settings, then click Enable button.

{
  "audience": "https://saml.boxyhq.com",
  "mappings": {
    "id": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
    "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
    "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
    "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
  }
}

audience is just an identifier to validate the SAML audience. More info.

Auth0 provides database connections to authenticate users with an email/username and password. These credentials are securely stored in the Auth0 user store.

Let's create one so that our users can register or login.

Go to Auth0 Dashboard > Authentication > Database.
Click Create DB Connection - Auth0 Create DB Document
Give your connection a name, then click Create.
Go to the Applications tab and enable the application you just created.

Now we've everything ready, let's move to the next step.

Getting started

Launch a terminal and clone the GitHub repo:

git clone https://github.com/devkiran/express-saml.git

cd express-saml

Now, install the dependencies:

npm install

Add the environment variables:

cp .env.example .env

Update the DATABASE_URL variable with your Postgres database connection URI.

About the Express app

This is a simple express.js app created using express-generator. You can use any express.js app if you want.

Our express.js app has only 2 routes.

GET / render a home page
GET /dashboard render a dashboard

So, what's the plan? We'll add SAML SSO login (via Auth0) to our express.js app so that only authenticated users can access the /dashboard.

Install SAML Jackson

Run the following command to install the latest version of the SAML Jackson.

npm i --save @boxyhq/saml-jackson

Once you installed Jackson, let's initialize it.

Add the following code to the routes/index.js.

// routes/index.js

...

let apiController;
let oauthController;

const jacksonOptions = {
  externalUrl: process.env.APP_URL,
  samlAudience: process.env.SAML_AUDIENCE,
  samlPath: '/sso/acs',
  db: {
    engine: 'sql',
    type: 'postgres',
    url: process.env.DATABASE_URL,
  },
};

(async function init() {
  const jackson = await require('@boxyhq/saml-jackson').controllers(jacksonOptions);

  apiController = jackson.apiController;
  oauthController = jackson.oauthController;
})();

Setting up Express.js routes

Now let's add the routes to our express.js app.

Add SAML Metadata

The first route you'll create is the GET /connection one. This route will display a form with following fields:

Metadata: Enter the XML Metadata content you've downloaded from IdP.
Tenant: Jackson supports a multi-tenant architecture, this is a unique identifier you set from your side that relates back to your customer's tenant. This is normally an email, domain, an account id, or user-id.
Product: Jackson support multiple products, this is a unique identifier you set from your side that relates back to the product your customer is using.

// routes/index.js

router.get('/connection', async (req, res) => {
  res.render('connection');
});

Add a view to display the form.

<!-- views/connection.ejs -->

<!DOCTYPE html>
<html>
  <head>
    <title>SAML Connection</title>
    <script src="https://cdn.tailwindcss.com?plugins=forms,typography,aspect-ratio,line-clamp"></script>
    <link rel="stylesheet" href="/stylesheets/style.css" />
  </head>
  <body>
    <div class="max-w-md mx-auto mt-6 p-6 bg-white rounded-lg shadow-md">
      <h1 class="text-2xl font-semibold text-center mb-4">SAML Connection</h1>
      <p class="text-gray-600 text-center mb-4">Add SAML Metadata.</p>

      <form action="/connection" method="POST">
        <div class="mb-4">
          <label for="tenant" class="block text-gray-700">Tenant</label>
          <input
            type="text"
            name="tenant"
            id="tenant"
            class="form-input mt-1 block w-full"
            required="required"
          />
        </div>
        <div class="mb-4">
          <label for="product" class="block text-gray-700">Product</label>
          <input
            type="text"
            name="product"
            id="product"
            class="form-input mt-1 block w-full"
            required="required"
          />
        </div>
        <div class="mb-4">
          <label for="rawMetadata" class="block text-gray-700"
            >Metadata (Raw XML)</label
          >
          <textarea
            name="rawMetadata"
            id="rawMetadata"
            cols="30"
            rows="10"
            class="form-textarea mt-1 block w-full"
            required="required"
          ></textarea>
        </div>
        <div class="mb-4">
          <button
            type="submit"
            class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded"
          >
            Submit
          </button>
        </div>
      </form>
    </div>
  </body>
</html>

Now let's add another route POST /connection that will store the form data by calling the SAML Jackson config API.

This step is the equivalent of setting an OAuth 2.0 app and generating a client ID and client secret that will be used in the login flow.

// routes/index.js

router.post('/connection', async (req, res, next) => {
  const { rawMetadata, tenant, product } = req.body;

  const defaultRedirectUrl = 'http://localhost:3000/sso/callback';
  const redirectUrl = '["http://localhost:3000/*"]';

  try {
    await apiController.config({
      rawMetadata,
      tenant,
      product,
      defaultRedirectUrl,
      redirectUrl,
    });

    res.redirect('/connection');
  } catch (err) {
    next(err);
  }
});

There are a few important things to note in the code above.

defaultRedirectUrl holds the redirect URL to use in the IdP login flow. Jackson will call this URL after completing an IdP login flow.

redirectUrl holds an array containing a list of allowed redirect URLs. Jackson will disallow any redirects that are not on this list.

Next, let's start the express app. The app starts a server and listens on port 3000 (by default) for connections.

npm start

Now, let's visit http://localhost:3000/connection, you should see the page with a form.

Here you can add the metadata you've downloaded from Auth0. Fill out the form with a Tenant, Product, and paste the metadata XML content as it is.

I'll use boxyhq.com as tenant and crm as product.

The response returns a JSON with client_id and client_secret that can be stored against your tenant and product for a more secure OAuth 2.0 flow.

If you do not want to store the client_id and client_secret you can alternatively use client_id=tenant=<tenantID>&product=<productID> and any arbitrary value for client_secret when setting up the OAuth 2.0 flow.

Redirect the users to IdP

Now you have added the SAML metadata, you'll need a route to redirect the users to IdP to start the SAML authentication.

Let's add a new route GET /sso/authorize.

Don't forget to change the values of the tenant and product in the code.

// routes/index.js

router.get('/sso/authorize', async (req, res, next) => {
  try {
    const tenant = 'boxyhq.com';
    const product = 'crm';

    const body = {
      response_type: 'code',
      client_id: `tenant=${tenant}&product=${product}`,
      redirect_uri: 'http://localhost:3000/sso/callback',
      state: 'a-random-state-value',
    };

    const { redirect_url } = await oauthController.authorize(body);

    res.redirect(redirect_url);
  } catch (err) {
    next(err);
  }
});

oauthController.authorize() will returns a redirect_url. You should redirect the users to this redirect_url to start the IdP authentication flow.

Handle the SAML Response from IdP

This route becomes the Assertion Consumer Service (ACS) URL of your app. The ACS URL tells your IdP where to POST its SAML Response after authenticating a user.

The SAML Response contains 2 fields: SAMLResponse and RelayState.

// routes/index.js

router.post('/sso/acs', async (req, res, next) => {
  try {
    const { SAMLResponse, RelayState } = req.body;

    const body = {
      SAMLResponse,
      RelayState,
    };

    const { redirect_url } = await oauthController.samlResponse(body);

    res.redirect(redirect_url);
  } catch (err) {
    next(err);
  }
});

Call to the method oauthController.samlResponse() will returns a redirect_url. You should redirect the users to this redirect_url. The query parameters will include the code and state parameters.

Code exchange

Now exchange the code for a token. The token is required to access the user profile.

Let's create a new route GET /sso/callback to handle the callback.

// routes/index.js

router.get('/sso/callback', async (req, res, next) => {
  const { code } = req.query;

  const tenant = 'boxyhq.com';
  const product = 'crm';

  const body = {
    code,
    client_id: `tenant=${tenant}&product=${product}`,
    client_secret: 'dummy',
  };

  try {
    // Get the access token
    const { access_token } = await oauthController.token(body);

    // Get the user information
    const profile = await oauthController.userInfo(access_token);

    // Add the profile to the express session
    req.session.profile = profile;

    res.redirect('/dashboard');
  } catch (err) {
    next(err);
  }
});

In the above code, replace the value for tenant and product with yours.

Protect the dashboard

Now is the time to fix our GET /dashboard route so that only authenticated users can access it.

Let's fix it by adding a condition to check if the profile exists in the session.

If profile is undefined, redirect the users back to the / otherwise display the profile on the dashboard.

Replace the GET /dashboard route with the below code.

// routes/index.js

router.get('/dashboard', function (req, res, next) {
  const { profile } = req.session;

  if (profile === undefined) {
    return res.redirect('/');
  }

  // Pass the profile to the view
  res.render('dashboard', {
    profile,
  });
});

Replace the views/dashboard.ejs view with the below code.

<!-- views/dashboard.ejs -->

<!DOCTYPE html>
<html>
  <head>
    <title>Dashboard</title>
    <link rel="stylesheet" href="/stylesheets/style.css" />
  </head>
  <body>
    <h1>Dashboard</h1>
    <p>Only authenticated users should access this page.</p>

    <p>Id - <%= profile.id %></p>
    <p>Email - <%= profile.email %></p>
  </body>
</html>

From the command line, let's restart the express app then visit the authorize the URL http://localhost:3000/sso/authorize.

If you've configured everything okay, it should redirect you to the Auth0 authentication page, then click on the Sign up link and register there

If the authentication is successful, the app will redirect you to the dashboard and display the id, email of the user.

Conclusion

Congratulations, you should now have a functioning SAML SSO integrated with your express.js app using the SAML Jackson and Auth0.

References

To learn more about SAML Jackson, take a look at the following resources:

Your feedback and contributions are welcome!

// Detect dark theme var iframe = document.getElementById('tweet-1694089182296121402-115'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1694089182296121402&theme=dark" }

9 Next.js Open Source Projects for Contributions 🚀🚀

Kiran Krishnan — Fri, 01 Sep 2023 10:28:13 +0000

I've been using Next.js for a while now and have grown to love it. It's an excellent framework for building full-stack web applications.

I'm always on the lookout for open-source projects where I can contribute. It's a fantastic way to learn, enhance your skills, and give back to the community.

In this brief article, I'll share nine open-source Next.js projects that welcome contributions. I hope you discover something that piques your interest.

Ensure you star the repositories you like; it's a great way to show appreciation.

Here they are, listed in no particular order.

Dub

An open-source link management tool for modern marketing teams to create, share, and track short links.

dubinc / dub

The modern link attribution platform. Loved by world-class marketing teams like Twilio, Buffer, Framer, Perplexity, Vercel, and more.

Dub

The open-source link attribution platform
Learn more »

Introduction · Tech Stack · Self-hosting · Contributing

Introduction

Dub is the modern, open-source link attribution platform for short links, conversion tracking, and affiliate programs.

Our platform powers 100M+ clicks and 2M+ links monthly, and is used by world-class marketing teams from companies like Twilio, Buffer, Framer, Perplexity, Vercel, Laravel, and more.

Tech Stack

Next.js – framework
TypeScript – language
Tailwind – CSS
Prisma – ORM
Upstash – redis
Tinybird – analytics
PlanetScale – database
NextAuth.js – auth
BoxyHQ – SSO/SAML
Turborepo – monorepo
Stripe – payments
Resend – emails
Vercel – deployments
Pangea - link scanning

Self-Hosting

You can self-host Dub for greater control over your data and design. Read this guide to learn more.

Contributing

We love our contributors! Here's how you can contribute:

Open an issue if you believe you've encountered a bug.
Follow…

View on GitHub

Cal.com

Meet Cal.com, the event-juggling scheduler for everyone. Focus on meeting, not making meetings. Free for individuals.

calcom / cal.com

Scheduling infrastructure for absolutely everyone.

Cal.com (formerly Calendso)

The open-source Calendly successor
Learn more »

Discussions · Website · Issues · Roadmap

About the Project

Scheduling infrastructure for absolutely everyone

The open source Calendly successor. You are in charge of your own data, workflow, and appearance.

Calendly and other scheduling tools are awesome. It made our lives massively easier. We're using it for business meetings, seminars, yoga classes, and even calls with our families. However, most tools are very limited in terms of control and customization.

That's where Cal.com comes in. Self-hosted or hosted by us. White-label by design. API-driven and ready to be deployed on your own domain. Full control of your events and data.

Recognition

Hacker News

Product Hunt

Built With

Contact us

Meet our sales team for any commercial inquiries.

Stay Up-to-Date

Cal.com officially launched as v.1.0 on the 15th of September 2021 and we've…

View on GitHub

Documenso

Documenso aims to be the world's most trusted document signing tool. This trust is built by empowering you to self-host Documenso and review how it works under the hood.

documenso / documenso

The Open Source DocuSign Alternative.

The Open Source DocuSign Alternative
Learn more »

Discord · Website · Issues · Upcoming Releases · Roadmap

About Documenso

Signing documents digitally should be fast and easy and should be the best practice for every document signed worldwide. This is technically quite easy today, but it also introduces a new party to every signature: The signing tool providers. While this is not a problem in itself, it should make us think about how we want these providers of trust to work. Documenso aims to be the world's most trusted document-signing tool. This trust is built by empowering you to self-host Documenso and review how it works under the hood.

Join us in creating the next generation of open trust infrastructure.

Recognition

Community and Next Steps 🎯

We're currently working on a redesign of the application, including a revamp of the codebase, so Documenso can be more intuitive to use…

View on GitHub

Formbricks

Formbricks is your go-to solution for in-product micro-surveys that will supercharge your product experience. Use micro-surveys to target the right users at the right time without making surveys annoying.

formbricks / formbricks

Open Source Qualtrics Alternative

Help us grow and star us on Github! ⭐️

Formbricks

The Open Source Qualtrics Alternative
Website

Trusted by

✨ About Formbricks

Formbricks provides a free and open source surveying platform. Gather feedback at every point in the user journey with beautiful in-app, website, link and email surveys. Build on top of Formbricks or leverage prebuilt data analysis capabilities.

Try it out in the cloud at formbricks.com

💪 Mission: Empower your team, craft an irresistible experience.

Formbricks is both a free and open source survey platform - and a privacy-first experience management platform. Use in-app, website, link and email surveys to gather user and customer insights at every point of their journey. Leverage Formbricks Insight Platform or build your own. Life's too short for mediocre UX.

Features

📲 Create conversion-optimized surveys with our no-code editor with…

View on GitHub

Next.js SaaS Starter Kit

Next.js based SaaS starter kit saves you months of development by starting you off with all the features that are the same in every product, so you can focus on what makes your app unique.

boxyhq / saas-starter-kit

🔥 Enterprise SaaS Starter Kit - Kickstart your enterprise app development with the Next.js SaaS boilerplate 🚀

⭐ Enterprise SaaS Starter Kit

The Open Source Next.js SaaS boilerplate for Enterprise SaaS app development.

Please star ⭐ the repo if you want us to continue developing and improving the SaaS Starter Kit! 😀

📖 Additional Resources

Video - BoxyHQ's SaaS Starter Kit: Your Ultimate Enterprise-Compliant Boilerplate
Blog - Enterprise-ready Saas Starter Kit

Next.js-based SaaS starter kit saves you months of development by starting you off with all the features that are the same in every product, so you can focus on what makes your app unique.

🛠️ Built With

Next.js This is a React framework that provides features such as server-side rendering and static site generation. It's used for building the user interface of your application. The main configuration for Next.js can be found in next.config.js.
Tailwind CSS This is a utility-first CSS framework for rapidly building custom user interfaces. It's used for styling the application. The…

View on GitHub

Supabase Studio

Supabase is an open-source Firebase alternative. Supabase studio is a dashboard for managing your Supabase projects.

supabase / supabase

The open source Firebase alternative. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

Supabase

Supabase is an open source Firebase alternative. We're building the features of Firebase using enterprise-grade open source tools.

Hosted Postgres Database. Docs
Authentication and Authorization. Docs
Auto-generated APIs
- REST. Docs
- GraphQL. Docs
- Realtime subscriptions. Docs
Functions
- Database Functions. Docs
- Edge Functions Docs
File Storage. Docs
AI + Vector/Embeddings Toolkit. Docs
Dashboard

Watch "releases" of this repo to get notified of major updates.

Documentation

For full documentation, visit supabase.com/docs

To see how to Contribute, visit Getting Started

Community & Support

Community Forum. Best for: help with building, discussion about database best practices.
GitHub Issues. Best for: bugs and errors you encounter using Supabase.
Email Support. Best for: problems with your database or infrastructure.
Discord. Best for: sharing your applications and hanging out with the community.

How it works

Supabase is a combination of open source tools. We’re building the features of Firebase using enterprise-grade, open source…

View on GitHub

Unkey

Open Source API Key Management. API authentication made easy.

unkeyed / unkey

Open source API management platform

Unkey

Open Source API authentication and authorization

unkey.com

Contributing

We welcome contributions! To ensure your work doesn't conflict with ongoing work, please:

Read our contributing guide
Discuss your ideas with us in public channels (GitHub/Discord) BEFORE starting development (No private DMs)
Get approval from a core team member

This helps us align efforts and prevents duplicated or conflicting work.

Let's talk

Authors

Stats

View on GitHub

Typebot

Typebot is an open-source chatbot builder. It allows you to create advanced chatbots visually, embed them anywhere on your web/mobile apps, and collect results in real time.

baptisteArno / typebot.io

💬 Typebot is a powerful chatbot builder that you can self-host.

Typebot is an Fair Source chatbot builder. It allows you to create advanced chatbots visually, embed them anywhere on your web/mobile apps, and collect results in real-time

Try Typebot • Docs

Builder demo

demo.mp4

Features

Typebot makes it easy to create advanced chatbots. It provides the building block that are adaptable to any business use case. I improve Typebot regularly with bug fixes, new features, and performance improvements regularly.

Chat builder with 34+ building blocks such as:

💬 Bubbles: Text, Image / GIF, video, audio, embed.
🔤 Inputs: Text, email, phone number, buttons, picture choice, date picker, payment (Stripe), file picker... inputs
🧠 Logic: Conditional branching, URL redirections, scripting (Javascript), A/B testing
🔌 Integrations: Webhook / HTTP requests, OpenAI, Google Sheets, Google Analytics, Meta Pixel, Zapier, Make.com, Chatwoot, More to come...

Theme your chatbot to match your brand identity:

🎨 Customize the fonts, background, colors, roundness, shadows, and more
💪…

View on GitHub

OpenStatus

OpenStatus is an open-source monitoring system with a beautiful status page. You can choose to host it yourself or use our hosted version.

openstatusHQ / openstatus

🏓 The open-source synthetic monitoring platform 🏓

OpenStatus

The Open-Source synthetic monitoring platform
Learn more »

Discord · Website · Issues

About OpenStatus 🏓

OpenStatus is open-source synthetic monitoring platform.

Synthetic monitoring: Monitor your website and APIs globally and receive notifications when they are down or slow.

Recognitions 🏆

Contact us 💌

If you are interested in our enterprise plan or need special features, please email us at ping@openstatus.dev or book a call

Roadmap 🗺️

Here's our roadmap feel free to contribute to it.

Contributing 🤝

If you want to help us building the best status page and alerting system, you can check our contributing guidelines

Top Contributors

Made with Contrib.rocks

Stats

Tech stack 🥞

Getting Started 🚀

With Devbox

You can use Devbox and get started with the following commands:

Install Devbox

curl -fsSL https://get.jetify.com/devbox | bash

Install project dependencies, build and start services
```
devbox services up
```

…

View on GitHub

Top SaaS Starter Kits & Boilerplates

Next.js 13 - Use Server Action to submit form data

Kiran Krishnan — Thu, 31 Aug 2023 17:32:13 +0000

Next.js 13 introduces a new feature called Server Actions. It is built on top of React Actions.

Server Actions are a way to run code on the server when a user performs an action on the client.

For example, when a user submits a form, you can run code on the server to process the form data.

In this article, we will learn how to use Server Actions to submit form data.

Let's create a new Next.js app using the following command:

npx create-next-app@latest

Enable the experimental server actions feature by adding the following code to the next.config.js file:

const nextConfig = {
  experimental: {
    serverActions: true,
  },
};

Create a new page with a signup form at app/signup/page.tsx with the following code:

export default function SignupPage() {
  return (
    <form method="POST">
      <input type="text" name="name" />
      <input type="email" name="email" />
      <input type="password" name="password" />
      <button type="submit">Create Account</button>
    </form>
  );
}

This page can be accessed at /signup.

Now you can add a function within the page component to handle the form submission. This function will be called when the user submits the form.

export default function SignupPage() {
  const createAccount = async (formData: FormData) => {
    "use server";

    const name = formData.get("name");
    const email = formData.get("email");
    const password = formData.get("password");

    // Validate the form data and save it to the database

    console.log({ name, email, password });
  };

  // Form code
}

The use server directive makes sure that this function is only executed on the server.

Within the createAccount function, we can access the form data using the FormData API. We can then process the form data and save it to the database.

Let's use this function to handle the form submission by adding the action attribute to the form element:

<form action={createAccount} method="POST">
  ...
</form>

Here is the complete code for the page component:

export default function SignupPage() {
  const createAccount = async (formData: FormData) => {
    "use server";

    const name = formData.get("name");
    const email = formData.get("email");
    const password = formData.get("password");

    console.log({ name, email, password });
  };

  return (
    <form action={createAccount} method="POST">
      <input type="text" name="name" />
      <input type="email" name="email" />
      <input type="password" name="password" />
      <button type="submit">Create Account</button>
    </form>
  );
}

Supabase ⚡ database functions

Kiran Krishnan — Thu, 31 Aug 2023 04:21:01 +0000

In this article, we will learn about Supabase database functions and how to invoke them from your app.

Supabase database functions are PostgreSQL functions that you can invoke from your app using the Supabase client.

Database function allow you to carry out operations that would normally take several queries and round trips in a single function within the database.

Create a table

Let's create a new table called restaurants and add some data to it.

CREATE TABLE restaurants (
  id INT PRIMARY KEY,
  name TEXT NOT NULL,
  description TEXT NOT NULL,
  address TEXT NOT NULL,
  phone_number TEXT NOT NULL,
  email TEXT NOT NULL,
  website TEXT NOT NULL,
  status TEXT NOT NULL
);

Add some restaurants to the table so we can test our database function. We'll add 5 restaurants to the table.

INSERT INTO restaurants (id, name, description, address, phone_number, email, website, status)
VALUES (1, 'Tasty Bites', 'A cozy bistro with a wide range of delicious dishes.', '123 Main St, Cityville', '+1234567890', 'info@tastybites.com', 'www.tastybites.com', 'approved');

INSERT INTO restaurants (id, name, description, address, phone_number, email, website, status)
VALUES (2, 'Sushi Delight', 'Experience the finest sushi in town.', '456 Oak Ave, Urbantown', '+9876543210', 'hello@sushidelight.com', 'www.sushidelight.com', 'approved');

INSERT INTO restaurants (id, name, description, address, phone_number, email, website, status)
VALUES (3, 'Pizza Haven', 'Authentic Italian pizzas made with love.', '789 Pine Rd, Villageland', '+5551234567', 'info@pizzahaven.net', 'www.pizzahaven.net', 'pending');

INSERT INTO restaurants (id, name, description, address, phone_number, email, website, status)
VALUES (4, 'Spice Fusion', 'A fusion of flavors from around the world.', '1010 Spice Blvd, Flavortown', '+1231231234', 'contact@spicefusion.co', 'www.spicefusion.co', 'approved');

INSERT INTO restaurants (id, name, description, address, phone_number, email, website, status)
VALUES (5, 'Café Euphoria', 'A serene café serving premium coffees and pastries.', '222 Serenity Ln, Tranquiltown', '+9879879876', 'info@cafeeuphoria.com', 'www.cafeeuphoria.com', 'rejected');

Explore the database function syntax

Here is the basic syntax for creating a database function.

CREATE FUNCTION function_name (arguments) RETURNS return_type AS $$
  DECLARE
    -- declare variables
  BEGIN
    -- function body
  END;
$$ LANGUAGE plpgsql;

A database function has the following parts:

function_name is the name of the function.
arguments are the arguments that the function accepts.
return_type is the type of value that the function returns.
function body is the code that the function executes.

Function that returns records

Let's create a simple function that returns the all the records from the restaurants table.

CREATE OR REPLACE FUNCTION get_restaurants()
  RETURNS SETOF restaurants AS $$
  BEGIN
    RETURN QUERY SELECT * FROM restaurants;
  END;
$$ LANGUAGE plpgsql;

You can see the get_restaurants function returns SETOF restaurants. This means that the function returns a set of records from the restaurants table.

You can invoke the function from the SQL editor or from your Next.js app.

SELECT * FROM get_restaurants();

Call the function from your Next.js app using the Supabase client.

const { data, error } = await supabase.rpc("get_restaurants");

You can also write the same function using the RETURNS TABLE syntax.

CREATE OR REPLACE FUNCTION get_restaurants_2()
  RETURNS TABLE (
    id INT,
    name TEXT,
    description TEXT,
    address TEXT,
    phone_number TEXT,
    email TEXT,
    website TEXT,
    status TEXT
  ) AS $$
  BEGIN
    RETURN QUERY SELECT * FROM restaurants;
  END;
$$ LANGUAGE plpgsql;

Function that returns specific columns

If you want to ignore certain columns from the restaurants table, you can do so by not including them in the RETURNS TABLE syntax and select only the columns you want to return from the restaurants table.

In this example, we only returns the id, name, email, and website columns from the restaurants table.

CREATE OR REPLACE FUNCTION get_restaurants_3()
  RETURNS TABLE (
    id INT,
    name TEXT,
    email TEXT,
    website TEXT
  ) AS $$
  BEGIN
    RETURN QUERY SELECT r.id, r.name, r.email, r.website FROM restaurants r;
  END;
$$ LANGUAGE plpgsql;

Function that returns a single value

You can also create a function that returns a single value. In this example, we return the total number of restaurants in the restaurants table.

CREATE OR REPLACE FUNCTION get_restaurants_count()
  RETURNS INT AS $$
  BEGIN
    RETURN (SELECT COUNT(*) FROM restaurants);
  END;
$$ LANGUAGE plpgsql;

Function that accepts arguments

You can also create a function that accepts arguments. In this example, we create a function that accepts a status argument and returns all the restaurants with that status.

CREATE OR REPLACE FUNCTION get_restaurants_by_status(r_status TEXT)
  RETURNS SETOF restaurants AS $$
  BEGIN
    RETURN QUERY SELECT * FROM restaurants WHERE status = r_status;
  END;
$$ LANGUAGE plpgsql;

You can invoke the function using Supabase client as follows.

const { data, error } = await supabase.rpc("get_restaurants_by_status", {
  r_status: "approved",
});

BoxyHQ + Cerbos: Merging SSO and Authorization

Kiran Krishnan — Mon, 24 Jul 2023 00:00:00 +0000

In this article, we will see how to enable Enterprise SSO login (based on the SAML single sign-on protocol) using Okta for your Next.js app and relay role-based access directly from the Identity Provider to Cerbos.

We'll be using BoxyHQ's open-source Enterprise SSO solution (called SAML Jackson) to interface with Okta. We'll use the principle of minimal UI and include only the necessary interface in our example application.

Introduction to SAML single sign-on

Security Assertion Markup Language (SAML) was designed for traditional web applications in the early 2000s. The goal was to provide a seamless user experience for applications by federating authentication to an IdP.

As a result, applications no longer had to maintain identities for users. All they had to do was to redirect the browser to the IdP which would then authenticate the user and return an assertion about the logged-in user.

This assertion in effect was a token, asserting to the app that the user authenticated at the IdP and the assertion is valid for the set period contained within it. You can read more about SAML and other SSO protocols here.

SAML continues to be a very popular choice of protocol when there's a need to provide a single sign-on (SSO) experience for an enterprise application. Microsoft has great resources explaining SAML authentication and SAML at a deeper level.

Benefits of using SAML

Increased Security

SAML is at its heart a security standard and as it provides a single point of authentication that takes place in a secure environment it adds an extra layer of security to your service that most enterprise customers will ask for.

Improved user experience

As a user, SAML is very simple and pleasant to use as you only have to log in once and then you can access all your external services on a dashboard with a single click. This saves the user time and makes their overall experience of your product better.

Reduces cost

Without SAML you have to maintain account information across multiple services but when you use SAML this is all managed by the IdP.

Introduction to BoxyHQ

BoxyHQ implements and maintains an open-source project that handles all the service provider functionality for implementing SAML, hiding away all the complexity you read about above behind the more popular and well-understood OAuth 2.0 protocol.

Introduction to Cerbos

Cerbos is the open-core, language-agnostic, scalable authorization solution that makes user permissions and authorization simple to implement and manage by writing context-aware access control policies for your application resources.

In this tutorial, we are using BoxyHQ as the service provider layer between our example Next.js application and Okta as the Identity Provider to showcase the benefits of syncing roles and permissions during SSO login.

Overview of the example app

The example app is a simple Next.js app that uses SAML Jackson for SAML SSO authentication and Cerbos for authorization.

The app has two pages:

/ - Display the authenticated user's profile and authorization decisions returned by Cerbos API.
/saml-connection - Update the SAML connection details.

The example app runs on port 3000. SAML Jackson and Cerbos are running on ports 5225 and 3593 respectively within Docker containers.

You are free to use cloud versions of Cerbos, the instructions for those wouldn’t change a lot but have been avoided in this article to keep it short.

The example app is configured to work with 2 roles: app-admin and app-user.

The app-admin role has access to all resources.
The app-user role has access to resources only the user owns.

Take a look at the cerbos/policies/contact.yaml file to see how the policies are defined for the example app. You can try changing the policies and see how the authorization decisions change in the app.

The following diagram shows the architecture of the example app.

1. Setup the example app

Clone the example app repository:

git clone https://github.com/boxyhq/jackson-cerbos

Navigate to the example app directory and run npm install to install the dependencies.

cd jackson-cerbos

npm install

If you navigate to http://localhost:3000 on your browser, you should see the following page.

This would mean that the example app is running successfully and you can now proceed to the next step.

The README file repository has all details about the example app. You can refer to it if you have anything unclear in this article.

2. Setup SAML App in Okta

The next step is to set up a SAML app in Okta. If you don't have an Okta account, you can create a free developer account https://developer.okta.com/signup/.

Alternatively, you can also use other SAML IdPs like Azure AD, OneLogin, Auth0, etc. The steps for those would be similar to the ones for Okta.

In this article, we will use Okta as the IdP.

If you are unfamiliar with creating a SAML app in Okta, you can follow the instructions here.

You will want to use the Assertion Consumer Service URL and Entity ID from http://localhost:5225/.well-known/saml-configuration.

Do not worry about the roles attribute yet, we’ll configure that in a later step once we have ensured the SSO login flow works correctly.

Next, download the SAML Metadata XML file from the Okta app. You will need this file in the next step.

3. Create a SAML connection in SAML Jackson

Now that we have the SAML app setup in Okta, we need to create a SAML connection in SAML Jackson.

Navigate to http://localhost:3000/saml-connection on your browser and paste the contents of the SAML Metadata XML file you downloaded in the previous step in the XML Metadata field. Click on Create SAML Connection to create the SAML connection.

If you see the status SAML SSO Enabled on the page, it means that the SAML connection was created successfully.

4. Login with SAML SSO

Now that we have the SAML connection setup, we can try logging in with SAML SSO.

Navigate to http://localhost:3000/login on your browser, enter the email address and click on Continue with SAML SSO.

You will be redirected to the Okta login page. Enter the credentials and click on Sign In.

You will be redirected back to the home page of the example app and you should see the Profile of the authenticated user.

This means that you have successfully logged in with SAML SSO.

Since we haven't configured the roles attribute yet, all the users will be assigned the app-user role by default.

5. Configure the groups attribute in Okta App

Now that we have ensured that the SSO login flow works correctly, we can configure the groups attribute in Okta.

Groups attribute allows you to map the groups in your identity provider to the roles in your application.

Create a group in Okta

First, we need to create a group in Okta. Navigate to the Directory > Groups from the left navigation menu.

Click on Add group and enter the group name and description (optional)

Next create two new groups: app-admin and app-user.

After creating the groups, you will see the groups listed in the Groups page.

Next we need to add the users to the groups. Navigate to the group you just created and click on the People tab.

Click on the Assign people button and assign the users you want to add to the group.

Repeat the same steps for the second group.Configure the groups attribute in Okta

Now that we have created the groups in Okta, we need to configure the groups attribute in Okta.

Navigate to the SAML Settings tab in the Okta app and click on Edit.

Now click on the Configure SAML tab and scroll down to the Group Attribute Statements section.

Click on Add Another and enter the following values

Name: groups
Name format: Unspecified
Filter: Starts with app-

Note the app- prefix in the filter. This will ensure that only the groups that start with app- are returned in the SAML response from Okta. So if you have other groups in Okta, they will not be returned in the SAML response. This is useful if you want to map only a subset of the groups in Okta to the roles in your application.

There are also other filter options available in the Group Attribute Statements section. You can read more about them in the Okta documentation.

6. Test the authorization

Now that we have configured the group attribute, we can test the authorization.

Navigate to http://localhost:3000 on your browser and click the Sign Out button.

Let's try logging in with a user that has the app-admin role.

You will be redirected to the Okta login page. Enter the credentials and click on Sign In.

You will be redirected back to the home page of the example app and you should see the Profile of the authenticated user.

Access API authorized by Cerbos

In the Access API authorized by Cerbos section, we've added a table to display Cerbos authorization decisions for the authenticated user for the resources in the example app.

Here is the overview of the policies defined in the cerbos/policies/contact.yaml file.

A user with the app-admin role can perform all actions on all resources.
A user with the app-user role can perform read and update actions on resources they own.

resourcePolicy: version: default resource: contact rules: - actions: ['read', 'create', 'update', 'delete'] effect: EFFECT_ALLOW roles: - app-admin - actions: ['read', 'update'] effect: EFFECT_ALLOW roles: - app-user condition: match: expr: request.resource.attr.author == request.principal.id

Guarded Routes

In the Guarded Routes section at the bottom of the page, we've added 3 routes to showcase how Cerbos can be used to guard routes in your application.

Route the Admin user role can access: Can be accessed by the user with the app-admin role.
Route the User and Admin user roles can access: Can be accessed by the user with the app-user or app-admin role.
Route the User does not have access to: Can be accessed by the user who owns the resource.

Closing thoughts

In this article, we have seen how to integrate SAML SSO with Jackson and Cerbos. We have implemented authentication and authorization using SAML SSO, Jackson and Cerbos.

This opens up whole new possibilities for enterprise apps using Jackson and Cerbos. I’d love to hear of all the cool apps and features you are going to build, please reach out to Jackson or Cerbos if you found this article useful.

Access the source code for this article here: https://github.com/boxyhq/jackson-cerbos

Learn More

To learn more about SAML Jackson and Cerbos, take a look at the following resources:

boxyhq / jackson

🔥 Streamline your web application's authentication with Jackson, an SSO service supporting SAML and OpenID Connect protocols. Beyond enterprise-grade Single Sign-On, it also supports Directory Sync via the SCIM 2.0 protocol for automatic user and group provisioning/de-provisioning. 🤩

SAML Jackson: Open Source Enterprise SSO And Directory Sync

We now also support OpenID Connect providers.

Directory Sync

SAML Jackson also supports Directory Sync based on the SCIM 2.0 protocol.

For complete documentation, visit boxyhq.com/docs/directory-sync/overview

🌟 Why star this repository?

If you find this project helpful, please consider supporting us by starring the repository and sharing it with others. This helps others find the project…

View on GitHub

How to Build a Custom Raycast Extension to Access Dev.to Articles

Kiran Krishnan — Sat, 25 Feb 2023 18:41:05 +0000

In this tutorial, we will build a custom Raycast extension that fetches the latest articles from Dev.to and displays them in a list and opens the selected article in the browser.

Visit the Raycast Doc to learn more about the system requirements you need to start building extensions.

Create a new extension

Open the Create Extension command in Raycast
Choose the Template Static List
Name your extension Devto Articles
Name the command Latest Articles
Click Create Extension from the bottom right corner

This will create a new directory called devto-articles in your extensions directory.

Install the dependencies

Now, let's dive into the code.

Open the extension directory devto-articles in your favorite code editor.

Install the dependencies by running the following command:

npm install

Before continuing, let's install the @raycast/api package. It contains a set of components that make it easier to build extensions.

npm install @raycast/utils

Build the extension

Now we are ready to start building the extension.

Open the src/index.tsx file, this is where we will write the code that fetches the latest articles from Dev.to and displays them in a list.

Remove the existing code from the src/index.tsx so that we can start from scratch.

Now, let's import the useFetch hook from @raycast/utils. useFetch can be used to fetch data from an API.

import { ActionPanel, Action, List } from "@raycast/api";
import { useFetch } from "@raycast/utils";

Define the type of the article object to map the response from the API.

type Article = {
  id: number;
  title: string;
  readable_publish_date: string;
  comments_count: number;
  url: string;
};

Now, let's use the useFetch hook to fetch the latest articles from Dev.to.

export default function Command() {
  const { isLoading, data: articles } = useFetch<Article[]>(
    "https://dev.to/api/articles"
  );
}

useFetch returns an object with two properties: isLoading and data.

isLoading is a boolean that indicates whether the data is being fetched or not.
data is the response that is fetched from the API.

Now, let's use the List component to display the articles in a list.

return (
  <List isLoading={isLoading}>
    {(articles || []).map((article) => (
      <List.Item
        key={article.id}
        icon="list-icon.png"
        title={article.title}
        subtitle={`${article.comments_count} comments`}
        accessories={[{ text: article.readable_publish_date }]}
        actions={
          <ActionPanel>
            <Action.OpenInBrowser url={article.url} />
          </ActionPanel>
        }
      />
    ))}
  </List>
);

The List component takes an isLoading prop that indicates whether the data is being fetched or not.

It also takes a children prop that is an array of List.Item components.

The ActionPanel is a component that contains a set of actions that can be performed on the selected item.

In our case, we want to open the selected article in the browser. So, we will use the Action.OpenInBrowser component to open the article in the browser when the user selects it.

Here is the final code:

import { ActionPanel, Action, List } from "@raycast/api";
import { useFetch } from "@raycast/utils";

type Article = {
  id: number;
  title: string;
  readable_publish_date: string;
  comments_count: number;
  url: string;
};

export default function Command() {
  const { isLoading, data: articles } = useFetch<Article[]>(
    "https://dev.to/api/articles"
  );

  return (
    <List isLoading={isLoading}>
      {(articles || []).map((article) => (
        <List.Item
          key={article.id}
          icon="list-icon.png"
          title={article.title}
          subtitle={`${article.comments_count} comments`}
          accessories={[{ text: article.readable_publish_date }]}
          actions={
            <ActionPanel>
              <Action.OpenInBrowser url={article.url} />
            </ActionPanel>
          }
        />
      ))}
    </List>
  );
}

Run the extension

You can run the extension by running the following command:

npm run dev

Find the extension in Raycast by searching for Devto Articles and run the command Latest Articles.

How to validate Next.js API routes using Zod

Kiran Krishnan — Wed, 22 Feb 2023 17:18:58 +0000

In this article, you'll learn how to validate Next.js API routes using Zod.

Let's create a new file called /api/users.ts. The API endpoint /api/users will accept POST requests with a JSON body.

import type { NextApiRequest, NextApiResponse } from "next";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const { method } = req;

  if (method !== "POST") {
    res.setHeader("Allow", ["GET", "POST"]);
    res.status(405).json({
      error: { message: `Method ${method} Not Allowed` },
    });
  }

  // Validate the request body

  return res.status(200).json({ message: "Success" });
}

Install Zod

Let's install Zod using npm.

npm install zod

Create the schema

Next, we will create the schema to represent the request body.

import { z } from "zod";

const schema = z.object({
  name: z.string(),
  email: z.string(),
  zipcode: z.number().min(5).max(5),
  subcribe: z.boolean().optional(),
});

The sample request body will look like this:

{
  "name": "Kiran",
  "email": "kiran@example.com",
  "zipcode": "12345",
  "subcribe": true // optional
}

Validate the request body

Next step is to validate the request body using the above schema. We will use the safeParse method to validate.

const response = schema.safeParse(req.body);

// If the request body is invalid, return a 400 error with the validation errors
if (!response.success) {
  const { errors } = response.error;

  return res.status(400).json({
    error: { message: "Invalid request", errors },
  });
}

// Now you can safely use the data to create a user
const { name, email, zipcode, subcribe } = response.data;

If the request validation fails, we will return a 400 status code with the validation errors. You can access the validation errors using the errors property on the JSON response.

Here is how the response will look like if the request body is invalid:

{
  "error": {
    "message": "Invalid request",
    "errors": [
      {
        "validation": "email",
        "code": "invalid_string",
        "message": "Invalid email",
        "path": ["email"]
      }
    ]
  }
}

You can use the library Zod Error to convert the validation errors to a more readable format.

Here is the full code for the API endpoint:

import type { NextApiRequest, NextApiResponse } from "next";
import { z } from "zod";

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const { method } = req;

  if (method !== "POST") {
    return res.status(405).json({
      error: { message: `Method ${method} Not Allowed` },
    });
  }

  const schema = z.object({
    name: z.string(),
    email: z.string().email(),
    zipcode: z.string().min(5).max(5),
    subcribe: z.boolean().optional(),
  });

  const response = schema.safeParse(req.body);

  if (!response.success) {
    const { errors } = response.error;

    return res.status(400).json({
      error: { message: "Invalid request", errors },
    });
  }

  const { name, email, zipcode, subcribe } = response.data;

  return res.status(200).json({ message: "Success" });
}

Here is the curl command to test the API endpoint:

curl --request POST \
  --url http://localhost:3000/api/users \
  -H 'Content-Type: application/json' \
  --data '{"name":"Kiran","email":"kiran@example.com","zipcode":"12345","subcribe":false}'

If you're planning to build a SaaS app, then you might be interested in NextAPI. NextAPI is a Next.js RESTful API Starter for building SaaS Apps. NextAPI can handle the heavy lifting for common SaaS features such as authentication, team management, invites, subscriptions, and more.

NextAPI - A Next.js RESTful API Starter for building SaaS Apps

Kiran Krishnan — Thu, 09 Feb 2023 11:15:46 +0000

NextAPI is a Next.js RESTful API Starter designed specifically for building SaaS apps.

NextAPI is a great starting point for anyone looking to build a SaaS app with Next.js.

Look no further than NextAPI if you want to build a SaaS application with a fully functional backend in minutes.

Learn more about NextAPI

With its powerful combination of Next.js, Supabase, and Prisma, it provides the perfect foundation for creating scalable and feature-rich SaaS apps.

One of the biggest advantages of using NextAPI is that it takes care of the heavy lifting for common SaaS features such as authentication, team management, invites, subscriptions, and more.

NextAPI is currently in beta. Please report any bugs or issues you encounter on GitHub.

Built with

Features

Authentication
Team Management
Team Invites
Subscriptions (Coming soon)

API routes

NextAPI comes with a set of API routes that you can use within your React components.

Method	Path	Description
POST	/api/auth/signup	Sign up a new user
POST	/api/auth/signin	Sign in an existing user
POST	/api/teams	Create a new team
GET	/api/teams	Get all teams for user
GET	/api/teams/:slug	Get a team
DELETE	/api/teams/:slug	Delete a team
PUT	/api/teams/:slug	Update a team
POST	/api/teams/:slug/invites	Create a new invite
GET	/api/teams/:slug/invites	Get all invites for team
GET	/api/teams/:slug/invites/:inviteId	Get an invite
DELETE	/api/teams/:slug/invites/:inviteId	Delete an invite
GET	/api/teams/:slug/members	Get all members for team
PUT	/api/teams/:slug/members/:memberId	Update a member
DELETE	/api/teams/:slug/members/:memberId	Delete a member
GET	/api/me	Get current user
PUT	/api/me	Update current user
POST	/api/invites/:inviteId/accept	Accept an invite
POST	/api/invites/:inviteId/decline	Reject an invite

API Documentation

Emails are sent for the following events

When a new user signs up
When a new invite is created
When a user is added to a team
When a user is removed from a team

Getting started

Fork this repository
Clone your forked repository
Navigate to the project directory
Run npm install to install dependencies
Run npm run dev to start the development server

Sending Emails with React Email and Next.js

Kiran Krishnan — Sat, 21 Jan 2023 16:59:19 +0000

In this tutorial, we will learn how to create and send HTML emails with React Email and Next.js

Prerequisites

Getting Started

Let's start with a new Next.js project. You can use the Next.js CLI to create a new project.

npx create-next-app next-email --ts

Wait for the project to be created. Once the project is created, let's move into the project directory.

cd next-email

Create Email Template

We will use the React Email to create a new email template.

Let's install dependencies.

npm install react-email @react-email/html @react-email/text @react-email/section @react-email/container -E

Now, let's create a new email template using the React Email components. This is a simple React component that will be converted to HTML email template.

We will create a new file emails/WelcomeTemplate.tsx and add the following code.

import { Html } from "@react-email/html"
import { Text } from "@react-email/text"
import { Section } from "@react-email/section"
import { Container } from "@react-email/container"

export default function WelcomeEmail() {
  return (
    <Html>
      <Section style={main}>
        <Container style={container}>
          <Text style={heading}>Hi there!</Text>
          <Text style={paragraph}>Welcome to our app!</Text>
        </Container>
      </Section>
    </Html>
  )
}

// Styles for the email template
const main = {
  backgroundColor: "#ffffff",
}

const container = {
  margin: "0 auto",
  padding: "20px 0 48px",
  width: "580px",
}

const heading = {
  fontSize: "32px",
  lineHeight: "1.3",
  fontWeight: "700",
  color: "#484848",
}

const paragraph = {
  fontSize: "18px",
  lineHeight: "1.4",
  color: "#484848",
}

Preview Email Template

Add the following script in your package.json file.

{
  "scripts": {
    "preview-email": "email dev"
  }
}

Now, you can preview your email template by running the following command.

npm run preview-email

This will start a local server and open your email template in the browser.

Send Email with Nodemailer

Let's install Nodemailer.

npm install nodemailer

npm i --save-dev @types/nodemailer

Create a new helper file lib/email.ts and add the following code. This will take care of sending emails using Nodemailer and the SMTP server.

Find the source code on GitHub

import nodemailer from "nodemailer"

type EmailPayload = {
  to: string
  subject: string
  html: string
}

// Replace with your SMTP credentials
const smtpOptions = {
  host: process.env.SMTP_HOST || "smtp.mailtrap.io",
  port: parseInt(process.env.SMTP_PORT || "2525"),
  secure: false,
  auth: {
    user: process.env.SMTP_USER || "user",
    pass: process.env.SMTP_PASSWORD || "password",
  },
}

export const sendEmail = async (data: EmailPayload) => {
  const transporter = nodemailer.createTransport({
    ...smtpOptions,
  })

  return await transporter.sendMail({
    from: process.env.SMTP_FROM_EMAIL,
    ...data,
  })
}

Make sure your .env file contains the following environment variables.

SMTP_HOST=
SMTP_PORT=
SMTP_USER=
SMTP_PASSWORD=
SMTP_FROM_EMAIL=

Now, let's create a new file pages/api/send-email.ts and add the following code.

import type { NextApiRequest, NextApiResponse } from "next"
import { render } from "@react-email/render"
import WelcomeTemplate from "../../emails/WelcomeTemplate"
import { sendEmail } from "../../lib/email"

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  await sendEmail({
    to: "kiran@example.com",
    subject: "Welcome to NextAPI",
    html: render(WelcomeTemplate()),
  })

  return res.status(200).json({ message: "Email sent successfully" })
}

Now you can visit http://localhost:3000/api/send-email to send the email.

HelpUp: Knowledge Base / Help Center Builder

Kiran Krishnan — Wed, 07 Dec 2022 19:18:29 +0000

What I built

HelpUp - A simple knowledge base builder. It helps you build a knowledge base for your customer support team. It is a self-hosted solution that you can deploy on your own infrastructure. It is built using Next.js, Supabase and MongoDB.

Category Submission

Search No More: Build an application with full-text search capabilities using MongoDB Atlas and Atlas Search

App Link

https://helpup.vercel.app/

Demo HelpCenter for a E-commerce Store

Screenshots

Backend
Watch demo

Frontend
Watch demo

Description

HelpUp is a simple knowledge base builder. It helps you build a knowledge base for your customer support team. You can add as many workspaces as you want. Each workspace has its own set of articles. You can group articles into collections. You can search articles by title, content.

Here are some of the features of the app.

Create an account
Create and manage workspaces
Create and manage collections
Create and manage articles
Customize the landing page of the help center
Search articles by title and content
Autocomplete search title
Highlight search term in the article content
Allow users to share feedback on the article

Link to Source Code

Github

Permissive License

MIT

How I built it

I built the app using Next.js, Supabase, and MongoDB. I used MongoDB Atlas to store and query the data.

Let's take a look at the important parts of the app.

Search articles

I created a MongoDB Atlas Search Index searchArticles to search the articles. I used the following mapping for the index.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "contentText": {
        "type": "string"
      },
      "title": {
        "type": "string"
      },
      "workspaceId": {
        "type": "objectId"
      }
    }
  },
  "storedSource": {
    "include": ["workspaceId"]
  }
}

Then created a Atlas Function to search the articles. It is a simple function that takes the searchTerm and workspaceId as input and returns the search results. Here is the code for the function.

exports = function ({ query, headers, body }, response) {
  const { searchTerm, workspaceId } = query;

  const docs = context.services
    .get("mongodb-atlas")
    .db("helpup")
    .collection("Article")
    .aggregate([
      {
        $search: {
          index: "searchArticles",
          compound: {
            must: [
              {
                text: {
                  query: searchTerm,
                  path: ["title", "contentText"],
                },
              },
            ],
            filter: [
              {
                equals: {
                  value: new BSON.ObjectId(workspaceId),
                  path: "workspaceId",
                },
              },
            ],
          },
        },
      },
      {
        $project: {
          _id: 0,
          title: 1,
          slug: 1,
          contentText: 1,
          updatedAt: 1,
        },
      },
    ]);

  return docs;
};

Then I created a HTTPS Endpoint /searchArticles to call the above Atlas Function. I called this endpoint from Next.js getServerSideProps function to get the search results. Here is the code to invoke the endpoint.

const url = new URL(`${process.env.NEXT_PUBLIC_ATLAS_APP_URL}/searchArticles`);

url.searchParams.set("searchTerm", searchTerm);
url.searchParams.set("workspaceId", workspaceId);

const response = await fetch(url, {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
  },
});

const articles = await response.json();

Autocomplete search

I created another MongoDB Atlas Search Index autocompleteArticles to autocomplete the search title. I used the following mapping for the index.

{
  "mappings": {
    "dynamic": false,
    "fields": {
      "title": {
        "type": "autocomplete"
      },
      "workspaceId": {
        "type": "objectId"
      }
    }
  },
  "storedSource": {
    "include": [
      "workspaceId"
    ]
  }
}

Created a new Atlas Function to autocomplete the search title. It is a simple function that takes the searchTerm and workspaceId as input and returns the search results.

exports = function ({ query, headers, body }, response) {
  const { searchTerm, workspaceId } = query;

  const docs = context.services
    .get("mongodb-atlas")
    .db("helpup")
    .collection("Article")
    .aggregate([
      {
        $search: {
          index: "autocompleteArticles",
          compound: {
            must: [
              {
                autocomplete: {
                  query: searchTerm,
                  path: "title",
                },
              },
            ],
            filter: [
              {
                equals: {
                  value: new BSON.ObjectId(workspaceId),
                  path: "workspaceId",
                },
              },
            ],
          },
        },
      },
      {
        $project: {
          _id: 0,
          title: 1,
          slug: 1,
          contentText: 1,
          updatedAt: 1,
        },
      },
    ]);

  return docs;
};

I created another HTTPS Endpoint /autocompleteArticles to call the above Atlas Function. I called this endpoint from the client-side to get the autocomplete search results.

Here is the link to the search and autocomplete code

Enterprise-ready SaaS Starter Kit

Kiran Krishnan — Tue, 27 Sep 2022 00:00:00 +0000

Enterprise-ready SaaS Starter Kit is a Next.js based SaaS Starter Kit that can save hundreds of development hours while building enterprise-ready SaaS apps.

Kickstart your enterprise app development with Next.js SaaS Starter Kit

Let's look at some of the enterprise-ready features the SaaS kit offers.

SAML SSO

SAML stands for Security Assertion Markup Language. It is an XML-based open standard for transferring identity data between an identity provider (IdP) and a service provider (SP).

Single Sign On (SSO) allows your customers to manage their team's users outside your built-in user table.

SAML SSO is integrated with the help of SAML Jackson

Directory Sync (SCIM)

Directory sync helps organizations automate the provisioning and de-provisioning of their users.

As a result, it streamlines the user lifecycle management process by saving valuable organizational hours, creating a single truth source of the user identity data, and facilitating them to keep the data secure.

Directory Sync is integrated with the help of SAML Jackson

Webhooks & Events

Webhooks are a way for systems to notify external applications that a specific event has occurred in your SaaS app without receiving a request.

Webhooks are a great solution if the client does not know when an event will occur and wants to be notified in real-time.

Webhook is integrated with the help of Svix

Team Management

Teams describe the functionality that enables modern software to be coordinated and managed.

Through Teams, SaaS app users invite others to collaboratively use the application with them by creating an account.

Other Features

Let's also look at other standard features the SaaS kit offers.

Create account
Sign in with Email and Password
Sign in with Magic Link
Update account
Manage team
Manage team members
Invite users to the team
Accept invitation

Getting Started

Please follow these simple steps to get a local copy up and running.

1. Setup

Clone or fork this GitHub repository

git clone https://github.com/boxyhq/saas-starter-kit.git

2. Go to the project folder

cd saas-starter-kit

3. Install dependencies

npm install

4. Set up your .env file

Duplicate .env.example to .env.

cp .env.example .env

5. Set up database schema

npx prisma db push

6. Start the server

In a development environment:

npm run dev

7. Start the Prisma Studio

Prisma Studio is a visual editor for the data in your database.

npx prisma studio

Contributing guide

Contributions make the open-source community a fantastic place to learn, inspire, and create. Any contributions you make are greatly appreciated.

We also invite new supporters to contribute to the repository if you are interested.

Open-source Next.js SaaS Starter Kit

Kiran Krishnan — Wed, 21 Sep 2022 03:25:46 +0000

Enterprise SaaS Starter Kit

Recently we (BoxyHQ) launched an open-source Enterprise SaaS Starter Kit on GitHub. This repository is still in an early stage of development.

Kickstart your enterprise app development with Next.js SaaS Starter Kit

It is Next.js based project that saves you months of development by starting you off with all the same features in every SaaS app, so you can focus on what makes your app unique.

Getting Started

Please follow these simple steps to get a local copy up and running.

Prerequisites

Node.js (Version: >=15.x <17)
PostgreSQL
NPM

1. Setup

Clone or fork this GitHub repository

git clone https://github.com/boxyhq/saas-starter-kit.git

2. Go to the project folder

cd saas-starter-kit

3. Install dependencies

npm install

4. Set up your .env file

Duplicate .env.example to .env.

cp .env.example .env

5. Set up database schema

npx prisma db push

6. Start the server

In a development environment:

npm run dev

7. Start the Prisma Studio

Prisma Studio is a visual editor for the data in your database.

npx prisma studio

Features

The app supports the following features as of now.

Create account
Sign in with Email and Password
Sign in with Magic Link
Sign in with SAML SSO
Directory Sync (SCIM)
Update account
Create team
Invite users to the team
Manage team members
Update team settings
Configure SAML SSO

Coming Soon

Audit logs
Unit and integration tests
Dark mode
Mobile-first UI
Billing & subscriptions
Internationalization
Roles and Permissions

Contributing

Contributions make the open-source community a fantastic place to learn, inspire, and create. Any contributions you make are greatly appreciated.

We also invite new supporters to contribute to the repository if you are interested.

Here are some open issues.

Discover a collection of SaaS Starter Kits based on Next.js, Supabase, React.js, Remix, Ruby on Rails, Laravel, and Go.

DEV Community: Kiran Krishnan

Adding SAML Single Sign-On to an Express App: A Step-by-Step Guide 🚀🚀

boxyhq / jackson

🔥 Streamline your web application's authentication with Jackson, an SSO service supporting SAML and OpenID Connect protocols. Beyond enterprise-grade Single Sign-On, it also supports Directory Sync via the SCIM 2.0 protocol for automatic user and group provisioning/de-provisioning. 🤩

SAML Jackson: Open Source Enterprise SSO And Directory Sync

Directory Sync

🌟 Why star this repository?

Prerequisites

Setting up the database

Configure the Identity Provider

Getting started

About the Express app

Install SAML Jackson

Setting up Express.js routes

Add SAML Metadata

Redirect the users to IdP

Handle the SAML Response from IdP

Code exchange

Protect the dashboard

Conclusion

References

9 Next.js Open Source Projects for Contributions 🚀🚀

dubinc / dub

The modern link attribution platform. Loved by world-class marketing teams like Twilio, Buffer, Framer, Perplexity, Vercel, and more.

Dub

Introduction

Tech Stack

Self-Hosting

Contributing

calcom / cal.com

Scheduling infrastructure for absolutely everyone.

Cal.com (formerly Calendso)

About the Project

Scheduling infrastructure for absolutely everyone

Recognition

Built With

Contact us

Stay Up-to-Date

documenso / documenso

The Open Source DocuSign Alternative.

About Documenso

Recognition

Community and Next Steps 🎯

formbricks / formbricks

Open Source Qualtrics Alternative

Formbricks

✨ About Formbricks

💪 Mission: Empower your team, craft an irresistible experience.

Table of Contents

Features

boxyhq / saas-starter-kit

🔥 Enterprise SaaS Starter Kit - Kickstart your enterprise app development with the Next.js SaaS boilerplate 🚀

⭐ Enterprise SaaS Starter Kit

📖 Additional Resources

🛠️ Built With

supabase / supabase

The open source Firebase alternative. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

Supabase

Documentation

Community & Support

How it works

unkeyed / unkey

Open source API management platform

Unkey

Open Source API authentication and authorization

Contributing

Let's talk

Authors

Stats

baptisteArno / typebot.io

💬 Typebot is a powerful chatbot builder that you can self-host.

Try Typebot • Docs

Builder demo

Features

openstatusHQ / openstatus

🏓 The open-source synthetic monitoring platform 🏓

OpenStatus

About OpenStatus 🏓

Recognitions 🏆

Contact us 💌

Introduction to SAML single sign-on

Benefits of using SAML

Increased Security

Improved user experience

Reduces cost

Introduction to BoxyHQ

Introduction to Cerbos

Overview of the example app

1. Setup the example app

2. Setup SAML App in Okta

3. Create a SAML connection in SAML Jackson

4. Login with SAML SSO

5. Configure the groups attribute in Okta App

Create a group in Okta

6. Test the authorization

Access API authorized by Cerbos

Guarded Routes

Closing thoughts

Learn More