SharePoint Group Creation & Permission Management with PnPjs

Managing permissions effectively in SharePoint is crucial for building secure and collaborative environments. While assigning permissions to users or breaking inheritance is common, enterprise-grade solutions often require creating custom SharePoint groups, managing role definitions, and implementing validation logic.

In this article, we'll explore how to use the modern PnPjs (@pnp/sp) with SPFx to:

• Create custom SharePoint groups
• Assign role definitions (permissions)
• Validate group existence and user permissions

🧠 Note: We’re using the latest PnPjs (spfi) with fluent syntax and tree-shaking support for optimized bundles.

Prerequisites:

Ensure your SPFx project has the latest PnPjs installed:

npm install @pnp/sp @pnp/graph @pnp/nodejs --save        

Set up spfi in your webpart.ts:

import { spfi, SPFI } from "@pnp/sp";
import { SPFx } from "@pnp/sp";
import { WebPartContext } from "@microsoft/sp-webpart-base";

let sp: SPFI;

export const setupPnPjs = (context: WebPartContext): void => {
  sp = spfi().using(SPFx(context));
};        

1. Create a Custom SharePoint Group

You can create a new group with optional settings:

const groupTitle = "Custom Contributors";
const groupDescription = "Users with limited contribution rights";

const groupResult = await sp.web.siteGroups.add({
  Title: groupTitle,
  Description: groupDescription,
  AllowMembersEditMembership: true,
  OnlyAllowMembersViewMembership: false
});

console.log("Group Created:", groupResult);        

✅ This will create a site-level group. You can also add users right after creation.

2. Create and Assign Role Definitions

To assign a permission level, like Contribute, to the new group on the site or a list:

// Break inheritance (optional)
await sp.web.breakRoleInheritance(true, true);

// Get the role definition (Contribute)
const contributeRole = await sp.web.roleDefinitions.getByName("Contribute");

// Assign role to the group
await sp.web.roleAssignments.add(
  groupResult.group.Id,
  contributeRole.Id
);        

🧠 You can also use "Read", "Edit", "Full Control" as role names.

3. Validate Group Existence Before Creating

Avoid duplicate groups by checking if it already exists:

const groupName = "Custom Readers";
const groupDescription = "Group for read-only access";

const allGroups = await sp.web.siteGroups();
const exists = allGroups.some((g) => g.Title === groupName);

if (!exists) {
  await sp.web.siteGroups.add({
    Title: groupName,
    Description: groupDescription,
  });
}        

4. Validate If a User Belongs to a Group

To check whether a user or group has a particular role assigned:

const user = await sp.web.siteUsers.getByEmail("user@yourdomain.com").select("Id")();

const hasPermissions = await sp.web.roleAssignments.getByPrincipalId(user.Id)();
console.log("User Role Assignments:", hasPermissions);        

💡 You can also call .expand("Member", "RoleDefinitionBindings") to get more details about the assigned roles.

5. Revert to Default Permissions (Reset Inheritance)

If you need to reset permissions to inherited defaults:

await sp.web.lists.getByTitle("Projects").resetRoleInheritance();        

Bonus: Add User to Group

await sp.web.siteGroups.getByName(groupName).users.add("i:0#.f|membership|john.doe@domain.com");        

Conclusion

By leveraging the powerful and modern PnPjs API, you can fully manage SharePoint groups, role definitions, and permissions directly from your SPFx components. This ensures your apps can scale securely across site collections and tenants.

Up Next

In the next blog, we'll dive into automating site-level permission structures, including:

• Creating groups per site
• Mapping roles by business rules
• Logging permission assignments

Helpful Resources

• PnPjs Documentation – Permissions
• PnPjs GitHub