Introduction: What Are Portal Roles in Frappe?

In Frappe Framework v15, portal roles define what logged-in website users are allowed to see and do on portal pages. They bridge the gap between internal role-based permissions and external user access.
Portal roles are essential for building secure customer portals, vendor dashboards, and member-only web pages without exposing internal Desk permissions.

What Is a Portal Role?

Answer:
A portal role is a standard Frappe Role assigned to a portal user that determines access to portal pages, linked documents, and actions.
Portal roles:

• Apply only to website users
• Work alongside DocType permissions
• Are evaluated server-side before rendering content

How Portal Roles Work in Frappe v15

Portal role evaluation follows this flow:

1. User logs in via website
2. User roles are loaded
3. Portal page access is validated
4. DocType permissions are enforced
5. Content is rendered conditionally

This ensures secure, role-aware portal access.

Portal Roles vs Desk Roles

Portal users never access Desk unless explicitly enabled.

Default Portal Roles in Frappe

Frappe ships with standard portal roles such as:

• Customer
• Supplier
• Website User
• Member

These roles can be reused or extended based on business needs.

Assigning Portal Roles to Users

Portal roles are assigned like any other role.

Steps:

1. Go to User
2. Open the portal user
3. Add roles under Roles
4. Save

Once assigned, permissions apply immediately.

Restricting Portal Pages Using Roles

Portal pages can be restricted using role checks.

Example

import frappe
def get_context(context):
if "Customer" not in frappe.get_roles():
frappe.throw("Not permitted")

This ensures only authorized portal users can access the page.

Role-Based Data Access in Portal Pages

Portal roles work together with DocType permissions.

Example use case:

• Customers see only their Sales Orders
• Suppliers see only their Purchase Orders

Permissions are enforced automatically using standard Frappe permission rules.

Portal Roles with Linked DocTypes

Portal roles are commonly used with:

• Sales Order
• Purchase Order
• Invoice
• Support Ticket

Access is controlled using:

• User Permission
• Link Field mapping
• Role-based DocType permissions

Making a Page Role-Specific

You can enforce role access explicitly.

def get_context(context):
context.allowed_roles = ["Supplier"]

Combined with permission checks, this ensures clean role separation.

Best Practices for Portal Roles

• Use minimal roles for portal users
• Avoid reusing Desk-only roles
• Combine roles with User Permissions
• Always validate roles server-side
• Keep role names business-friendly

Common Mistakes to Avoid

• Assigning Desk roles to portal users
• Skipping DocType permission setup
• Hardcoding role names without checks
• Exposing internal fields in portal views

Real-World Use Case

Customer Portal

• Role: Customer
• Access: Orders, Invoices, Tickets
• Restriction: Own records only

Supplier Portal

• Role: Supplier
• Access: POs, Payment Status
• Restriction: Linked supplier records

Portal roles make these scenarios secure and scalable.

Troubleshooting Portal Role Issues

User sees Not Permitted

• Check assigned roles
• Verify DocType permissions

Page loads but no data

• Validate User Permission records
• Confirm role-based filters

User redirected unexpectedly

• Confirm login status
• Check role validation logic

Technical Scope & Compatibility

• Framework: Frappe Framework v15
• Modules: Website, Portal
• Applies to: ERPNext portals, custom Frappe apps
• Not applicable: Desk pages, Reports, Workspaces

Industry Relevance

• ERP customer portals
• Vendor self-service portals
• Membership platforms
• B2B SaaS dashboards

Cross-References

Official Portal Roles Documentation

https://docs.frappe.io/framework/user/en/guides/portal-development/portal-roles

Portal Context

https://docs.frappe.io/framework/user/en/guides/portal-development/context

Frappe v15 Source Code

https://github.com/frappe/frappe/tree/version-15

Conclusion

Portal roles in Frappe Framework v15 provide a secure, scalable mechanism for controlling website user access without exposing internal system functionality. When combined with DocType permissions and user mappings, portal roles enable clean separation of responsibilities and robust portal security.
Used correctly, portal roles are the foundation of professional, enterprise-grade portal development in Frappe.