Complete Guide: AEM System User & Service User Mapping
 

System users in AEM are used by backend services to access the repository securely without using an admin session. They are commonly used with the Sling ResourceResolverFactory to obtain a ResourceResolver.

Using system users is a recommended security practice in modern AEM development.

1. What is a System User in AEM?

A System User is a non-login user used by services or backend code to access resources in the repository.

Key Characteristics

• Cannot log in to AEM UI

• Used by backend services

• Has specific permissions (ACL)

• Works with Service User Mapping

Why System Users Are Important

Older versions of AEM allowed:

resourceResolverFactory.getAdministrativeResourceResolver()

This method is now deprecated for security reasons. Instead, system users should be used.

2. Architecture of Service User Access

Typical flow:

AEM Service / Servlet / Scheduler
↓
ResourceResolverFactory
↓
Subservice Name
↓
Service User Mapping
↓
System User
↓
Repository Access

3. Step 1: Create a System User

Open CRX Explorer:

http://localhost:4502/crx/explorer/index.jsp

Login using admin credentials.

Steps

1. Click User Administration

2. Select Create System User

3. Enter username

Example:

practiceuser

4. Click Save

4. Step 2: Verify System User

Open:

http://localhost:4502/useradmin

Search for:

practiceuser

Open the user profile to verify it was created successfully.

5. Step 3: Assign Permissions (ACL)

System users require permissions to access repository nodes.

Example path:

/content

Steps

1. Select the system user

2. Open Permissions

3. Add path

4. Grant Read permission

5. Save

Recommended rule:

Give minimum required permissions only.

6. Step 4: Configure Service User Mapping

Service user mapping connects a bundle + subservice name to the system user.

Open the configuration:

Apache Sling Service User Mapper Service Amendment

URL:

http://localhost:4502/system/console/configMgr

Search for:

Apache Sling Service User Mapper

Add mapping:

bundleId:subserviceName=systemUser

Example:

com.myproject.core:readService=practiceuser

Where:

7. Step 5: Access ResourceResolver in Code

Example Java code:

@Reference
private ResourceResolverFactory resourceResolverFactory;

public void getResolver() {
Map<String, Object> param = new HashMap<>();
param.put(ResourceResolverFactory.SUBSERVICE, "readService");

try (ResourceResolver resolver =
resourceResolverFactory.getServiceResourceResolver(param)) {

Resource resource = resolver.getResource("/content/my-site");

if(resource != null) {
System.out.println(resource.getPath());
}
} catch (LoginException e) {
e.printStackTrace();
}
}

8. Step 6: Best Practices

1. Use Service Users Only

Never use:

getAdministrativeResourceResolver()

2. Use Least Privilege Principle

Grant only required permissions:

Example:

/content/mysite (read)

instead of:

/content

3. Always Close ResourceResolver

Use try-with-resources:

try(ResourceResolver resolver = ...)

4. Use Separate System Users

Different services should use different users.

Example:

readServiceUser
writeServiceUser
workflowServiceUser

9. Creating System User via RepoInit (Recommended)

Instead of manual creation, modern AEM projects create system users via RepoInit scripts.

Example:

create service user practiceuser
set ACL for practiceuser
allow jcr:read on /content/myproject
end

Configured in:

org.apache.sling.jcr.repoinit.RepositoryInitializer

Benefits:

• automatic creation during deployment

• environment independent

• best DevOps practice

10. Common Use Cases of System Users

System users are used in:

1. Servlets

Example:

/bin/contentreader

2. Sling Models

3. OSGi Services

4. Workflows

5. Schedulers

11. Troubleshooting

Error: LoginException

Cause:

No service user mapped

Solution:

Check Service User Mapper configuration.

Error: Access Denied

Cause:

Missing ACL permissions

Solution:

Grant required read/write permissions.

12. Folder Structure Best Practice

Recommended system user location:

/home/users/system/<project-name>

Example:

/home/users/system/myproject/practiceuser

13. Interview Questions (Very Common)

Q1: What is a System User in AEM?

A non-login service account used by backend services to access the repository securely.

Q2: Why avoid admin sessions?

Admin sessions bypass security restrictions and can expose the repository.

Q3: What is Service User Mapping?

Mapping between bundle + subservice name and a system user.

Q4: How to get ResourceResolver using system user?

resourceResolverFactory.getServiceResourceResolver()

Final Summary