Apex User And Permission Checks

Apex User And Permission Checks

Activates when Apex needs to branch on who the running user is or what they are allowed to do. Produces correct FeatureManagement.checkPermission usage, safe identity reads, and guidance to use custom permissions over profile-name checks.

Before Starting

• What are you actually gating — UI behavior only, or server-side authorization? Server-side checks must be enforced with stripInaccessible / user_mode regardless of permission flags.
• Does a Custom Permission exist for this concept? If not, create one — it's the supported extensibility point.
• Is the check supposed to ignore admins (e.g., "even admins can't do this") or honor them (most permissions do)? Custom Permissions respect "Modify All Data."
• Does this run in a Queueable, Batch, or @future? The running user is the async context user, not the originating user.

Core Concepts

Prefer Custom Permissions Over Profile / Permission-Set Name Checks

The supported way to gate a feature in Apex is a Custom Permission. In Setup create Perform_Bulk_Refund, assign it to permission sets or profiles, and check with FeatureManagement.checkPermission('Perform_Bulk_Refund'). This returns true if the user has the permission via any assignment path.

Checking Profile.Name == 'Sales Manager' is brittle: the name can be renamed in production, cloned profiles drift, and this check misses permission-set-based grants.

UserInfo Gives Identity, Not Authorization

UserInfo.getUserId(), .getUserName(), .getProfileId(), and .getSessionId() report identity. Use them for logging and relationship lookups. Don't use UserInfo.getProfileId() to drive authorization — couple the gate to a permission the admin can grant.

Async Context Switches The User

Apex in @future, Queueable, Batch, Scheduled, and platform event triggers runs as the async context user (often the user who fired the async, but for scheduled jobs the scheduler, for platform events the "Automated Process" user). FeatureManagement.checkPermission then checks that user's permissions. If you need the originating user, pass their Id explicitly and look up permissions via a query (see patterns).

Custom Permission Lookup Paths

FeatureManagement.checkPermission('Name') checks if the running user has the custom permission via Profile or Permission Set assignment. Multi-permission checks need an AND/OR logic built in Apex.

There is no checkPermissionFor(userId, 'Name') built-in. For a user other than the running user, query the SetupEntityAccess / PermissionSetAssignment / CustomPermission graph yourself.

Common Patterns

Pattern 1: Gate A Feature On A Custom Permission

When to use: Any code path that should be available only to users an admin has blessed.

How it works:

public with sharing class BulkRefundService {
    public static void initiate(Set<Id> paymentIds) {
        if (!FeatureManagement.checkPermission('Perform_Bulk_Refund')) {
            throw new NoAccessException('You do not have permission to perform bulk refunds.');
        }
        // proceed
    }
}

Why not the alternative: Hardcoding Profile.Name == 'Finance Admin' misses permission-set assignments and breaks on rename.

Pattern 2: Check Custom Permission For A Different User

When to use: A Queueable running as the automated context needs to verify the originating user's permission.

How it works:

public class RefundQueueable implements Queueable {
    private final Id initiatingUserId;
    private final Set<Id> paymentIds;

    public RefundQueueable(Id initiatingUserId, Set<Id> paymentIds) {
        this.initiatingUserId = initiatingUserId;
        this.paymentIds = paymentIds;
    }

    public void execute(QueueableContext ctx) {
        if (!hasPermission(initiatingUserId, 'Perform_Bulk_Refund')) {
            throw new NoAccessException('Initiating user lacks bulk refund permission.');
        }
        // proceed
    }

    private static Boolean hasPermission(Id userId, String permApiName) {
        return ![
            SELECT Id FROM PermissionSetAssignment
            WHERE AssigneeId = :userId
            AND PermissionSet.PermissionsCustomizeApplication = false
            AND PermissionSetId IN (
                SELECT ParentId FROM SetupEntityAccess
                WHERE SetupEntityType = 'CustomPermission'
                AND SetupEntityId IN (
                    SELECT Id FROM CustomPermission WHERE DeveloperName = :permApiName
                )
            )
        ].isEmpty();
    }
}

Why not the alternative: FeatureManagement.checkPermission silently checks the running (async context) user, not the originating user.

Pattern 3: Distinguish Internal Vs Community Users

When to use: Code behaves differently for Experience Cloud users vs internal licenses.

How it works:

public with sharing class UserContextUtil {
    public static Boolean isInternal() {
        UserType t = UserInfo.getUserType();
        return t == UserType.Standard;
    }
}

Where UserType is an enum and Standard represents internal users. Partner, Customer Success, CspLitePortal and others represent external. Treating internal-only code paths as the default is safer than enumerating every external type.

Decision Guidance

Recommended Workflow

1. Identify the concept being gated (e.g., "can initiate a refund"). Create a Custom Permission with a descriptive DeveloperName.
2. Assign the Custom Permission to the relevant Permission Sets (prefer over profiles).
3. In Apex, call FeatureManagement.checkPermission('<DeveloperName>').
4. For server-side authorization, pair the check with WITH USER_MODE on SOQL and DML, or Security.stripInaccessible.
5. Write tests under System.runAs(userWithPerm) and System.runAs(userWithoutPerm) to prove both paths.
6. Avoid caching the result across transactions — permission assignments change.
7. Document the permission in the feature's README so admins know what to grant.

Review Checklist

• No Profile.Name == 'Something' checks in security-sensitive code.
• Custom Permissions exist and have descriptive DeveloperNames.
• FeatureManagement.checkPermission is called only for the running user; async jobs pass the originator Id explicitly.
• Server-side authorization is paired with FLS/CRUD enforcement.
• Tests cover both the allowed and denied paths with System.runAs.
• Permission assignments are documented in the feature's admin guide.

Salesforce-Specific Gotchas

See references/gotchas.md for the full list.

1. Async context users differ from originators — checkPermission in a Queueable checks the async user.
2. Custom Permissions respect "Modify All Data" — admins pass any permission check by default.
3. Profile rename breaks hardcoded name checks — prefer Custom Permissions.
4. System.runAs(admin) in tests masks permission bugs — test as real users.
5. FeatureManagement.checkPermission returns false for undefined permissions without throwing — typos silently deny.

Output Artifacts

Related Skills

• apex-security-patterns — FLS/CRUD enforcement alongside permission gating
• apex-async-architecture — user-context switches in async work
• apex-callable-interface — permission-sensitive dynamic invocation