ÃÛ¶¹ÊÓƵ

DocumentationAEMAEM TutorialsAEM as a Cloud Service Tutorials

Invoke OpenAPI-based AEM APIs using OAuth Single Page App

Last update: Thu Apr 03 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Intermediate
  • Developer
  • Leader

Learn how to invoke OpenAPI-based AEM APIs on AEM as a Cloud Service using OAuth Single Page App authentication. It follows the OAuth 2.0 PKCE (Proof Key for Code Exchange) flow for user-based authentication in a Single Page Application (SPA).

OAuth Single Page App authentication is ideal for JavaScript-based applications running in the browser. Whether they lack a backend server or need to fetch access tokens to interact with AEM APIs on behalf of a user.

The PKCE flow extends the OAuth 2.0 authorization_code grant type, enhancing security by preventing authorization code interception. For more information, see the Difference between OAuth Server-to-Server vs Web App vs Single Page App credentials section.

AVAILABILITY
OpenAPI-based AEM APIs are available as part of an early access program. If you are interested in accessing them, we encourage you to email aem-apis@adobe.com with a description of your use case.

What you learn what-you-learn

In this tutorial, you learn how to:

  • Configure an ÃÛ¶¹ÊÓƵ Developer Console (ADC) project to access the OpenAPI-based AEM APIs using OAuth Single Page App authentication or commonly known as OAuth 2.0 PKCE flow.

  • Implement the OAuth Single Page App authentication flow in a custom SPA.

    • IMS user authentication and app authorization.
    • Access token retrieval using OAuth 2.0 PKCE flow.
    • Use the access token to invoke OpenAPI-based AEM APIs.

Before you start, make sure you reviewed the following:

WKND SPA overview and functional flow wknd-spa-overview-and-functional-flow

Let’s explore what the WKND SPA is, how it’s built, and how it functions.

The WKND SPA is a React-based Single Page Application that demonstrates how to securely obtain a user-specific access token and interact with AEM APIs directly from the client side. It implements the OAuth 2.0 PKCE authentication flow through ÃÛ¶¹ÊÓƵ IMS and integrates with two key AEM APIs:

  1. Sites API: For accessing Content Fragment models
  2. Assets API: For managing DAM folders

The ÃÛ¶¹ÊÓƵ Developer Console (ADC) project is configured to enable OAuth Single Page App authentication, providing the required client_id to initiate the OAuth 2.0 PKCE flow.

IMPORTANT
The ADC Project does NOT provide a client_secret. Instead, the SPA generates a code_verifier and code_challenge to securely exchange the authorization code for an access token. It eliminates the need to store a client secret on the client side, enhancing security.

video poster

Transcript
In this tutorial, we’ll explore how to use the OAuth Single Page App authentication flow to enable user-based authentication for OpenAPI-based EEM APIs. OAuth Single Page App authentication, also known as OAuth PKC flow, is designed for JavaScript applications running in the browser, especially those that lack a backend server or need to interact with AEM APIs on behalf of a user. To demonstrate this, we’ll use a sample weekend spa. It is a React-based single-page application that securely obtains a user-specific access token and directly invokes AEM APIs from the client side. Now, let’s walk through how the weekend spa works. Everything starts when the user logs into the app. Once they initiate login, they’re redirected to ÃÛ¶¹ÊÓƵ IMS, ÃÛ¶¹ÊÓƵ’s identity management system for secure authentication. If it’s their first time, they’ll be prompted to consent to API access. After successfully signing in, ÃÛ¶¹ÊÓƵ IMS redirects the user back to the spa, along with an authorization code. The spa then securely exchanges this authorization code for a user-specific access token, which is stored in the browser’s local storage. This token is what allows the spa to make authenticated requests to AEM APIs on behalf of the user. Now, here’s what makes the PKC flow different from the traditional OAuth authorization code grant. In PKC, the authorization code never goes to a backend server. Instead, it’s handled entirely by the spa. To ensure security, the spa generates a code verifier and a code challenge. The code challenge, which is a hashed version of the code verifier, is sent when the user logs in. Later, during the token exchange, the spa sends the original code verifier, ensuring that only the same client that initiated the request can complete the flow. With authentication in place, let’s take a look at how the weekend spa interacts with AEM APIs. In the site’s API tab, clicking Fetch Content Fragment Models retrieves the first 10 content fragment models from AEM and displays their key details in a table. In the Assets API tab, clicking Fetch DAM Folders fetches the first 10 DAM folders and displays them as well. The spa also lets you create a new DAM folder by entering a name and clicking Create DAM Folder. Once created, the new folder will appear in the AEM Assets interface. To delete a DAM folder, simply click the Delete button next to it. You can inspect all AEM API requests and responses in the browser console. Now, let’s quickly go over some key details about how this spa is built. It’s developed using React, with React context handling authentication state management, and React router managing navigation. But you’re not limited to React. You can use any JavaScript framework to build your own spa and interact with AEM APIs in a similar way. So, are you ready to implement this in your own project? Follow this tutorial to set up the OAuth single page app authentication flow and start integrating your custom spas with AEM as a cloud service. Thanks for watching.

