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

A user with an IMS org administrator role, and who is also a member of the AEM Users or AEM Administrators Product Profile on AEM Author, can generate a set of AEM as a Cloud Service credentials, each of which 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 subsequently 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 expire 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 from the Developer Console
• Install the AEM as a Cloud Service credentials on a non AEM server making calls to AEM
• Generate a JWT token and exchange that token for an access token using Adobe’s IMS APIs
• Calling the AEM API with the access token as a Bearer Authentication token
• Set appropriate permissions for the technical account user in the AEM environment

Fetch the AEM as a Cloud Service Credentials

Users with access to the AEM as a Cloud Service developer console will 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 the Create new technical account button, a new set of credentials will be 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 will open 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 modify the credentials for the same technical account by creating a new private key or certificate, for cases when the certificate needs to be renewed or revoked.

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

Install the AEM Service Credentials on a Non AEM Server

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

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 in order 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 will define 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

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

First, a new product profile needs to be created in the Adobe Admin Console. You can achieve this by following these steps:

1. Go to the Adobe Admin Console at https://adminconsole.adobe.com/

2. Press the Manage link under the Products and Services column on the left.

3. Select AEM as a Cloud Service

4. Press the New Profile button

   

5. Name the profile and press Save

   

6. Select the profile you just created from the profile list

7. Press the Add User button

   

8. Add the technical account you just created (in this case 84b2c3a2-d60a-40dc-84cb-e16b786c1673@techacct.adobe.com) and press Save

   

9. Wait 10 minutes for the changes to take effect and make an API call to AEM with an access token generated from the new credential. As a cURL command, it would be represented similar to this example:

   curl -H "Authorization: Bearer <access_token>" https://author-pXXXXX-eXXXXX.adobeaemcloud.net/content/dam.json

After making the API call, the product profile will appear 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, you need to:

1. Login to the author instance

2. Go to Tools - Security and click the Groups card

3. Locate the name of the profile you created in the list of groups and click on it:

   

4. In the following window, switch over to the Members tab and check if the technical account is correctly listed there:

   

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

1. Go to Tools - Security - Users

2. Check that your technical account is the user list and click on it

3. Click on the Groups tab to verify that the user is a part of the group that corresponds to your product profile. This user also is a member of a handful of other groups, including Contributors:

   

Set the Appropiate Group Permissions

Finally, configure the group with the appropriate permissions needed to in order to invoke or lock down your APIs appropriately. You can do this by:

1. Logging in to the appropiate author instance and going to Settings - Security - Permissions

2. Search for the name of the group corresponding to the product profile in the left hand pane (in this case Read-only APIs) and click on it:

   

3. Click the Edit button in the following window:

   

4. Modify the permissions appropriately and click Save

   

Developer Flow

Developers will 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, since developers do not necessarily have IMS admin role permissions, we cannot assume they can generate the JWT bearer described in the regular server-to-server flow. Thus, we provide a mechanism for a developer to generate an access token directly that can be used in requests to AEM as a Cloud Service environments 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 will use 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:

• Generate an access token from the Developer Console
• Call the AEM application with the access token.

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

1. Go to the Local token under Integrations
2. Click the Get Local Development Token button in the Developer Console to generate 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

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

To achieve this, you can:

• Use the Add certificate button under Integrations - Technical Accounts in the Developer Console, as shown below

  

• After pressing the button, a set of credentials that includes a new certificate will be generated. Install the new credentials on your off-AEM server and ensure that connectivity is as expected, without removing the old credentials

• Make sure the new credentials are used instead of the old ones when generating the access token

• Optionally revoke (and then delete) the prior certificate so it can no longer be used to authenticate with AEM as a Cloud Service.

Credentials Revocation

If the private key is compromised, you need to create credentials with a new certificate and new private key. After your application uses the new credentials to generate access tokens, you can revoke and delete the old certificates.

You can do this by following these steps:

1. First, add the new key. This will generate credentials with a new private key and a new certificate. The new private key will be marked in the UI as current and will thus be used for all new credentials for this technical account going forward. Note that the credentials associated with the older private keys will still be valid until revoked. To achieve this, press the three dots (…) under your current technical account and press Add new private key:

   

2. Press Add at the prompt that follows:

   

   A new browse tab with the new crendetials will open and the UI will be updated to show both private keys, with the new one marked as current:

   

3. Install the new credentials on the non-AEM server and ensure connectivity works as expected. See the Server to Server Flow section for details on how to do this

4. Revoke the old certificate. You can do this by selecting the three dots (…) to the right of the certificate and pressing Revoke:

   

   Then, confirm the revocation in the following prompt by pressing the Revoke button:

   

5. Finally, delete the compromised certificate.

Business.Adobe.com resources