Home / admin / delegated-administration

delegated-administration

Use when configuring delegated administration to allow non-system-admin users to manage specific user groups, reset passwords, assign permission sets, or administer custom objects.

• v1.1.0
• Salesforce Spring '25+
• Updated 2026-09-04
• Security
• Operational Excellence

• delegated-administration
• delegate-group
• user-management
• security
• role-hierarchy
• profiles
• permission-sets
• login-access

Open the skill folder on GitHub

Delegated Administration

This skill activates when you need to grant a non-System-Administrator user the ability to manage a scoped subset of users — including creating users, resetting passwords, assigning profiles and permission sets, or administering custom objects — without granting them full System Administrator access. It covers setup from scratch, review of existing configuration, and troubleshooting delegated admin permissions that are not working as expected.

Before Starting

Gather this context before working on anything in this domain:

• Confirm the org has a role hierarchy defined. Scope comes entirely from the group's roles field — "the roles and subordinates for which delegated administrators of the group can create and edit users" (Metadata API Developer Guide, DelegateGroup). Listing a role puts every role beneath it in scope. UNVERIFIED (2026-09-04): the frequently repeated rule that a delegated admin can only manage users at or below their own role is not in the DelegateGroup field table, which describes the configured roles list as the only constraint. Aligning the delegated admin's own role with the top of the branch they manage is still sound practice for consistent report and sharing visibility, but do not design around the "own role" rule as a security control.
• Identify which profiles, permission sets, and permission set groups the delegated admins should be permitted to assign — three separate fields (profiles, permissionSets, permissionSetGroups). Only the specific names listed can be assigned; each list is a menu, not a scope.
• Decide loginAccess before you write the file. It is a required boolean that "allows users in this group to log in as users in the role hierarchy that they administer". Default it to false; treat true as a privileged-access grant.
• Confirm whether custom object administration is required, and check the two documented exclusions: delegated admins "can customize nearly every aspect of each of those custom objects, including creating a custom tab. However, they can't create or modify relationships on the objects or set organization-wide sharing defaults."
• Confirm the intended delegated admins hold View Setup and Configuration. The guide's Special Access Rules: "Only users with the 'View Setup and Configuration' permission can be delegated administrators. As of Spring '20 and later, only users with 'View Setup' or 'Configuration' permission can access this object."
• Know the key limit: delegated admins cannot manage System Administrator users, regardless of role hierarchy position. UNVERIFIED (2026-09-04): this protection is not stated in the DelegateGroup documentation and there is no delegate-group SObject in the Object Reference to check it against — verify it in a sandbox rather than relying on it as your only guard against a delegated admin minting administrators. The guard that is documented and checkable is keeping the System Administrator profile out of profiles.

Questions to Ask Before Configuring

Ask these before opening Setup or writing the XML. Each answer changes a field in the DelegateGroup file, and the ones that get skipped are the ones that show up later as a privilege-escalation finding.

What a proper configuration adds over just creating the group: the delegated administrators can do the job they were given without any path to creating an administrator, the impersonation switch was a decision rather than a default, and a reviewer can read the file and see exactly which population is managed and exactly what may be handed to them.

Core Concepts

Delegated Administrator Groups

A Delegated Administrator group is the core configuration object. It is the DelegateGroup metadata type — available since API 36.0, deployable from delegateGroups/<Name>.delegateGroup-meta.xml, and retrievable with the * wildcard. Each Setup related list maps to one field:

Read the fields in two halves: roles decides the population, and everything else is a menu offered inside it. Deployable examples and the package.xml are in references/metadata-examples.md.

You can create multiple groups to model different business units or regions, each with their own scope.

Role Hierarchy Enforcement

The role hierarchy is a hard constraint on delegated administration. When you add roles to the "Users in Delegated Group" configuration, the delegated admin can manage any user whose role is at or below the roles listed. The delegated admin's own role does not need to be a parent of the target roles — the role list in the group configuration is what determines scope. However, best practice is to align the delegated admin's role with the top of the roles they manage, to ensure consistent visibility across related features (reports, sharing, etc.).

One critical platform behavior: if a target user's role is not in the configured role list (or below it), the delegated admin will not see that user in their Manage Users view, even if they share a profile or group membership.