The following diagram illustrates the functional flow of the WKND SPA getting user-specific access token to invoke OpenAPI-based AEM APIs:

WKND SPA Auth Flow

  1. The SPA initiates the authentication flow by directing the user to the ÃÛ¶¹ÊÓƵ Identity Management System (IMS) via an authorization request.
  2. As part of the authorization request, the SPA sends the client_id, redirect_uri, and code_challenge to IMS, following the OAuth 2.0 PKCE flow. The SPA generates a random code_verifier, hashes it using SHA-256, and Base64 encodes the result to create the code_challenge.
  3. The IMS authenticates the user and, upon successful authentication, issues an authorization_code, which is sent back to the SPA via the redirect_uri.
  4. The SPA exchanges the authorization_code for an access token by sending a POST request to the IMS token endpoint. It includes the code_verifier in the request to validate the code_challenge sent earlier. This ensures that the authorization request (Step 2) and token request (Step 4) are linked to the same authentication flow, preventing interception attacks.
  5. The IMS validates the code_verifier and returns the user-specific access token.
  6. The SPA includes the access token in API requests to AEM to authenticate and retrieve user-specific content.

The WKND SPA is a -based application and it uses the for authentication state management, for navigation.

Other SPA frameworks like Angular, Vue, or vanilla JavaScript can be used to create SPA that integrate with the ÃÛ¶¹ÊÓƵ APIs using the approaches illustrated in this tutorial.

How to use this tutorial how-to-use-this-tutorial

You can approach this tutorial in two ways:

  • Review SPA key code snippets: Understand the OAuth Single Page App authentication flow and explore the key API call implementations in the WKND SPA.
  • Setup and run the SPA: Follow step-by-step instructions to configure and run the WKND SPA on your local machine.

Choose the path that best fits your needs!

Review SPA key code snippets review-spa-key-code-snippets

Let’s dive into the key code snippets from the WKND SPA that demonstrate how to:

  • Obtain a user-specific access token using the OAuth Single Page App authentication flow.

  • Invoke OpenAPI-based AEM APIs directly from the client side.

These snippets help you understand the authentication process and API interactions within the SPA.

Download the SPA code download-the-spa-code

  1. Download the WKND SPA & AEM APIs - Demo App zip file and extract it.

  2. Navigate to the extracted folder and open the .env.example file in your favorite code editor. Review the required configuration parameters.

    code language-plaintext 
    ########################################################################
# ÃÛ¶¹ÊÓƵ IMS, ÃÛ¶¹ÊÓƵ Developer Console (ADC), and AEM as a Cloud Service Information
########################################################################
# ÃÛ¶¹ÊÓƵ IMS OAuth endpoints
REACT_APP_ADOBE_IMS_AUTHORIZATION_ENDPOINT=https://ims-na1.adobelogin.com/ims/authorize/v2
REACT_APP_ADOBE_IMS_TOKEN_ENDPOINT=https://ims-na1.adobelogin.com/ims/token/v3

# ÃÛ¶¹ÊÓƵ Developer Console (ADC) Project's OAuth Single-Page App credential
REACT_APP_ADC_CLIENT_ID=<ADC Project OAuth Single-Page App credential ClientID>
REACT_APP_ADC_SCOPES=<ADC Project OAuth Single-Page App credential Scopes>

