Connect AEM 6.5

Overview

This guide explains how to integrate Gradial with Adobe Experience Manager (AEM) 6.5. AEM 6.5 supports multiple authentication methods, with OAuth 2.0 being the preferred approach for enhanced security and granular access control.

Authentication Methods

AEM 6.5 supports two primary authentication methods for external integrations:

OAuth 2.0 Client (Preferred)

Recommended approach offering fine-grained access control through custom OAuth scopes. Provides better security, audit trails, and permission management.

Basic Authentication

Secondary option using username/password credentials. Simpler to implement but less secure and granular than OAuth.

OAuth 2.0 is strongly recommended for production environments due to its superior security model, token-based authentication, and granular permission controls.

OAuth 2.0 Integration Steps

Basic OAuth integration includes:

Creating and configuring an OAuth client
Defining custom OAuth scopes and assigning them appropriate permissions
Configuring user permissions for scope access
Granting the oauthservice user the same privileges (plus access control privileges)
Providing Gradial with the OAuth client credentials (and private key if 2-legged OAuth)

OAuth 2.0 Technical Details

AEM supports two OAuth authentication flows:

On-behalf-of (3-legged)

Tied to individual user permissions. This flow requires user authentication and consent.

Service-to-service (2-legged)

Machine-to-machine communication with no user intervention. Uses JWT tokens for authentication.

Gradial’s access is always additionally governed by custom-defined OAuth scopes.

Integration Steps

Create an OAuth Client

Log in as an admin or service account
Go to <AEM-HOST>/libs/granite/oauth/content/clients.html, click Create
Name the client (e.g., Gradial)
For 3-legged OAuth, set the redirect to: https://www.gradial.com/api/v1/auth/aem65/oauth2/callback
Obtain the Client ID and Secret and share them securely with Gradial

Always keep OAuth credentials secure and never share them in public repositories or documentation.

Define Custom OAuth Scopes

What are OAuth Scopes?OAuth scopes are Java classes that define specific permissions for API access. Each scope:

Maps to specific JCR paths in your AEM repository
Defines the exact privileges (read, write, version management, etc.)
Controls what operations the OAuth client can perform
Appears in user consent dialogs during authorization

Example Scope ImplementationThe following complete example demonstrates how to create an OAuth scope for asset upload permissions:

ExampleScope.java - Complete Implementation

package com.site.ams.core.oauth.scopes;

import javax.servlet.http.HttpServletRequest;

import org.apache.jackrabbit.api.security.user.User;
import org.apache.jackrabbit.oak.spi.security.privilege.PrivilegeConstants;
import org.osgi.service.component.annotations.Component;

import com.adobe.granite.oauth.server.Scope;
import com.adobe.granite.oauth.server.ScopeWithPrivileges;

/**
 * Example OAuth Scope for Gradial AEM 6.5 Integration
 * 
 * This scope demonstrates how to create custom OAuth scopes for AEM 6.5 integrations.
 * It defines permissions for Digital Asset Management (DAM) operations including
 * uploading, reading, and version management of assets.
 * 
 * Key Components:
 * - RESOURCE_URI: Defines the JCR path this scope grants access to
 * - UPLOAD_ASSETS_SCOPE: Unique identifier for this scope
 * - getPrivileges(): Specifies the exact JCR privileges granted
 * - getDescription(): Human-readable explanation shown in consent dialogs
 * 
 * Usage Instructions:
 * 1. Customize RESOURCE_URI to match your DAM structure (e.g., /content/dam/mysite)
 * 2. Update UPLOAD_ASSETS_SCOPE name to reflect your use case
 * 3. Deploy as OSGi bundle to AEM instance
 * 4. Reference scope name in OAuth client configurations
 * 5. Ensure authenticating users have corresponding JCR permissions
 * 
 * @version 1.1
 */
@Component(service=Scope.class)
public class ExampleScope implements ScopeWithPrivileges {

    // If authors have permissions to a specific folder in the DAM, use that as the resource path in the scope.
    // Common base folders: /content/dam
    //                      /content/dam/tenant1/site1
    //                      /content/dam/site1
    //                      /content/dam/final
    //                      /content/dam/tenant1/final/site1/en-us
    private static final String RESOURCE_URI = "/content/dam";
    // Update the scope name accordingly if the resource path is specific to a tenant or site.
    private static final String UPLOAD_ASSETS_SCOPE = "upload_assets";

    @Override
    public String[] getPrivileges() {
        return new String[] {
            PrivilegeConstants.JCR_READ,
            PrivilegeConstants.REP_WRITE,
            PrivilegeConstants.JCR_LOCK_MANAGEMENT,
            PrivilegeConstants.JCR_VERSION_MANAGEMENT
        };
    }