What Delegated Admins Can and Cannot Do

Can do:

• Create new users with any profile listed in the group's Assignable Profiles
• Edit user details (name, email, title, phone) for users in their group
• Reset passwords for users in their group
• Freeze or unfreeze users in their group
• Assign or remove permission sets listed in the group's Assignable Permission Sets
• (If configured) Customize specific custom objects: add/edit fields, page layouts, validation rules, and list views

Cannot do:

• Create or edit System Administrator users (platform-enforced; no workaround)
• Assign profiles not listed in the group configuration
• Assign permission sets not listed in the group configuration
• Modify their own user record via the delegated admin interface
• Access Setup areas beyond Manage Users and (if configured) the specific custom objects
• Manage users whose roles are not in the group's role scope
• Create other delegated administrator groups or modify group configuration

Custom Object Administration

Custom object administration rights are configured per Delegated Administrator group through customObjects. The guide's wording is deliberately broad, with two named exclusions:

This is useful for business unit owners who need to extend a custom object for their team without opening full Setup access — provided their backlog is not mostly relationship changes, which always route back to a full administrator.

Common Patterns

Pattern 1: Setting Up Delegated Administration From Scratch

When to use: A department head, regional manager, or HR coordinator needs to manage users in their business unit (create users, reset passwords, assign profiles) without escalating every request to the IT/Salesforce admin team.

How it works:

1. Go to Setup > Users > Delegated Administrators.
2. Click New to create a Delegated Administrator group. Give it a descriptive name (e.g., "APAC Sales Admin Group").
3. In the Delegated Administrators related list, click Add and search for the users who will act as delegated admins. Save.
4. In the Users in Delegated Group related list, click Add and select the roles whose users can be managed. The delegated admin will be able to manage users at these roles and all subordinate roles.
5. In the Assignable Profiles related list, click Add and select the profiles that the delegated admin is permitted to assign when creating or editing users.
6. (Optional) In the Assignable Permission Sets related list, click Add and select specific permission sets the delegated admin can assign.
7. (Optional) In the Custom Object Administration related list, click Add and select any custom objects the delegated admin should be able to customize.
8. Confirm the delegated admin users hold View Setup and Configuration (ViewSetup) on their own profile or via a permission set — the guide's Special Access Rules make it the prerequisite for being a delegated administrator. Enable Manage Users as well; UNVERIFIED (2026-09-04): the Manage Users requirement, though universally repeated, is not stated in the Metadata API Developer Guide or the Object Reference (references/gotchas.md #1).

Why not the alternative: Granting the System Administrator profile or cloning it with broad access creates an uncontrolled security risk. Permission sets alone cannot scope user-management rights to a subset of users — only Delegated Administrator groups provide role-scoped user management.

Pattern 2: Reviewing Existing Delegated Admin Configuration

When to use: An admin suspects a delegated admin has too broad or too narrow access, or a compliance review requires audit of who can manage users.

How it works:

1. Go to Setup > Users > Delegated Administrators.
2. Review each group for: which users are Delegated Administrators, which roles are in scope, which profiles are assignable, and which permission sets are assignable.
3. For each delegated admin user, confirm their own profile or permission set still grants View Setup and Configuration (and Manage Users, if the org relies on it) — the entry permission is often lost when a user's profile changes post-setup. scripts/check_delegated_administration.py lists every retrieved container that grants ViewSetup.
4. Cross-reference the role list against the org's role hierarchy diagram. Roles added to the group include all subordinate roles implicitly — confirm no unintended roles are in scope.
5. Check whether any delegated admins have been inadvertently given System Administrator profile access directly, which would bypass all scoping.

Pattern 3: Troubleshooting Delegated Admin Permissions Not Working

When to use: A configured delegated admin reports they cannot see the Manage Users button, cannot see specific users, or cannot assign a profile or permission set.

How it works:

1. Manage Users button missing: Check the delegated admin's profile and permission sets for View Setup and Configuration, then Manage Users. Neither is granted by group membership — the group supplies scope, the user permission supplies entry (references/gotchas.md #1).
2. Cannot see specific users: Check that those users' roles are in the Delegated Group's "Users in Delegated Group" configuration. If the target user has no role, or a role not in the list, they will not appear.
3. Cannot assign a profile: Check that the target profile is listed in the group's Assignable Profiles related list. Also confirm the target profile is not the System Administrator profile — that assignment is always blocked.
4. Cannot assign a permission set: Check the Assignable Permission Sets related list in the group configuration.
5. Error when trying to manage a System Admin user: This is expected platform behavior. System Administrator users are always protected and cannot be managed by delegated admins.