# AEM Assets Information
REACT_APP_AEM_ASSET_HOSTNAME=<AEMCS Hostname, e.g., https://author-p63947-e1502138.adobeaemcloud.com/>

################################################
# Single Page Application Information
################################################

# Enable HTTPS for local development
HTTPS=true
PORT=3001

# SSL Certificate and Key for local development
SSL_CRT_FILE=./ssl/server.crt
SSL_KEY_FILE=./ssl/server.key

# The URL to which the user will be redirected after the OAuth flow is complete
REACT_APP_REDIRECT_URI=https://localhost:3000/callback

    You need to replace the placeholders with the actual values from the ÃÛ¶¹ÊÓƵ Developer Console (ADC) Project and AEM as a Cloud Service Assets instance.

IMS user authentication and SPA authorization ims-user-authentication-and-spa-authorization

Let’s explore the code that handles IMS user authentication and SPA authorization. To retrieve content fragment models and DAM folders, the user must authenticate with ÃÛ¶¹ÊÓƵ IMS and grant the WKND SPA permission to access AEM APIs on their behalf.

During the initial login, the user is prompted to provide consent, allowing the WKND SPA to securely access the required resources.

WKND SPA First Login and Consent

  1. In src/context/IMSAuthContext.js file, the login function initiates the IMS user authentication and app authorization flow. It generates a random code_verifier and code_challenge to securely exchange the code for an access token. The code_verifier is stored in the local storage for later use. As mentioned earlier, the SPA does not store or use the client_secret, it generates one on the fly and uses it in two steps: authorize and token requests.

    code language-javascript 
    ...
const login = async () => {
    try {
        const codeVerifier = generateCodeVerifier();
        const codeChallenge = generateCodeChallenge(codeVerifier);

        localStorage.setItem(STORAGE_KEYS.CODE_VERIFIER, codeVerifier);

        const params = new URLSearchParams(
            getAuthParams(AUTH_METHODS.S256, codeChallenge, codeVerifier)
        );

        window.location.href = `${
            APP_CONFIG.adobe.ims.authorizationEndpoint //https://ims-na1.adobelogin.com/ims/authorize/v2
        }?${params.toString()}`;
    } catch (error) {
        console.error("Login initialization failed:", error);
        throw error;
    }
};
...

// Generate a random code verifier
export function generateCodeVerifier() {
    const array = new Uint8Array(32);
    window.crypto.getRandomValues(array);
    const wordArray = CryptoJS.lib.WordArray.create(array);
    return base64URLEncode(wordArray);
}

// Generate code challenge using SHA-256
export function generateCodeChallenge(codeVerifier) {
    const hash = CryptoJS.SHA256(codeVerifier);
    return base64URLEncode(hash);
}

// Get authorization URL parameters
const getAuthParams = useCallback((method, codeChallenge, codeVerifier) => {
    const baseParams = {
        client_id: APP_CONFIG.adobe.adc.clientId, // ADC Project OAuth Single-Page App credential ClientID
        scope: APP_CONFIG.adobe.adc.scopes, // ADC Project OAuth Single-Page App credential Scopes
        response_type: "code",
        redirect_uri: APP_CONFIG.adobe.spa.redirectUri, // SPA redirect URI https://localhost:3000/callback
        code_challenge_method: method, // S256 or plain
    };

    return {
        ...baseParams,
        code_challenge:
            method === AUTH_METHODS.S256 ? codeChallenge : codeVerifier,
        };
}, []);
...

    If the user is not authenticated against the ÃÛ¶¹ÊÓƵ IMS, the ÃÛ¶¹ÊÓƵ ID login page is displayed asking the user to authenticate.

    If already authenticated, the user is redirected back to the specified redirect_uri of the WKND SPA with an authorization_code.

Access token retrieval using OAuth 2.0 PKCE flow access-token-retrieval-using-oauth-20-pkce-flow

The WKND SPA securely exchanges the authorization_code with the ÃÛ¶¹ÊÓƵ IMS for a user-specific access token using the client_id and code_verifier.

  1. In the src/context/IMSAuthContext.js file, the exchangeCodeForToken function exchanges the authorization_code for a user-specific access token.

    code language-javascript 
    ...