    @Override
    public String getName() { return UPLOAD_ASSETS_SCOPE; }

    @Override
    public String getResourcePath(User user) {
        if (user == null) {
            throw new IllegalArgumentException("User cannot be null");
        }
        return RESOURCE_URI;
    }

    @Override
    public String getEndpoint() {
        return null;
    }

    /**
     * Get the description for the scope. This is displayed to the user in the consent dialog.
     * @param httpServletRequest - The request.
     * @return String - The description.
     */
    @Override
    public String getDescription(HttpServletRequest httpServletRequest) {
        return "Upload assets to the DAM";
    }
}

This example demonstrates:

Asset upload permissions to /content/dam
Required JCR privileges (read, write, lock management, version management)
Proper OSGi component configuration
User-friendly description for consent dialogs

Standard Scopes for Gradial IntegrationThe typical set of scopes Gradial requires:

ReadAllScope.java: Read access to / for component/template definitions, dynamic media publishing, etc.
AuthorLaunchesScope.java: Create and manage launches at /content/launches
AuthorTagsScope.java: Create and manage tags at /content/cq:tags
AssetsUploadScope.java: Upload assets to /content/dam
AssetsPublishScope.java: Publish assets from the DAM

Custom Scope Development for Multi-Site EnvironmentsTechnical Requirement: Each unique content path or permission requirement needs its own OAuth scope class. This is a development task that requires creating, compiling, and deploying Java classes.

When You Need Custom Scopes

Multi-Site Architecture:

If your AEM instance manages multiple websites with different permission boundaries
When authors have access to specific sites but not others
Example: Authors for Site A can access /content/sitea but not /content/siteb

Specialized Content Types:

Experience Fragments with site-specific access patterns
Campaign content with restricted access
Multi-brand environments with separate governance

Permission Granularity:

Different operations (read vs write) for different content areas
Workflow-specific permissions (launches vs direct editing)
Integration-specific requirements (publish vs author operations)

Scope Creation Examples

Example 1: Site-Specific Author Scopes

// Site A Author Scope
private static final String RESOURCE_URI = "/content/sitea";
private static final String SCOPE_NAME = "sitea_author";

// Site B Author Scope  
private static final String RESOURCE_URI = "/content/siteb";
private static final String SCOPE_NAME = "siteb_author";

Example 2: Experience Fragment Scopes

// Site-specific Experience Fragments
private static final String RESOURCE_URI = "/content/experience-fragments/sitea";
private static final String SCOPE_NAME = "sitea_experience_fragments";

Example 3: Operation-Specific Scopes

// Read-only content access
private static final String RESOURCE_URI = "/content/sitea";
private static final String SCOPE_NAME = "sitea_read_only";
// Only includes PrivilegeConstants.JCR_READ in getPrivileges()

// Full authoring access
private static final String RESOURCE_URI = "/content/sitea";  
private static final String SCOPE_NAME = "sitea_full_author";
// Includes JCR_READ, REP_WRITE, JCR_LOCK_MANAGEMENT, etc.

Engineering Implementation Process

Step 1: Analyze Your Content Architecture

Map out all content paths that need different access controls
Identify user groups and their permission boundaries
Document required operations per content area

Step 2: Design Scope Classes

Create one scope class per unique permission requirement
Name scopes descriptively (e.g., SiteAAuthorScope, SiteBExperienceFragmentScope)
Set appropriate RESOURCE_URI and privilege combinations

Step 3: Development and Deployment

Create Java Classes: Base each on the ExampleScope.java template above
Compile to OSGi Bundle: Package all scopes into a single bundle
Deploy to AEM: Install bundle on all author instances
Verify Registration: Check OAuth client configuration shows new scopes
Test Access: Validate each scope grants expected permissions

Step 4: Permission Alignment

Ensure authenticating users have JCR permissions matching each scope’s RESOURCE_URI
Update user group memberships to align with scope boundaries
Test OAuth authorization with different user accounts

Each scope must have a corresponding user permission. If a scope grants access to /content/sitea but the authenticating user lacks permissions to that path, OAuth authorization will fail.

This is a one-time engineering effort per AEM environment. Once scopes are deployed, they can be reused across multiple OAuth clients and integrations.

Alternative: Dynamic Scopes Package

Simplified Scope Management OptionFor organizations that prefer to avoid custom Java development, Gradial offers a pre-built dynamic scopes package that enables scope configuration through OSGi settings instead of code deployment.Benefits of Dynamic Scopes:

No Java development required
Configure scopes via OSGi configuration files
Update scope permissions without code deployments
Ideal for environments with limited development resources
Supports the same permission granularity as custom scopes

How It Works:

Deploy Gradial’s dynamic scopes OSGi bundle once
Create scope configurations using OSGi .config files
Define resource paths and permissions declaratively
Manage scope changes through configuration management

Interested in Dynamic Scopes? Contact your Gradial representative to learn more about the dynamic scopes package and whether it’s suitable for your environment and requirements.

Gradial can provide additional scope templates for specific use cases if needed.

Configure User Permissions

Who performs this step: AEM Administrator or user with security administration privilegesOAuth scopes only work if the authenticating user has the corresponding JCR permissions. This section details the permissions required for both the authenticating user and the oauthservice system user.

Required JCR Permissions

The authenticating user needs specific read and write permissions that match your OAuth scope definitions:Read Permissions Required:

/apps - Application configurations and components
/bin - Binary servlets and utilities
/conf - Configuration settings
/content - All content areas
/libs - System libraries

Write Permissions Required:

/content/launches - For launch-based workflows (default)
OR /content/<your-website-path> - Direct content modification (if not using launches)
/content/dam - Digital Asset Management operations
/content/cq:tags - Tag management

Special Permissions Required:

jcr:versionManagement on /content/launches - Required for version control operations on launches
jcr:lockManagement on relevant paths - Required for content locking during edits

Permission Assignment for Authenticating Users

The user who authorizes OAuth access must have permissions that match the requested scopes:

Navigate to AEM Security Console
- Go to Tools → Security → Users
- Locate the user account that will authorize OAuth access
Assign to Author Groups
- Add the user to appropriate author groups
- Ensure the groups have permissions matching your OAuth scopes
Verify Scope Alignment
- If your scope grants access to /content/mysite, ensure the user has author permissions for that path
- If using asset scopes, ensure the user can upload/manage assets in the corresponding DAM folders

OAuth authorization will fail if the authenticating user lacks permissions for the requested scopes. The user must have at least the same permissions defined in your OAuth scope classes.

Permission Verification

Test user permissions before OAuth configuration:

Access Control Testing
- Navigate to <AEM-HOST>:<PORT>/security/permissions.html
- Search for the user account
- Verify permissions match your OAuth scope paths
Content Access Testing
- Log in as the user and verify they can access/modify content in scope paths
- Test launch creation if using launch-based workflows
- Test asset upload if using DAM scopes

Configure oauthservice System User Permissions

About the oauthservice UserThe oauthservice is a built-in system user that AEM creates to handle OAuth token operations. This user must have enhanced permissions beyond regular users to manage access control for OAuth scopes.

Required Permissions for oauthservice

The oauthservice user needs all the same permissions as your authenticating users plus additional access control privileges:Standard Permissions (same as authenticating users):

Read access to: /apps, /bin, /conf, /content, /etc, /home, /libs, /var
Write access to: /content/launches, /content/dam, /content/cq:tags, or your specific site paths
Special permissions: jcr:versionManagement, jcr:lockManagement

Additional System Privileges Required:

jcr:readAccessControl - Read permission metadata and access control lists
jcr:modifyAccessControl - Modify access control for OAuth scope validation

Permission Assignment Steps

Access the Security Console
- Navigate to <AEM-HOST>:<PORT>/security/permissions.html/principal/oauthservice?filter=user
- This shows current permissions for the oauthservice user
Verify Current Permissions
- Check that oauthservice has read access to all paths defined in your OAuth scopes
- Verify write access to content paths where Gradial will operate
Add Missing Permissions
- Add any missing read/write permissions to match your OAuth scope definitions
- Ensure jcr:readAccessControl and jcr:modifyAccessControl are present
Alternative: Group-Based Assignment
- Create a dedicated “OAuth Service Users” group
- Assign all required permissions to the group
- Add oauthservice user to the group

The oauthservice user must have equal or greater permissions than your OAuth scopes grant. Missing permissions will cause OAuth authorization failures.

The oauthservice user automatically appears in AEM after the first OAuth request. If not visible, complete the OAuth client setup first.

Configure OAuth Server Authentication Handler

What this step does: Configures AEM to prioritize OAuth authentication over other authentication methods.

Access OSGi Configuration

Open the Configuration Manager
- Navigate to <AEM-HOST>:<PORT>/system/console/configMgr
- Use admin credentials to access the OSGi console
Locate the OAuth Handler
- Search for “Adobe Granite OAuth Server Authentication Handler”
- Click the configuration name to open the editor

