Skip to main content

​
Overview

​
Authentication Methods

AEM 6.5 supports two primary authentication methods for external integrations:

OAuth 2.0 (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.

​
Integration Steps

1

Configure Adobe Granite OAuth Server Authentication Handler

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

​
Determine the OAuth Module Ranking

  1. Navigate to <AEM-HOST>:<PORT>/system/console/jaas
  2. You will see a list of registered LoginModules
  3. Note the highest ranking number in the list - you’ll need to set the OAuth ranking higher than this value

​
Configure the OAuth Handler

  1. Navigate to <AEM-HOST>:<PORT>/system/console/configMgr
  2. Find “Adobe Granite OAuth Server Authentication Handler” in the list and click to edit
  3. Ensure the values are as follows:
    • Path: /
    • jaas.controlFlag: sufficient
    • jaas.realmName: jackrabbit.oak
    • jaas.ranking: Set this to a value higher than the largest number in the LoginModules list (e.g., if the highest is 2001, use 2002 or higher)
    • Offline Validation: checked
The jaas.ranking value must be higher than all other authentication handlers to ensure OAuth takes precedence.
2

Configure oauthservice User Account

What this step does: Configures the system user that AEM uses to manage OAuth token operations and scope validation.About the oauthservice UserThe oauthservice is a built-in system user provided by Adobe that AEM creates to handle OAuth token operations. This user requires elevated permissions to create and apply permissions for scoped requests.

​
Access the Permissions Console

Navigate to <AEM-HOST>:<PORT>/security/permissions.html/principal/oauthservice?filter=user

​
Add Required ACEs (Access Control Entries)

Configure the following permissions for the oauthservice user:Path: /
  • Privileges: jcr:versionManagement, jcr:modifyAccessControl, jcr:lockManagement, jcr:readAccessControl, jcr:read
Path: /content
  • Privileges: rep:write
The oauthservice user must have elevated permissions above the authenticated OAuth token user, as it is responsible for creating and applying permissions for scoped requests.
These permissions are essential for OAuth functionality. Missing permissions will cause OAuth authorization failures.
3

Configure OAuth Client

What this step does: Creates the OAuth client configuration that Gradial will use to authenticate with AEM.

​
Create the OAuth Client

  1. Navigate to <AEM-HOST>:<PORT>/libs/granite/oauth/content/clients.html
  2. Click “Create” in the top right corner
  3. Enter the following values:
    • Name: Gradial
    • Redirect URI: https://www.gradial.com/api/v1/auth/aem65/oauth2/callback
  4. Click “Save”

​
Retrieve OAuth Credentials

  1. Click into the newly created OAuth Client
  2. Note the following values (you’ll need to provide these to Gradial):
    • Client ID
    • Client Secret
  3. Click “Download Private Key” and securely save the file
Keep the Client Secret and Private Key secure. These credentials provide access to your AEM instance and should be treated as sensitive security credentials.
You will need to provide the Client ID, Client Secret, and Private Key to your Gradial representative during the integration setup process.
4

Configure OAuth Scopes

What this step does: Deploys the OAuth scopes that define what permissions Gradial can request from AEM.

​
Gradial OAuth Scopes Package

Gradial provides an easy, effective method for deploying and updating OAuth scopes without custom Java development.Installation Options:
  1. GitHub Repository: https://github.com/gradial/gradial-65-oauth
  2. Release Package: Download Release Installation
If you prefer not to use Gradial’s package, you can deploy your own custom OAuth scopes as part of your AEM package install. See the GitHub repository for examples of OSGI configuration files.

​
Scope Configuration

Each OAuth scope is defined by an OSGI configuration file stored in:
ui.config/src/main/content/jcr_root/apps/gradial-65/osgiconfig/config.author
You can deploy custom scopes by following the structure of the existing scope OSGI configuration files.

​
Default Scopes

By default, Gradial installs a read_all scope that provides read access to all system paths required for operation:
  • /apps - Component and application definitions
  • /libs - System libraries
  • /etc - Legacy configurations
  • /conf - Context-aware configurations
  • /var - Variable content (optional, required when workflow execution is needed)
We highly recommend keeping the read_all scope in place. You can further limit the paths Gradial can access during the onboarding process.

​
Gradial OAuth Scope Definitions

The following table defines the standard OAuth scopes provided by Gradial:
Scope NameResource PathPrivileges
launch_author/content/launchesjcr:read, rep:write, jcr:lockManagement, jcr:versionManagement
publish_assets/content/damjcr:read, jcr:addChildNodes, crx:replicate
read_all/jcr:read
site_author/contentjcr:read, rep:write, jcr:lockManagement, jcr:versionManagement
site_xf_author/content/experience-fragmentsjcr:read, rep:write, jcr:lockManagement, jcr:versionManagement
tags_author/content/cq:tagsjcr:read, rep:write, crx:replicate, jcr:versionManagement
upload_assets/content/damjcr:read, rep:write, jcr:lockManagement, jcr:versionManagement
You must supply jcr:versionManagement for sites and DAM paths. Failure to do so will result in errors when creating and updating pages.

​
Custom Scopes for Multi-Site Environments

If you need custom scopes for specific sites or permission boundaries, you can create additional scope configurations. For example:
  • Site-specific author scopes: /content/sitea, /content/siteb
  • Experience Fragment scopes: /content/experience-fragments/sitea
  • Custom content paths: /content/dam/myproject
Each scope should align with your user permission structure and content architecture.
If using 3-legged authentication, ensure that authenticating user has JCR permissions matching the OAuth scopes you configure. OAuth authorization will fail if users lack the necessary permissions.
5

Testing

What this step does: Validates that your OAuth configuration is working correctly by testing scope authorization.

​
Test OAuth Scopes

To test your OAuth configuration and scopes, open the OAuth consent URL in a browser:
http://<AEM-HOST>:<PORT>/oauth/authorize?response_type=code&client_id=CLIENT_ID&scope=SCOPE1 SCOPE2&redirect_uri=REDIRECT_URI
Replace the placeholders:
  • <AEM-HOST>:<PORT> - Your AEM author instance URL
  • CLIENT_ID - The Client ID from Step 3
  • SCOPE1 SCOPE2 - Space-separated list of scopes to test (e.g., read_all site_author upload_assets)
  • REDIRECT_URI - The redirect URI configured in Step 3

​
Expected Behavior

  • You should see a consent dialog displaying each requested scope
  • After authorizing, the browser should redirect to the redirect URI with an authorization code in the URL
  • If the authenticating user lacks permissions for the requested scopes, no authorization code will be returned
Contact your Gradial representative if you need assistance with testing or completing the full OAuth flow to retrieve and use access tokens.

​
Need Help?

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