// Handle the callback from the ÃÛ¶¹ÊÓƵ IMS authorization endpoint
const handleCallback = async (code) => {
    if (authState.isProcessingCallback) return;

    try {
        updateAuthState({ isProcessingCallback: true });

        const data = await exchangeCodeForToken(code);

        if (data.access_token) {
            handleStorageToken(data.access_token);
            localStorage.removeItem(STORAGE_KEYS.CODE_VERIFIER);
        }
    } catch (error) {
        console.error("Error exchanging code for token:", error);
        throw error;
    } finally {
        updateAuthState({ isProcessingCallback: false });
    }
};

...
// Exchange the authorization code for an access token
const exchangeCodeForToken = useCallback(async (code) => {
    const codeVerifier = localStorage.getItem(STORAGE_KEYS.CODE_VERIFIER);

    if (!codeVerifier) {
        throw new Error("No code verifier found");
    }

    //https://ims-na1.adobelogin.com/ims/token/v3
    const response = await fetch(APP_CONFIG.adobe.ims.tokenEndpoint, {
        method: "POST",
        headers: { "Content-Type": "application/x-www-form-urlencoded" },
        body: new URLSearchParams({
            grant_type: "authorization_code",
            client_id: APP_CONFIG.adobe.adc.clientId, // ADC Project OAuth Single-Page App credential ClientID
            code_verifier: codeVerifier, // Code verifier generated during login
            code, // Authorization code received from the IMS
            redirect_uri: `${window.location.origin}/callback`,
        }),
    });

    if (!response.ok) {
        throw new Error("Token request failed");
    }

    return response.json();
}, []);

const handleStorageToken = useCallback(
    (token) => {
        if (token) {
            localStorage.setItem(STORAGE_KEYS.ACCESS_TOKEN, token);
            updateAuthState({ isLoggedIn: true, accessToken: token });
        }
    },
    [updateAuthState]
);
...

    The access token is stored in the browser’s local storage and used in the subsequent API calls to the AEM APIs.

Accessing OpenAPI-based AEM APIs using the access token accessing-openapi-based-aem-apis-using-the-access-token

The WKND SPA uses the user-specific access token to invoke the content fragment models and DAM folders API endpoints.

In the src/components/InvokeAemApis.js file, the fetchContentFragmentModels function demonstrates how to use the access token to invoke the OpenAPI-based AEM APIs from the client side.

    ...
  // Fetch Content Fragment Models
  const fetchContentFragmentModels = useCallback(async () => {
    try {
      updateState({ isLoading: true, error: null });
      const data = await makeApiRequest({
        endpoint: `${API_PATHS.CF_MODELS}?cursor=0&limit=10&projection=summary`,
      });
      updateState({ cfModels: data.items });
    } catch (err) {
      updateState({ error: err.message });
      console.error("Error fetching CF models:", err);
    } finally {
      updateState({ isLoading: false });
    }
  }, [makeApiRequest, updateState]);

  // Common API request helper
  const makeApiRequest = useCallback(
    async ({ endpoint, method = "GET", passAPIKey = false, body = null }) => {

      // Get the access token from the local storage
      const token = localStorage.getItem("adobe_ims_access_token");
      if (!token) {
        throw new Error("No access token available. Please login again.");
      }

      const headers = {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
        ...(passAPIKey && { "x-api-key": APP_CONFIG.adobe.adc.clientId }),
      };

      const response = await fetch(
        `${APP_CONFIG.adobe.aem.hostname}${endpoint}`,
        {
          method,
          headers,
          ...(body && { body: JSON.stringify(body) }),
        }
      );

      if (!response.ok) {
        throw new Error(`API request failed: ${response.statusText}`);
      }

      return method === "DELETE" ? null : response.json();
    },
    []
  );
  ...

Setup and run the SPA setup-and-run-the-spa

Let’s configure and run the WKND SPA on your local machine to understand the OAuth Single Page App authentication flow and API calls.

Prerequisites prerequisites

To complete this tutorial, you need:

  • Modernized AEM as a Cloud Service environment with the following:

    • AEM Release 2024.10.18459.20241031T210302Z or later.
    • New style Product Profiles (if environment was created before November 2024)

    See the Set-up OpenAPI-based AEM APIs article for more details.

  • The sample project must be deployed on to it.

  • Access to the .

  • Install on your local machine to run the sample NodeJS application.

