Front-End Authentication with dotCMS & Next.js

In the evolving landscape of headless CMS solutions, managing front-end user authentication remains a challenge for developers. While most headless CMS platforms rely on third-party authentication services, dotCMS offers a built-in front-end user management system. 

This unique capability is particularly useful for building member portals, gated content experiences, and intranets, where managing user access is essential.

The Complexity of User Authentication in Headless CMS

Many headless CMS platforms focus on content management while leaving authentication to external services. While this provides flexibility, it also requires developers to integrate third-party identity providers such as Auth0, Firebase, or Amazon Cognito.

These integrations add extra layers of configuration, dependencies, and maintenance. Developers must ensure synchronization between the CMS and authentication provider, handle security concerns like token validation, and manage user roles separately. This approach can be effective, but it increases complexity.

How dotCMS Stands Out

Unlike many other headless CMS platforms, dotCMS includes native front-end user management capabilities, offering several key advantages:

1. Built-in Authentication & User Management

• dotCMS allows developers to create, manage, and authenticate users directly within the CMS, eliminating the need for third-party authentication services.

• It supports role-based access control (RBAC) and permission settings, making it easier to manage gated content and user-specific experiences.

• Developers can define workflows for different user groups, enhancing security and content governance.

2. Reduced Development Complexity

• With other CMS platforms, setting up authentication requires integrating and maintaining external identity services, writing custom authentication logic, and ensuring secure token storage and validation.

• dotCMS simplifies the process by offering out-of-the-box authentication, reducing the burden on developers and minimizing ongoing maintenance costs.

3. Stronger Security & Compliance

• While third-party authentication providers offer enterprise-level security, dotCMS provides native role-based access control (RBAC) and user workflows that help meet security and compliance requirements.

• Organizations with strict data governance policies can keep user management centralized within dotCMS, rather than relying on external services.

Implementing Front-End Authentication in dotCMS with Next.js

One of the most common use cases for front-end authentication is building a Next.js application with gated content or personalized user experiences. Here’s how developers can leverage dotCMS’s built-in authentication within a Next.js application:

Step 1: Set Up Front-End Users in dotCMS

1. Navigate to Users & Permissions in the dotCMS admin panel.

2. Create front-end user roles with the appropriate permissions.

3. Add new front-end users manually or programmatically via the dotCMS API.

Step 2: Allow Users to Register on the Front-End

To enable users to create their own accounts from the front-end, you can send a request to the dotCMS API to create a new user:

async function registerUser(username, email, password) {
    const response = await fetch('https://your-dotcms-instance/api/v1/users', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            userId: username,
            emailAddress: email,
            password: password,
            roles: ['Intranet'] // Assign user roles as needed
        })
    });

    if (!response.ok) {
        throw new Error('User registration failed');
    }

    const data = await response.json();
    return data;
}

Step 3: Authenticate Users in Next.js

Developers can authenticate users using the dotCMS REST API. Here’s an example of a login function in Next.js:

async function loginUser(username, password) {

    const response = await fetch('https://your-dotcms-instance/api/v1/authentication/api-token', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            user: username,
            password
        })
    });

    if (!response.ok) {
        throw new Error('Authentication failed');
    }

    const data = await response.json();

    // optionally set the cookie in the response
    // resp.cookies.set({name: 'auth-token', value: data.entity.token})

    return data.entity.token;
}

Step 4: Passing the JWT Token on Subsequent API Calls

After authentication, every subsequent API request should include the JWT token to verify the user’s identity. Here’s an example of how to retrieve the currently authenticated user:

import { cookies } from "next/headers";

async function getCurrentUser() {
    const token = cookies().get(auth-token');

    if (!token) throw new Error('No authentication token found');

    const response = await fetch('https://your-dotcms-instance/api/v1/users/current', {
        method: 'GET',
        headers: {
            'Authorization': Bearer ${token},
            'Content-Type': 'application/json'
        }
    });
    
    if (!response.ok) {
        throw new Error('Failed to fetch user data');
    }

    return await response.json();
}

If the authentication is successful, dotCMS will return the currently logged-in user's details in JSON format.

Step 5: Protect Routes and Manage User Sessions

After authentication, you can store the user session and restrict access to certain pages in your Next.js app:

import { cookies } from "next/headers";
import { redirect } from "next/navigation";

export default function ProtectedPage() {
    const token = cookies().get("auth-token")


    if (!token) {
        redirect('/'); // Redirect to login if not authenticated
    }

    return <div>Welcome to a protected page</div>;
}

Conclusion

dotCMS provides a powerful, built-in front-end user management system that eliminates the need for third-party authentication solutions. This reduces development complexity, strengthens security, and streamlines the process of managing user access. For teams building member portals, gated content experiences, or personalized applications, dotCMS offers a seamless and secure solution.

For developers working with Next.js, integrating dotCMS authentication is straightforward, allowing for efficient session management and protected routes with minimal effort.

Want to see it in action? Try out this example which has some of the concepts explained here already implemented.