Integrate Authentication System

[Wajahat43]

Integrate Authentication System

We need to add an authentication system to support user accounts, roles, and potentially permissions. This will serve as foundational infrastructure for upcoming features.

Requirements

Authentication

• Support sign-in and sign-up flows.
• Potentially allow accounts approval before then being functional?

Authorization

• Support role-based access.
• Permission-level access is preferred but not strictly required.

Cost

• Must be able to support our users for free.

Options Under Consideration

1. Clerk

• Free tier includes 10,000 users.
• Simple integration.
• Supports role creation and management.

2. WorkOS

• Free tier includes 1,000,000 users.
• Pricing: https://workos.com/pricing
• Next.js AuthKit docs: https://workos.com/docs/authkit/nextjs/1-configure-your-project

3. Auth0

• Well-established.
• Free tier available, though more limited than others.

4. Custom Auth implementation.

• Will be most flexible.

Evaluation Criteria

• Ease of integration with existing tech stack
• Role/permission capabilities
• Free tier limits and long-term cost
• Developer experience
• Maintainability and vendor lock-in risk

Proposed Next Steps

• Compare Clerk, WorkOS, and Auth0 based on criteria above
• Create a comparison table of pros/cons
• Select the preferred provider
• Implement sign-in/sign-up functionality
• Add role support (and permissions if possible)
• Document integration steps

[alikhan0616]

Feature Proposal: Authentication System Integration

Summary

We need to integrate an authentication provider to support user accounts, role-based access, and an approval workflow. This will serve as the foundational infrastructure for upcoming features.

Based on our requirements (Free Tier, Approval Flow, Roles), I recommend we proceed with Clerk.

---

1. Evaluation of Options

We compared Clerk, WorkOS, and Auth0 against our specific criteria.

Feature	Clerk 🏆	WorkOS (AuthKit)	Auth0
Free Tier Limit	10,000 MAU	1,000,000 MAU	25,000 MAU
Account Approval	✅ Native (Waitlist Mode)	⚠️ Manual (Middleware)	⚠️ Manual (Actions Code)
RBAC (Roles)	✅ Native (Free Tier)	⚠️ Basic	❌ Paid/Complex
Ease of Integration	⭐⭐⭐⭐⭐ (Next.js First)	⭐⭐⭐⭐	⭐⭐⭐
Maintenance	Low (Managed UI)	Low	Medium

Why Clerk?

1. Solves "Account Approval" natively: Clerk has a built-in Waitlist Mode. We can allow users to sign up, but they remain in a "pending" queue until an admin approves them in the dashboard. Other providers require building custom database tables (isApproved) and middleware logic to achieve this.
2. Granular Roles: Clerk allows us to assign metadata (Roles) easily within the free tier.
3. Speed: We can integrate the core flow in less than a day using their Next.js SDK.

---

2. Implementation Plan

Phase A: Sign-In & Approval Flow (The Waitlist)

To fulfill the requirement of "allowing account approval before functionality," we will utilize Clerk's Waitlist component instead of a direct Sign-Up form.

1. Configuration: Enable "Waitlist Mode" in the Clerk Dashboard.
2. Frontend Integration: Replace the Sign-Up page with the <Waitlist /> component.
3. The Flow:
   • User fills out the form → Added to Clerk Queue.
   • Admin approves user → Clerk sends an invite email.
   • User clicks link → Account is created and they can Sign In.

Phase B: Middleware Protection

We will add middleware.ts to protect our application routes, ensuring only authenticated users can access the platform.

// middleware.ts
import { clerkMiddleware, createRouteMatcher } from "@clerk/nextjs/server";

const isProtectedRoute = createRouteMatcher(['/dashboard(.*)', '/forum(.*)']);

export default clerkMiddleware((auth, req) => {
  if (isProtectedRoute(req)) auth().protect();
});

export const config = {
  matcher: ["/((?!.*\\..*|_next).*)", "/", "/(api|trpc)(.*)"],
};

Phase C: Role Support

We will implement Role-Based Access Control (RBAC) using User Metadata.

• Role Definition: We will define roles such as admin, member, and guest.
• Usage: We can check roles in Server Components to show/hide UI features.

import { auth } from '@clerk/nextjs/server';

export default function Dashboard() {
  const { sessionClaims } = auth();
  
  // Check if user has the specific role
  if (sessionClaims?.metadata.role === 'admin') {
    return <AdminPanel />;
  }
  return <UserView />;
}

---

3. 🚩 Open Questions for Discussion

Before I start the implementation, I need input on Roles and Approval Logic regarding our Circles (DSA, Open Source, etc.).

Question 1: Roles vs. Circles Structure

How do roles interact with our specific communities (Circles)?

• Option A: Global Roles

  • Description: A user is simply an Admin or Member of the entire platform. "DSA" or "Open-Source" are just tags they follow.
  • Pros: Simple to implement.
  • Cons: A user cannot be a "Lead" in the DSA circle while being a regular "Member" in the Open-Source circle.

• Option B: Scoped Roles (Clerk Organizations)

  • Description: We treat each Circle as a separate "Organization." A user can join the DSA Org as an Admin and the Open-Source Org as a Member.
  • Pros: Highly flexible and scales if circles operate independently.
  • Cons: Adds complexity to the UI (users have to "switch" contexts).

Question 2: Approval Criteria

Since we are manually approving users via the Waitlist:

• What is the rubric for approval? (e.g., specific university email domains? valid student IDs?)
• Do we need to add a custom field to the Waitlist form (e.g., "Why do you want to join?") to help us make approval decisions?

---

✅ Proposed Next Steps

• Initialize Clerk project and API keys.
• Enable Waitlist mode in Clerk Dashboard.
• Team Decision: Select Option A or Option B for Roles/Circles.

[Wajahat43]

Answer to your questions

1. We should have global roles and each user can have multiple roles. For example Admin, CoreMember, Mentor, Mentee. For circles, CoreMembers can create circles. And then add admins of circle. To store admins of circle we can create db table.
2. Approval Criteria can be set later but I believe it will be accepted mentees only.

With that said, I would like to explore more if we can integrate WorkOs instead of Clerk since it will provide us more generous limits on the number of free user accounts (1 million vs 10 thousand).

According to my initial research on WorkOs:

1. We can disable public sign up. Have an invite only workflow, where we invite users by entering their email in WorkOs dashboard. Or we can create a simple form where admins will be able to enter a list of emails to invite. WorkOs will then handle the invitations and sign up etc. https://workos.com/docs/authkit/invite-only-signup
2. WorkOs also provides RBAC functionality. https://workos.com/docs/rbac

Please explore if both of these options are free. If yes, then I believe we should move with WorkOs integration. @alikhan0616.

[alikhan0616]

Re: WorkOS Integration & Circle Architecture

@Wajahat43 Great finding on the WorkOS limits.

I have verified the pricing and you are correct; the 1 million MAU free tier versus Clerk's 10k limit is a massive difference that allows us to scale without cost concerns. The "Invite Only" flow also perfectly solves our "Approval" requirement since we can simply invite accepted mentees directly.

I support moving to WorkOS.

Regarding the implementation of Circles, I have a suggestion to further simplify our database schema:

Recommendation: Use WorkOS Organizations for Circles

Instead of building a custom database table to store Circle Admins, I propose we use WorkOS Organizations.

1. Global Roles: We can use WorkOS User Roles for platform-level permissions (e.g. Mentor, CoreMember).
2. Circles as Organizations: We treat each Circle as a distinct "Organization" within WorkOS.
3. Circle Permissions: When a user creates a Circle, we automatically make them the Admin of that Organization in WorkOS.

Benefits of this approach:

• No Custom Auth Tables: We do not need to maintain a separate circle_admins table or write complex logic to check permissions.
• Native Checks: We can use the native WorkOS API to check organization_membership to see if a user is an admin of a specific circle.
• Scalability: WorkOS Organizations are free and unlimited, so this scales indefinitely without extra cost.

Let me know if you agree with this "Organization-as-Circle" approach or if you prefer the custom DB route.

[Wajahat43]

Great! Let's implement Auth using WorkOs then.

For circles functionality, I don't believe we need to use WorkOs organizations here. We will need to keep track of members of a circle, we can easily keep an extra field with it to indicate whether the member can modify circle or whether they have read only access.

This achieves our goal of keeping functionality simple while also using WorkOs only for Auth. We maintain the control over our business use-case.

[alikhan0616]

Re: WorkOS Integration Plan

That sounds like a solid plan.

I agree that keeping the circle membership logic within our own database gives us better long-term control and flexibility over the data model (e.g., adding custom permission levels or metadata later on) without tying it strictly to the auth provider's structure.

Summary of Decisions:

1. Auth Provider: WorkOS (Free Tier).
2. Sign-up Flow: Invite-only (Admins trigger invites via WorkOS). Emails for which can be obtained via google forms or any such application.
3. Circle Logic: Custom database implementation (handling members & permissions internally).

Task Allocation & Next Steps

Before we start, how should we divide the setup tasks?

• Project Setup: Who should create the WorkOS project/organization and generate the API keys?
• Implementation: Do you want me to handle the full integration (Auth + Database Schema for circles), or should we split it? For example:
  • Person A: Sets up WorkOS SDK & Invite Flow.
  • Person B: Sets up the Database Schema & API for Circles.

Let me know what works best for you!

[Wajahat43]

@junaiddshaukat Please help with setting up WorkOs org and generating the API keys.

Let's focus only on WorkOs integration. We have a separate issue for circles.

[junaiddshaukat]

@Wajahat43 sure, can you explain me the whole process?

[alikhan0616]

@junaiddshaukat, Here is the step-by-step process to set up our WorkOS environment and generate the keys we need for development.

1. Create Account & Organization

1. Go to workos.com/signup and create an account.
2. Once logged in, you will be prompted to create an Organization. Name it something like [ProjectName]-Dev.
   • Note: WorkOS has "Staging" and "Production" environments. We will be working in Staging (Test) mode for now.

2. Enable AuthKit

We need to enable the authentication product specifically.

1. In the left sidebar, click on Authentication (sometimes labeled "User Management" or "AuthKit").
2. Click "Set up AuthKit".
3. Important: In the settings, find the "Sign Up" configuration.
   • ❌ Disable "Public Sign-up" (Turn it OFF).
   • Reason: This ensures only users we explicitly invite can access the app, matching our project requirements.

3. Get API Keys

We need two specific keys to connect our Next.js app.

1. In the left sidebar, click on API Keys.
2. Client ID: Copy the key that starts with client_....
3. Secret Key: Click "Generate API Key" (or copy the default Secret Key). It starts with sk_test_....

4. Configure Redirect URI (For Localhost)

For the login flow to work on our machines, we need to whitelist our local URL.

1. Go to Redirects in the sidebar.
2. Click "Add Redirect URI".
3. Enter: http://localhost:3000/callback (or http://localhost:3000/api/auth/callback if using the strict AuthKit library).
   • Note: This is where WorkOS sends the user back after they log in.

5. Final Output

Once you have these, please share the credentials securely or update the project secrets. The .env.local file structure will look like this:

WORKOS_CLIENT_ID="client_xxxxxxxxxxxx"
WORKOS_API_KEY="sk_test_xxxxxxxxxxxx"
WORKOS_REDIRECT_URI="http://localhost:3000/callback"
WORKOS_COOKIE_PASSWORD="<we_will_generate_this_ourselves>"

[Wajahat43]

@alikhan0616 @junaiddshaukat Any update on this?

[alikhan0616]

Subject: WorkOS Setup Complete - Question regarding Route Protection

I have successfully initialized the WorkOS project and enabled "Invite Only" mode. This ensures that public sign-ups are disabled, and only users we explicitly invite can log in.

Question: Scope of Route Protection

Now that the AuthKit is ready to be integrated, I need clarity on which pages should be protected.

Since this authentication system is specifically for Users (Mentors/Mentees) to access features like Circles, and we already have internal admin functionality for managing them, how should we scope the middleware?

Should I apply the WorkOS protection to:

1. Specific Feature Routes Only: (e.g., only protect /circles/* and /dashboard, leaving the rest of the app as-is?)
2. The Entire Application: (Protect everything, so a user must be logged in to see anything beyond the landing page?)

Let me know which routes require this specific user authentication so I can configure the middleware.ts matchers accordingly.

Cc: @Wajahat43 @junaiddshaukat