Development steps development-steps

The high-level development steps are:

  1. Configure ADC Project

    1. Add the Assets and Sites APIs.
    2. Configure OAuth Single Page App credentials.

  2. Configure the AEM instance

    1. To enable ADC Project communication
    2. To allow the SPA to access the AEM APIs by configuring the CORS settings.

  3. Configure and run the WKND SPA on your local machine

  4. Verify the end-to-end flow

Configure ADC Project configure-adc-project

The configure ADC Project step is repeated from the Setup OpenAPI-based AEM APIs. It is repeated to add the Assets, Sites API and configure its authentication method as OAuth Single Page App.

  1. From the , open the desired project.

  2. To add AEM APIs, click on the Add API button.

    Add API

  3. In the Add API dialog, filter by Experience Cloud and select the AEM CS Sites Content Management card and click Next.

    Add AEM API

  4. Next, in the Configure API dialog, select the User Authentication authentication option and click Next.

    Configure AEM API

  5. In the next Configure API dialog, select the OAuth Single-Page App authentication option and click Next.

    Configure OAuth Single-Page App

  6. In the Configure OAuth Single-Page App dialog, enter the following details and click Next.

    • Default redirect URI: https://localhost:3001/callback
    • Redirect URI pattern: https://localhost:3001/callback

    Configure OAuth Single-Page App

  7. Review the available scopes and click Save configured API.

    Save configured API

  8. Repeat the above steps to add the AEM Assets Author API.

  9. Review the AEM API and authentication configuration.

    AEM API configuration

    Authentication configuration

Configure AEM instance to enable ADC Project communication configure-aem-instance-to-enable-adc-project-communication

Follow the instructions from the Setup OpenAPI-based AEM APIs article to configure the AEM instance to enable ADC Project communication.

AEM CORS configuration aem-cors-configuration

AEM as a Cloud Service’s Cross-Origin Resource Sharing (CORS) facilitates non-AEM web properties to make browser-based client-side calls to AEM APIs.

  1. In AEM Project, locate or create the com.adobe.granite.cors.impl.CORSPolicyImpl~wknd-graphql.cfg.json file from the /ui.config/src/main/content/jcr_root/apps/wknd/osgiconfig/config.author/ folder.

    Locate CORS configuration file

  2. Add the following configuration to the file.

    code language-json 
    {
    "alloworigin":[
      ""
    ],
    "alloworiginregexp":[
      "https://localhost:.*",
      "http://localhost:.*"
    ],
    "allowedpaths": [
      "/adobe/sites/.*",
      "/graphql/execute.json.*",
      "/content/_cq_graphql/wknd-shared/endpoint.json",
      "/content/experience-fragments/.*"
    ],
    "supportedheaders": [
      "Origin",
      "Accept",
      "X-Requested-With",
      "Content-Type",
      "Access-Control-Request-Method",
      "Access-Control-Request-Headers",
      "Authorization"
    ],
    "supportedmethods":[
      "GET",
      "HEAD",
      "POST"
    ],
    "maxage:Integer": 1800,
    "supportscredentials": true,
    "exposedheaders":[ "" ]
}

  3. Commit the config changes and push the changes to the remote Git repository the Cloud Manager pipeline is connected to.

  4. Deploy the above changes using the FullStack Pipeline in the Cloud Manager.

Configure and run the SPA configure-and-run-the-spa

  1. Download the WKND SPA & AEM APIs - Demo App zip file and extract it.

  2. Navigate to the extracted folder and copy the .env.example file to .env.

  3. Update the .env file with the required configuration parameters from the ÃÛ¶¹ÊÓƵ Developer Console (ADC) Project and AEM as a Cloud Service environment. For example:

    code language-plaintext 
    ########################################################################
# ÃÛ¶¹ÊÓƵ IMS, ÃÛ¶¹ÊÓƵ Developer Console (ADC), and AEM as a Cloud Service Information
########################################################################
# ÃÛ¶¹ÊÓƵ IMS OAuth endpoints
REACT_APP_ADOBE_IMS_AUTHORIZATION_ENDPOINT=https://ims-na1.adobelogin.com/ims/authorize/v2
REACT_APP_ADOBE_IMS_TOKEN_ENDPOINT=https://ims-na1.adobelogin.com/ims/token/v3
REACT_APP_ADOBE_IMS_USERINFO_ENDPOINT=https://ims-na1.adobelogin.com/ims/userinfo/v2