Decision Guidance

Recommended Workflow

1. Answer the seven questions in Questions to Ask Before Configuring using templates/delegated-administration-template.md. The roles answer needs a headcount for the whole branch, not a role name — that number is the group's blast radius.
2. Retrieve what already exists. sf project retrieve start --metadata DelegateGroup --metadata Role --metadata Profile --metadata PermissionSet — DelegateGroup supports the * wildcard, so one retrieve gets every group in the org. A partial retrieve makes step 5's dangling-reference warnings meaningless.
3. Write the group file from references/metadata-examples.md: delegateGroups/<Name>.delegateGroup-meta.xml, label and loginAccess present (both required), roles as the lowest roles covering the intent, and each assignment menu (profiles, permissionSets, permissionSetGroups, groups) trimmed to what the business role actually hands out.
4. Read what the menu grants, not just its name. Open every .profile and .permissionset named in the file and check for Modify All Data, View All Data, and Author Apex. This is the escalation path the group file cannot show you (references/gotchas.md #9).
5. Run the checker over the full retrieve: python3 scripts/check_delegated_administration.py --manifest-dir force-app/main/default. It errors on System Administrator in profiles and on escalation permissions inside listed profiles/permission sets, and warns on loginAccess: true, dead menus on a role-less group, and stale name references. Exit code 1 means an ERROR — do not deploy past it.
6. Deploy --dry-run first, then for real, and confirm the delegated administrators hold View Setup and Configuration (the checker lists which retrieved containers grant ViewSetup).
7. Verify three ways — retrieve round-trip and diff, the Setup related lists, and a log-in-as walkthrough as the delegated administrator, including one negative test outside the role branch (references/metadata-examples.md § Verification, references/llm-anti-patterns.md #5).

Review Checklist

Run through these before marking work in this area complete:

• [ ] Delegated Administrator group created with a clear, descriptive name (label), distinct from any public group name
• [ ] Delegated Administrators (users) added to the group in Setup — they are not part of the metadata file
• [ ] roles holds the lowest roles covering the intent; branch headcount recorded
• [ ] loginAccess was decided, not inherited from a sample; if true, approved and recorded as privileged access
• [ ] profiles does not contain System Administrator, and every listed profile / permission set was opened and read
• [ ] No listed profile or permission set enables Modify All Data, View All Data, or Author Apex
• [ ] Delegated admin users hold View Setup and Configuration via profile or permission set
• [ ] python3 scripts/check_delegated_administration.py --manifest-dir <dir> exits 0 over a full retrieve
• [ ] Retrieve round-trip after deploy shows no silently dropped roles / profiles / permissionSets entries
• [ ] Tested as the delegated admin: allowed profiles appear, a user outside the role branch does not
• [ ] Tested: delegated admin cannot see or modify System Administrator users (verify — see gotchas #2)
• [ ] (If custom object admin) Only the intended custom objects are listed, and the requester knows relationships and OWD are excluded

Salesforce-Specific Gotchas

The full write-ups, with grounding, are in references/gotchas.md. In one line each:

Output Artifacts

Reference Files

Related Skills

• admin/user-management — full user provisioning, deactivation, license assignment, and role/profile setup that falls outside delegated admin scope
• admin/role-hierarchy-design — shaping the role branches that roles points at; the branch shape is the delegation scope
• admin/permission-set-architecture — what goes inside the permission sets listed in permissionSets, which is where the escalation risk actually lives
• security/privileged-access-management — governing standing administrative access and log-in-as, the home for any group deployed with loginAccess: true
• admin/custom-permissions — when the delegated task needs a named permission to gate against rather than a broader profile or permission set
• admin/user-access-policies — automatic, attribute-driven permission set assignment, which replaces manual delegated assignment for rule-shaped cases

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/metadata-examples.md
• references/well-architected.md
• templates/delegated-administration-template.md
• scripts/check_delegated_administration.py