Generating Access Tokens for Server-Side APIs generating-access-tokens-for-server-side-apis

Some architectures rely on making calls to AEM as a Cloud Service from an application hosted on a server outside of AEM infrastructure. For example, a mobile application that calls a server, which then makes API requests to AEM as a Cloud Service.

The server-to-server flow is described below, along with a simplified flow for development. The AEM as a Cloud Service Developer Console is used to generate tokens needed for the authentication process.

The Server-to-server Flow the-server-to-server-flow

Users with an IMS org administrator role, and who are a member of the AEM Users or AEM Administrators Product Profile on AEM Author, can generate a set of credentials from AEM as a Cloud Service. Each credential is a JSON payload that includes a certificate (the public key), a private key, and a technical account consisting of a clientId and clientSecret. Those credentials can later be retrieved by a user with the AEM as a Cloud Service Environment administrator role and should be installed on a non-AEM server and treated carefully as a secret key. This JSON format file contains all the data required to integrate with an AEM as a Cloud Service API. The data is used to create a signed JWT token, which is exchanged with the Adobe Identity Management Services (IMS) for an IMS access token. This access token can then be used as a Bearer authentication token to make requests to AEM as a Cloud Service. The certificate in the credentials expires after one year by default, but they can be refreshed when needed, as described here.

The server-to-server flow involves the following steps:

Fetch the AEM as a Cloud Service Credentials fetch-the-aem-as-a-cloud-service-credentials

Users with access to the AEM as a Cloud Service developer console see the integrations tab in the Developer Console for a given environment. A user with the AEM as a Cloud Service Environment administrator role can create, view, or manage credentials.

Clicking Create new technical account, a set of credentials is created that includes client id, client secret, private key, certificate, and configuration for author and publish tiers of the environment, regardless of the pod selection.

A new browser tab opens up, displaying the credentials. You can use this view to download the credentials by pressing the download icon next to the status title:

After the credentials are created, they will appear under the Technical Accounts tab in the Integrations section:

Users can later view the credentials using the View action. In addition, as described later in the article, users can edit the credentials for the same technical account. They accomplish this editing by creating a private key or certificate, for cases when the certificate must be renewed or revoked.

Users with the AEM as a Cloud Service Environment Administrator role can later create credentials for additional technical accounts. This ability is useful when different APIs have differing access requirements. For example, read versus read-write.

Install the AEM Service Credentials on a Non-AEM Server install-the-aem-service-credentials-on-a-non-aem-server

The application making calls to AEM should be able to access the credentials for AEM as a Cloud Service, treating it as a secret.

Generate a JWT Token and Exchange It for an Access Token generate-a-jwt-token-and-exchange-it-for-an-access-token

Use the credentials to create a JWT token in a call to Adobe’s IMS service to retrieve an access token, which is valid for 24 hours.

The AEM CS Service Credentials may be exchanged for an access token using client libraries designed for this purpose. The client libraries are available from Adobe’s public GitHub repository, which contains more detailed guidance and latest information.

/*jshint node:true */
"use strict";

const fs = require('fs');
const exchange = require("@adobe/aemcs-api-client-lib");

const jsonfile = "aemcs-service-credentials.json";

var config = JSON.parse(fs.readFileSync(jsonfile, 'utf8'));
exchange(config).then(accessToken => {
    // output the access token in json form including when it will expire.
    console.log(JSON.stringify(accessToken,null,2));
}).catch(e => {
    console.log("Failed to exchange for access token ",e);
});

The same exchange can be performed in any language capable of generating a signed JWT Token with the correct format and calling the IMS Token Exchange APIs.

The access token defines when it expires, which is typically 24 hours. There is sample code in the git repository to manage an access token and refresh it before it expires.

Calling the AEM API calling-the-aem-api

Make the appropriate server-to-server API calls to an AEM as a Cloud Service environment, including the access token in the header. So for the “Authorization” header, use the value "Bearer <access_token>". For example, using curl:

curl -H "Authorization: Bearer <your_ims_access_token>" https://author-p123123-e23423423.adobeaemcloud.com/content/dam.json

Set the Appropriate Permissions for the Technical Account User in AEM set-the-appropriate-permissions-for-the-technical-account-user-in-aem

First, a new product profile must be created in the Adobe Admin Console.

After making the API call, the product profile appears as a user group in the AEM as a Cloud Service author instance, with the appropriate technical account as a member of that group.

To check this information, do the following:

Alternatively, you can also verify that the technical account appears in the user’s list by performing the below steps on the author instance:

Set the Appropriate Group Permissions

Finally, configure the group with the appropriate permissions necessary so you can invoke or lock down your APIs appropriately.

Developer Flow developer-flow

Developers likely want to test using a development instance of their non-AEM application (either running on their laptop or hosted) that makes requests to a development AEM as a Cloud Service dev environment. However, because developers do not necessarily have IMS admin role permissions, Adobe cannot assume they can generate the JWT bearer described in the regular server-to-server flow. Therefore, Adobe provides a mechanism for a developer to generate an access token directly that can be used in requests to environments on AEM as a Cloud Service which they have access to.

See the Developer Guidelines documentation for information about the required permissions to use the AEM as a Cloud Service developer console.

Developers may use this token to make calls from their non-AEM test application to an AEM as a Cloud Service environment. Typically, the developer uses this token with the non-AEM application on their own laptop. Also, the AEM as a Cloud is typically a non-production environment.

The developer flow involves the following steps:

Developers can also make API calls to an AEM project running on their local machine, in which case an access token is not needed.

Generating the Access Token generating-the-access-token

Call the AEM Application with an Access Token call-the-aem-application-with-an-access-token

Make the appropriate server-to-server API calls from the non-AEM application to an AEM as a Cloud Service environment, including the access token in the header. So for the “Authorization” header, use the value "Bearer <access_token>".

Refresh Credentials refresh-credentials

By default, the credentials on AEM as a Cloud Service expire after one year. To ensure service continuity, developers have the option of refreshing the credentials, extending their availability for an extra year.

To achieve this refresh extension, do the following:

Credentials Revocation credentials-revocation

If the private key is compromised, you must create credentials with a new certificate and new private key. After your application uses the new credentials so you can generate access tokens, you can revoke and delete the old certificates by doing the following: