Design and Implementation of the SAM Permission System for Retail Platforms

By Mao Chengguang, Ma Chunjie on Retail

Youzan, as a merchant service company, helps businesses succeed in the Internet era through its products and services. In the wave of new retail, Youzan Retail provides solutions for stores of various sizes and online shops, enabling retailers to quickly enter the new retail era.

How can a mature new‑retail store elegantly manage dozens of employee roles (owner, store manager, customer service, cashier, verifier, warehouse keeper, finance, etc.) without pain?

After analyzing retail business scenarios and iterating on employee role‑management solutions, the Security Access Manager (SAM) permission system was created. SAM is a milestone in Youzan Retail’s exploration of employee role‑based permission management. It supports PC, App, and Pad products, allowing any store using Youzan Retail to flexibly assign roles to employees, thereby improving operational efficiency. The same framework also abstracts to other product lines such as the micro‑mall.

Before introducing SAM, several real‑world analogies are presented to illustrate permission concepts (e.g., QQ invisible status, black‑listing on social platforms). These map to the classic RBAC (Role‑Based Access Control) model, where a permission is expressed as a triple Who‑What‑How .

RBAC

RBAC abstracts the pattern “Who performs How on What”. It introduces the notion of a role —a collection of users and a collection of permissions. Users acquire permissions indirectly by being assigned roles. The basic RBAC model is illustrated in the original diagram.

In RBAC, the relationships between users‑roles and roles‑permissions are many‑to‑many. A session maps a user to multiple active roles, and the effective permission set is the union of those roles. RBAC separates users from resources, simplifying permission management.

Permission System SAM

SAM Permission System Model Design

SAM follows the RBAC principle: permissions are attached to roles, not directly to users. The business model consists of two parts: employee management (maintaining staff and assigning roles) and permission management (defining menus, pages, buttons, APIs as resources). The resulting “user‑role‑permission‑resource” model enables fine‑grained access control.

Key terminology in SAM includes:

Employee: the bearer of permissions.

Role: a set of permissions that can be dynamically managed.

Permission point: a globally unique identifier for a specific functional capability.

Function point: the minimal logical unit of a system resource, each mapped to a permission point.

Function set (permission set): a collection of function points.

API: the channel for requesting system resources, carrying function‑set attributes.

Menu: the entry that organizes system resources for the requester.

Page: a special kind of menu with a URL attribute.

Button: a finer‑grained entry within a page, also treated as a special menu.

Implementation of SAM

Traditional RBAC stores role‑to‑permission mappings in a relational table, which becomes hard to maintain as the number of function points grows. SAM solves this by using a binary‑based encoding strategy. Each function point is represented by a Long value (64 bits). An idx identifies the Long slot, and a pos identifies the bit within that slot. When a Long is full, idx increments, creating a new slot. Thus a permission set can be expressed as a series of bits, enabling compact storage and fast bitwise checks.

Example: permission set {1} means idx=0, pos=0 . Permission set {‑1,1} means all bits in idx=0 (positions 0‑63) plus idx=1, pos=0 .

The permission‑checking formula is a bitwise AND between the role’s permission Long array and the resource’s permission Long array. If any corresponding Long yields a non‑zero result, the role has access.

Permission verification formula: {Long0,Long1…LongN} & {Long0,Long1…LongM}

SAM adheres to the principles of least privilege, separation of duties, and data abstraction, ensuring that roles only receive the minimal set of functions required, that mutually exclusive roles can cooperate on sensitive tasks, and that permissions are abstracted from low‑level OS permissions.

SAM Architecture

SAM serves PC, App, Pad, and micro‑mall clients. It is exposed as a micro‑service via Dubbo, with a distributed layered architecture. The client side is lightweight and embedded in business systems; the server side manages employees, menus, roles, APIs, and function points. High request volume is handled with Redis caching, Druid connection pooling, and integration with the Tianwang monitoring platform for stability.

Role‑based access control in Youzan Retail manifests as API verification and menu rendering. When a user clicks a menu item or button, the system performs both menu rendering and API permission checks, each isolated per client to avoid interference.

Menu Rendering

SAM provides PHP and Node.js clients for web integration. Menu rendering follows three steps:

Node positioning – locate the unique page node in the menu tree using the request URL, then retrieve its path and associated buttons.

Permission calculation – combine the user’s role permission sets with each node’s permission set to determine access rights, greying out or hiding unauthorized items.

Attribute propagation – propagate URL attributes from child menus upward so that parent nodes inherit the first accessible child’s URL.

API Permission Verification

API requests pass through the “Kamen” API gateway. The SAM API verification client intercepts the request, applies the bitwise permission formula, and either allows execution or returns an error.

Pseudo‑code for API permission verification:

# Permission error code definition
AUTHPERM_ERROR(231000401,"You do not have permission to perform this operation!")
# AspectJ pointcut
@Before("@annotation(com.youzan.sam.common.Auth)")
# Aspect handler method
def handle(JoinPoint pjp):
    if(!enable):
        return
    def pass = checkPermission()
    if (pass.isSuccess()):
        if(pass.getData().get("isSuccess")):
            return
        else:
            throw new BusinessException(AUTHPERM_ERROR.getCode, AUTHPERM_ERROR.getMessage())
    else:
        throw BusinessException(pass.getCode(), pass.getMessage())

# Permission check method
def checkPermission():
    {...}
    def kdt_id = RpcContext.getContext().getAttachment(Constants.KDT_ID_KEY)
    def admin_id = RpcContext.getContext().getAttachment(Constants.ADMIN_ID_KEY)
    def service = RpcContext.getContext().getAttachment(Constants.SERVICE_KEY)
    def method = RpcContext.getContext().getAttachment(Constants.METHOD_KEY)
    def version = RpcContext.getContext().getAttachment(Constants.VERSION_KEY)
    {...}
    def staffPerm = StaffPermServiceProxy.getStaffPerms(adminId, kdtId)
    def apiPerm = APIPermServiceProxy.getServicePerms(service, version, method)
    {...}
    return pass

The verification flow includes annotating APIs with @Auth , enabling/disabling the check at runtime, retrieving role and API permission sets from SAM, and performing the bitwise AND operation.

Future Outlook

Custom Roles

Youzan Retail currently offers eight default roles for single‑store scenarios. Because real‑world needs are more complex, custom roles are already in use and will be fully supported, allowing merchants to define any permission set for any role.

Multiple Roles per Employee

To reduce labor costs, employees may hold multiple roles. SAM already provides multi‑role capabilities.

Retail Mid‑Platform Support

The Retail Mid‑Platform is a flagship product offering omnichannel solutions. Its complex business model involves many role‑permission combinations and personalized merchant requirements, posing a challenge for SAM’s flexible adaptation.

Custom Menus

Previously, feature releases were controlled by a deployment system. SAM’s menu management now allows real‑time control of any menu, page, or button, enabling seamless online/offline toggling of features.

Technical Refactoring

As a core component for Retail and other businesses, SAM must be highly available, performant, extensible, scalable, and secure. Ongoing refactoring will continue to meet growing business demands.

Conclusion

The SAM permission system is owned by the Youzan Retail technical team and is open for external integration. The team is rapidly expanding and welcomes interested engineers to join.