Manage Access Control

PlusAuth provides a powerful and flexible permission management system that allows fine-grained control over what users, applications, and resources can access. Permissions can be assigned directly to users or indirectly through roles and role groups, and are ultimately reflected in the user's access tokens.

Core Concepts

Resource

A Resource represents a protected entity (for example, an API or service) that enforces access control. Each resource is uniquely identified by its audience (aud) parameter.

A resource also defines:

• Which Clients (Applications) are allowed to request tokens for it.
• Which Permissions are available within that resource.

Permissions are always defined per resource. When managing permissions in the dashboard, you can select the active resource from the top-left dropdown in the Permission Graph view.

Permission

A Permission represents a specific action or capability within a resource (for example, read:user, update:profile, delete:post). Permissions are assigned:

• Directly to users, or
• Indirectly via roles and role groups.

The effective permissions granted to a user determine which permissions(scopes) will appear in their access token.

Role

A Role is a named collection of permissions within a resource. Roles simplify permission management by grouping related permissions together (e.g., admin, editor, viewer).

Roles can:

• Contain multiple permissions.
• Be assigned to users.
• Be assigned to role groups.
• Be configured to auto-assign to new users during signup.

Role Group

A Role Group is a higher-level container that groups multiple roles together. Assigning a role group to a user effectively grants all permissions contained in the included roles.

Like roles, role groups can also be configured for automatic assignment upon user creation.

Access Control Flow

The permission resolution process in PlusAuth occurs through a series of ordered stages. When a client requests access to a resource, PlusAuth evaluates the client’s authorization, gathers the user’s assigned permissions, and progressively expands them through roles and role groups. These permissions are then merged, filtered according to the resource–client policy, and finalized as the effective set of permissions embedded in the access token.

The table below summarizes the stages of PlusAuth’s permission resolution process.

The following diagram illustrates how these stages interact in practice.

flowchart TB
    %% === INPUT LEVEL ===
    subgraph INPUTS
        direction LR
        F["Client (Application)"]
        U["User"]
    end


    %% === RESOURCE DEFINITION ===
    A["Resource (identified by 'audience')"]

    %% === USER PERMISSIONS COMPOSITION ===
    B["Direct Permissions"]
    C["Roles"]
    D["Role Groups"]
    E["Permissions from Roles"]
    F2["Permissions from Role Groups"]
    M["All User Permissions (Merged per Resource)"]

    %% === FILTER & OUTPUT ===
    X["Filter: Allowed Permissions for this Client–Resource"]
    T["Final Permissions"]

    %% === FLOWS ===
    F --> A
    A --> X
    U --> B
    U --> C
    U --> D
    C --> E
    D --> F2
    B --> M
    E --> M
    F2 --> M
    M --> X
    X --> T

    %% === STYLING ===
    classDef entity fill:#fef6e4,stroke:#f1c40f,stroke-width:1.5px;
    classDef permission fill:#e6f4ea,stroke:#27ae60,stroke-width:1.5px;
    classDef flow fill:#e8f0fe,stroke:#2980b9,stroke-width:1.5px;
    classDef filter fill:#fdebd0,stroke:#f39c12,stroke-width:2px,stroke-dasharray: 3 3;
    classDef final fill:#fff3cd,stroke:#e67e22,stroke-width:2px,font-weight:bold;

    %% Hide the subgraph's background and border
    style INPUTS color:transparent
    style INPUTS stroke-width:0px;
    style INPUTS fill:none;


    %% Assign node styles
    class A,F entity
    class U,C,D flow
    class B,E,F2,M permission
    class X filter
    class T final

1. Access Context: Client → Resource

Every request starts when a Client (Application) asks for access to a Resource, identified by its audience. Each resource defines:

• Which clients are allowed to request tokens for it
• Which permissions those clients are allowed to use.

This establishes the access boundary for the rest of the process.

2. User Context and Permission Sources

In parallel, PlusAuth collects all permissions that belong to the User for the same resource:

1. Direct Permissions – permissions explicitly assigned to the user.
2. Roles – sets of permissions grouped under a role name.
3. Role Groups – higher-level groupings that contain multiple roles.

Roles and role groups are expanded step by step:

• Roles → Permissions – each role's permissions are added.
• Role Groups → Roles → Permissions – role groups are resolved into their included roles, and then into permissions.

All of these are merged into a unified set of user permissions per resource.

3. Permission Filtering by Resource-Client Rules

Once the full list of user permissions is built, PlusAuth filters it through the Resource-Client configuration. Only permissions that satisfy both conditions are kept:

• The user possesses the permission, and
• The client is allowed to use that permission for this resource.

Any permission outside the client–resource's allowed list is discarded, even if the user has it.

4. Final

The resulting intersection of permissions becomes the effective scopes for this authentication context. These are embedded into the user's access token.

This model allows PlusAuth to provide granular, resource-based access control that scales from simple role-based setups to complex multi-resource permission hierarchies.