Connect AEM 6.5

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

• 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

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";
    }
}

• 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

• 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

​

When You Need Custom Scopes

• 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

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

• 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

// 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";

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

// 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

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

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

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

• 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

​

Alternative: Dynamic Scopes Package

• 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

• 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

​

Required JCR Permissions (6.5)

​

Permission Assignment for Authenticating Users

1. Navigate to AEM Security Console
   • Go to Tools → Security → Users
   • Locate the user account that will authorize OAuth access
2. Assign to Author Groups
   • Add the user to appropriate author groups
   • Ensure the groups have permissions matching your OAuth scopes
3. 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

​

Permission Verification

1. Access Control Testing
   • Navigate to <AEM-HOST>:<PORT>/security/permissions.html
   • Search for the user account
   • Verify permissions match your OAuth scope paths
2. 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

​

Required Permissions for oauthservice

• 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

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

​

Permission Assignment Steps

1. Access the Security Console
   • Navigate to <AEM-HOST>:<PORT>/security/permissions.html/principal/oauthservice?filter=user
   • This shows current permissions for the oauthservice user
2. 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
3. Add Missing Permissions
   • Add any missing read/write permissions to match your OAuth scope definitions
   • Ensure jcr:readAccessControl and jcr:modifyAccessControl are present
4. Alternative: Group-Based Assignment
   • Create a dedicated “OAuth Service Users” group
   • Assign all required permissions to the group
   • Add oauthservice user to the group

​

Access OSGi Configuration

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

​

Required Configuration Settings

​

Step-by-Step Configuration

1. 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
2. Configure Control Flag
   • Set jaas.controlFlag to sufficient
   • This allows OAuth to fulfill authentication requirements independently
3. Enable Offline Validation
   • Check oauth.offline.validation to true
   • Enables token validation without requiring external callbacks
4. 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
5. Save Configuration
   • Click “Save” to apply the changes
   • The configuration takes effect immediately

​

Example OSGi Configuration File

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

​

Verification

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

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