Required Configuration Settings

Configure the following properties:

Property	Value	Purpose
`jaas.ranking`	`1100`	Sets priority over other auth handlers
`jaas.controlFlag`	`sufficient`	Allows OAuth to satisfy auth requirements
`oauth.offline.validation`	`true`	Enables token validation without callbacks
`jaas.realmName`	`jackrabbit.oak`	Specifies the security realm
`path`	`/`	Applies OAuth to all paths

Step-by-Step Configuration

Set Authentication Priority
- Find jaas.ranking field
- Enter 1100 (or higher if you have custom auth handlers with high rankings)
- This ensures OAuth takes precedence over basic authentication
Configure Control Flag
- Set jaas.controlFlag to sufficient
- This allows OAuth to fulfill authentication requirements independently
Enable Offline Validation
- Check oauth.offline.validation to true
- Enables token validation without requiring external callbacks
Set Realm and Path
- jaas.realmName: Use jackrabbit.oak (AEM’s default security realm)
- path: Set to / to apply OAuth authentication to all AEM paths
Save Configuration
- Click “Save” to apply the changes
- The configuration takes effect immediately

Example OSGi Configuration File

For deployment automation, use this .config file format:

jaas.controlFlag="sufficient"
oauth.offline.validation=B"true"
jaas.ranking=I"1100"
jaas.realmName="jackrabbit.oak"
path="/"

The “B” prefix indicates Boolean type and “I” indicates Integer type in OSGi configuration files.

Verification

After configuration:

Check that the configuration appears in the OSGi console
Verify no error messages in the AEM error logs
Test OAuth authentication with a simple scope request

Incorrect jaas.ranking values may cause OAuth authentication to be bypassed. Ensure the ranking is higher than other authentication handlers.

Configure Service-to-Service (2-Legged)

In the OAuth client config, click Download Private Key
Securely provide the private key to Gradial for JWT signing

Testing

To test scopes, open the consent URL:

http://<AEM-HOST>:<PORT>/oauth/authorize?response_type=code&client_id=CLIENT_ID&scope=SCOPE1 SCOPE2&redirect_uri=REDIRECT_URI

You should see a bullet for each requested scope. Authorizing should return a code in the URL bar if the user has permissions to the scopes. If the user does not have permissions, it will not return a code.

Gradial can provide a separate testing guide for completing the flow to retrieve and use access tokens if needed.

Need Help?

Contact your Gradial representative for additional support with your AEM 6.5 integration.

Get Started

Platform Fundamentals

Core Workflows

Overview

Authentication Methods

OAuth 2.0 Client (Preferred)

Basic Authentication

OAuth 2.0 Integration Steps

OAuth 2.0 Technical Details

On-behalf-of (3-legged)

Service-to-service (2-legged)

Integration Steps

When You Need Custom Scopes

Scope Creation Examples

Engineering Implementation Process

Alternative: Dynamic Scopes Package

Required JCR Permissions

Permission Assignment for Authenticating Users

Permission Verification

Required Permissions for oauthservice

Permission Assignment Steps

Access OSGi Configuration

Required Configuration Settings

Step-by-Step Configuration

Example OSGi Configuration File

Verification

Need Help?

Get Started

Platform Fundamentals

Core Workflows

​Overview

​Authentication Methods

OAuth 2.0 Client (Preferred)

Basic Authentication

​OAuth 2.0 Integration Steps

​OAuth 2.0 Technical Details

On-behalf-of (3-legged)

Service-to-service (2-legged)

​Integration Steps

​When You Need Custom Scopes

​Scope Creation Examples

​Engineering Implementation Process

​Alternative: Dynamic Scopes Package

​Required JCR Permissions

​Permission Assignment for Authenticating Users

​Permission Verification

​Required Permissions for oauthservice

​Permission Assignment Steps

​Access OSGi Configuration

​Required Configuration Settings

​Step-by-Step Configuration

​Example OSGi Configuration File

​Verification

​Need Help?

Overview

Authentication Methods

OAuth 2.0 Integration Steps

OAuth 2.0 Technical Details

Integration Steps

When You Need Custom Scopes

Scope Creation Examples

Engineering Implementation Process

Alternative: Dynamic Scopes Package

Required JCR Permissions

Permission Assignment for Authenticating Users

Permission Verification

Required Permissions for oauthservice

Permission Assignment Steps

Access OSGi Configuration

Required Configuration Settings

Step-by-Step Configuration

Example OSGi Configuration File

Verification

Need Help?