# ÃÛ¶¹ÊÓƵ Developer Console (ADC) Project's OAuth Single-Page App credential
REACT_APP_ADC_CLIENT_ID=ddsfs455a4a440c48c7474687c96945d
REACT_APP_ADC_SCOPES=ÃÛ¶¹ÊÓƵID,openid,aem.folders,aem.assets.author,aem.fragments.management

# AEM Assets Information
REACT_APP_AEM_ASSET_HOSTNAME=https://author-p69647-e1453424.adobeaemcloud.com/

################################################
# Single Page Application Information
################################################

# Enable HTTPS for local development
HTTPS=true
PORT=3001

# SSL Certificate and Key for local development
SSL_CRT_FILE=./ssl/server.crt
SSL_KEY_FILE=./ssl/server.key

# The URL to which the user will be redirected after the OAuth flow is complete
REACT_APP_REDIRECT_URI=https://localhost:3000/callback

  4. Open a terminal and navigate to the extracted folder. Install the required dependencies and start the WKND SPA using the following command.

    code language-bash 
    $ npm install
$ npm start

Verify the end-to-end flow verify-the-end-to-end-flow

  1. Open a browser and navigate to https://localhost:3001 to access the WKND SPA. Accept the self-signed certificate warning.

    WKND SPA Home

  2. Click the ÃÛ¶¹ÊÓƵ IMS Login button to initiate the OAuth Single Page App authentication flow.

  3. Authenticate against the ÃÛ¶¹ÊÓƵ IMS and provide the consent to allow the WKND SPA to access the resources on your behalf.

  4. Upon successful authentication, you are redirected back to the WKND SPA’s /invoke-aem-apis route and access token is stored in the browser’s local storage.

    WKND SPA Invoke AEM APIs

  5. From the https://localhost:3001/invoke-aem-apis route, click the Fetch Content Fragment Models button to invoke the Content Fragment Models API. The SPA displays the list of content fragment models.

    WKND SPA Fetch CF Models

  6. Likewise, in the Assets - Folders API tab, you can list, create and delete DAM folders.

    WKND SPA Assets API

  7. In the browser’s developer tools, you can inspect the network requests and responses to understand the API calls.

    WKND SPA Network Requests

IMPORTANT
If the authenticated user lacks the necessary permissions to list, create, or delete AEM resources, the API calls fails with a 403 Forbidden error. It ensures that, even if the user is authenticated and possesses a valid IMS access token, they cannot access AEM resources without the required permissions.

Review the SPA code review-the-spa-code

Let’s review the high-level code structure and main entry points of the WKND SPA. The SPA is built using the React framework and uses the React Context API for authentication and state management.

  1. The src/App.js file is the main entry point of the WKND SPA. The App component wraps the entire application and initializes the IMSAuthProvider context.

  2. The src/context/IMSAuthContext.js creates the ÃÛ¶¹ÊÓƵ IMSAuthContext to provide the authentication state to the children components. It includes the login, logout, and handleCallback functions to initiate the OAuth Single Page App authentication flow.

  3. The src/components folder contains various components to demonstrate the API calls to the AEM APIs. The InvokeAemApis.js component demonstrates how to use the access token to invoke the AEM APIs.

  4. The src/config/config.js file loads the environment variables from the .env file and exports them for use in the application.

  5. The src/utils/auth.js file contains utility functions to generate the code verifier and code challenge for the OAuth 2.0 PKCE flow.

  6. The ssl folder contains the self-signed certificate and key files to run the local SSL HTTP proxy.

You can develop or integrate the existing SPA with the ÃÛ¶¹ÊÓƵ APIs using the approaches illustrated in this tutorial.

Summary summary

In this tutorial, you learned how to invoke OpenAPI-based AEM APIs on AEM as a Cloud Service using user-based authentication from a Single Page App (SPA) via OAuth 2.0 PKCE flow.

Additional resources additional-resources

recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69