Merge pull request #277 from amisha1609/CMGR-50788

[CMGR-50788] Updated CM integration guides to use OAuth

gatsby-config.js

@@ -69,9 +69,13 @@ module.exports = {
             path: '/guides/getting-started/create-event-integration/',
           },
           {
-            path: 'guides/getting-started/authentication.md',
+            path: 'guides/getting-started/authentication/authentication/',
             title: 'Authentication',
           },
+          {
+            path: 'guides/getting-started/authentication/jwt-authentication/',
+            title: 'JWT Authentication (Deprecated)',
+          },
           {
             path: 'guides/getting-started/permissions.md',
             title: 'API Permissions',

src/pages/guides/getting-started/authentication/authentication.md

@@ -0,0 +1,67 @@
+---
+title: Authentication - Cloud Manager API
+description: Describes how authentication is done in the API.
+keywords:
+  - Experience Cloud
+  - Adobe Experience Manager
+  - API Documentation
+  - Cloud Manager
+  - Authentication
+---
+
+# Authentication
+
+## Authentication Headers
+
+<InlineAlert slots="text" variant="warning"/>
+
+The Service Account (JWT) credentials have been deprecated in favor of the OAuth Server-to-Server credentials. Creating new JWT credentials will stop by May 1, 2024. Your applications using JWT credentials will stop working after Jan 1, 2025. You must migrate to the new credential by Jan 1, 2025, to ensure your application continues functioning. [In order to generate JWT access token](jwt-authentication.md).
+
+Every inbound HTTP API call to the Cloud Manager API must contain these three headers:
+
+* `x-api-key`
+* `x-gw-ims-org-id`
+* `Authorization`
+
+The values which should be sent in the `x-api-key` and `x-gw-ims-org-id` headers are provided in the Credentials details screen in the [Adobe Developer Console](https://developer.adobe.com/console). The value of the `x-api-key` header is the _Client ID_ and the value for the `x-gw-ims-org-id` header is the _Organization ID_.
+
+![Credential details](../img/oauth-credential-details.png)
+
+The `Authorization` header's value is in the form `Bearer` followed by a generated access token, e.g. `Bearer somelongtokenvalue`.
+
+## Generating an Access Token
+
+### Manual Generation Using Adobe Developer Console
+
+<InlineAlert slots="text" variant="warning"/>
+
+Please note that tokens generated through the AEM Developer Console cannot be used with the Cloud Manager API. If you want to manually generate a token, you must use the Adobe Developer Console.
+
+Generating an access token can be done by navigating to the Cloud Manager API page for the project in the Adobe Developer Console.
+
+![Generate Access Token](../img/generate-access-token.png)
+
+Upon clicking the _Generate access token_ button, an access token will be generated and can be copied to the clipboard.
+
+![Generated Access Token](../img/generated-access-token.png)
+
+Access tokens generated in this fashion will be valid for 24 hours, after which a new token must be generated.
+
+### Programatic Generation
+
+Generating access tokens for OAuth Server-to-Server credential is straightforward. You can click on `View cURL command` and then copy the cURL on the credential overview page.
+
+![Programatic_Generate Access Token](../img/programatic-generate-access-token.png)
+
+<InlineAlert variant="help" slots="text"/>
+
+The below is a summary of this process. Complete documentation can be found in the [Adobe I/O OAuth Documentation](https://developer.adobe.com/developer-console/docs/guides/authentication/ServerToServerAuthentication/implementation/)
+
+The query parameters includes:
+
+* `client_id`- the Client ID from the Adobe Developer Console integration.
+* `client_secret`	- the Client SECRET retrieved from the Adobe Developer Console integration.
+* `grant_type` - it is equal to 'client_credentials'.
+* `scope` - the SCOPES from the Adobe Developer Console integration.
+
+And then these parameters are then included in the body of a `POST` request sent to https://ims-na1.adobelogin.com/ims/token/v3.

src/pages/guides/getting-started/authentication.md → src/pages/guides/getting-started/authentication/jwt-authentication.md

@@ -1,20 +1,20 @@
 ---
-title: Authentication - Cloud Manager API
-description: Describes how authentication is done in the API.
+title: JWT Authentication
+description: Describes how jwt authentication is done in the API.
 keywords:
   - Experience Cloud
   - Adobe Experience Manager
   - API Documentation
   - Cloud Manager
-  - Authentication
+  - JWT Authentication
 ---
 
-import Epoch from "../../../components/epoch"
-
-# Authentication
+# JWT Authentication
 
 ## Authentication Headers
 
+**Note that generation of JWT access token is deprecated.** Documentation can be found in the [Adobe I/O JWT Documentation](https://developer.adobe.com/developer-console/docs/guides/authentication/JWT/)
+
 Every inbound HTTP API call to the Cloud Manager API must contain these three headers:
 
 * `x-api-key`
@@ -23,9 +23,9 @@ Every inbound HTTP API call to the Cloud Manager API must contain these three he
 
 The values which should be sent in the `x-api-key` and `x-gw-ims-org-id` headers are provided in the Credentials details screen in the [Adobe Developer Console](https://developer.adobe.com/console). The value of the `x-api-key` header is the _Client ID_ and the value for the `x-gw-ims-org-id` header is the _Organization ID_.
 
-![Credential details](img/credential-details.png)
+![Credential details](../img/credential-details.png)
 
-The `Authorization` header's value is in the form `Bearer ` followed by a generated access token, e.g. `Bearer somelongtokenvalue`.
+The `Authorization` header's value is in the form `Bearer` followed by a generated access token, e.g. `Bearer somelongtokenvalue`.
 
 ## Generating an Access Token
 
@@ -37,11 +37,11 @@ Please note that tokens generated through the AEM Developer Console cannot be us
 
 Generating an access token can be done by navigating to the Cloud Manager API page for the project in the Adobe Developer Console and pasting the private key for the project.
 
-![Generate Access Token](img/generate-access-token.png)
+![Generate Access Token](../img/generate-access-token-deprecated.png)
 
 Upon clicking the _Generate Token_ button, an access token will be generated and can be copied to the clipboard.
 
-![Generated Access Token](img/generated-access-token.png)
+![Generated Access Token](../img/generated-access-token-deprecated.png)
 
 Access tokens generated in this fashion will be valid for 24 hours, after which a new token must be generated.
 
@@ -58,14 +58,13 @@ The JWT is constructed as a JSON object with these keys, referred to as _claims_
 * `exp`- the requested expiration of the access token, expressed as a number of seconds since January 1st 1970 GMT. For most use cases, this should be a relatively small value, e.g. 5 minutes. For example, for five minutes from now, this value should be <Epoch addition={300} />.
 * `iss`	- the Organization ID from the Adobe Developer Console project, in the format org_ident@AdobeOrg.
 * `sub` - the Technical Account ID from the Adobe Developer Console integration, in the format: id@techacct.adobe.com.
-* `aud` - the Client ID from the Adobe Developer Console integration *prepended* with `https://ims-na1.adobelogin.com/c/`.
+* `aud` - the Client ID from the Adobe Developer Console integration _prepended_ with `https://ims-na1.adobelogin.com/c/`.
 * `https://ims-na1.adobelogin.com/s/ent_cloudmgr_sdk` - set to the literal value `true`.
 
 This JSON object must be then base64 encoded and signed using the private key for the project.
 
 Finally, the encoded value is sent in the body of a `POST` request to https://ims-na1.adobelogin.com/ims/exchange/jwt along with the Client ID and Client Secret for the project.
 
-
 #### Language Support for JWT
 
 While it is possible to do the entire JWT generation and exchange process in custom code, it is more common to use a higher-level library to do so. A number of such libraries are listed on the [Adobe I/O JWT Documentation](https://developer.adobe.com/developer-console/docs/guides/authentication/JWT/).

src/pages/guides/getting-started/create-api-integration.md

@@ -20,9 +20,14 @@ Note that the API Developer role required to create integrations in the Adobe De
 
 When you receive notification of this role, click the **Get Started** button in the message to access services.
 
-All requests to the Cloud Manager API must be authenticated using an access token retrieved using a JSON Web Token (JWT). The [Adobe I/O JWT Documentation](https://developer.adobe.com/developer-console/docs/guides/authentication/JWT/) provides a guide to creating the certificate files necessary to set up the integration as well as instructions for how to generate your first access token.
+All requests to the Cloud Manager API must be authenticated using an access token. The [Adobe I/O OAuth Documentation](https://developer.adobe.com/developer-console/docs/guides/authentication/ServerToServerAuthentication/implementation/) provides a guide to generate your first access token with the OAuth Server-to-Server credential.
 
-Once you've generated your certificate, to create an API Integration:
+<InlineAlert slots="text" variant="warning"/>
+The Service Account (JWT) credentials have been deprecated in favor of the OAuth Server-to-Server credentials. Your applications using the Service Account (JWT) credentials will stop working after Jan 1, 2025.
+
+**To authenticate Cloud Manager APIs using a JWT access token, refer to the [Adobe I/O JWT Documentation](https://developer.adobe.com/developer-console/docs/guides/authentication/JWT/) for a guide on creating the certificate files required to set up the integration and instructions on generating your first access token.**
+
+To create an API Integration:
 
 1. Navigate to the following URL: [https://developer.adobe.com/console](https://developer.adobe.com/console). This can also be reached by clicking the Console button at the top of this page.
 
@@ -34,10 +39,12 @@ Once you've generated your certificate, to create an API Integration:
 
 5. Under the Experience Cloud section select `Cloud Manager` and then click `Next`.
 
-6. Generate or Upload a key pair. Click either `Generate keypair` or `Next`. If you generate a key pair, be sure to retain the downloaded file -- it **cannot** be recovered if lost and you will have to generate a new key pair.
+6. Select `OAuth Server-to-Server` authentication.
+   Note that obtaining JWT access token through **Generate or Upload a key pair** is deprecated.
 
-7. Select one of the Product Profiles to assign the integration to a [specific Cloud Manager role](https://www.adobe.com/go/aem_cloud_mrg_usersroles_en).
+![Choosing type of authentication](img/creating-api-integration.png)
 
+7. Select one of the Product Profiles to assign the integration to a [specific Cloud Manager role](https://www.adobe.com/go/aem_cloud_mrg_usersroles_en).
 
 ![Select Product Profile](img/integration-select-product-profile.png)
 
@@ -47,4 +54,4 @@ If you are an API Developer in the organization, you may be restricted as to whi
 
 9. Click `Save configured API`.
 
-Your client is now created. Notice your client has an `Client ID` (sometimes referred to as an API Key) and an `Organization ID`. You'll need these when making API calls. You will also need the `Technical Account ID` and `Client Secret` values to obtain an Access Token.
+Your client is now created. Notice your client has an `Client ID` (sometimes referred to as an API Key) and an `Organization ID`. You'll need these when making API calls. You will also need the `Client Secret` and `Scopes` values to obtain an Access Token.

src/pages/guides/getting-started/create-event-integration.md

@@ -17,9 +17,9 @@ To work with the Cloud Manager Events on the Adobe Developer Console, you need t
 
 Adobe I/O Events emitted by Cloud Manager are sent to **webhooks** hosted either in on-premise infrastructure, specialized webhook hosting providers, [Adobe I/O Runtime](https://developer.adobe.com/runtime/docs/), or even your AEM instances managed by Adobe. Alternatively, the [Adobe I/O Journaling API](https://developer.adobe.com/events/docs/guides/api/journaling_api/) may be used, especially in cases where network security rules prohibit a webhook from being accessible from the public internet.
 
-The [Getting Started with Adobe I/O Events](https://developer.adobe.com/events/docs/guides/) guide provides general documentation on how to set up a webhook. As with [API Integration Projecs](create-api-integration.md), a certificate file is needed to set up an Event Integration.
+The [Getting Started with Adobe I/O Events](https://developer.adobe.com/events/docs/guides/) guide provides general documentation on how to set up a webhook.
 
-Once your webhook is up and running and you have your certificate, to create an Event Integration:
+Once your webhook is up and running, to create an Event Integration:
 
 1. Navigate to the following URL: [https://developer.adobe.com/console](https://developer.adobe.com/console). This can also be reached by clicking the Console button at the top of this page.
 
@@ -31,9 +31,12 @@ Once your webhook is up and running and you have your certificate, to create an
 
 5. Under the Experience Cloud section select `Cloud Manager` and then click `Next`.
 
-6. For a new project, generate or Upload a key pair. Click either `Generate keypair` or `Next`.
+6. Select the events you want to receive on the webhook.
 
-7. Select the events you want to receive on the webhook.
+7. Choose `OAuth Server-to-Server` authentication.
+   Note that authentication using **Generate or Upload a key pair** is deprecated.
+
+![Choosing type of authentication](img/creating-event-integration.png)
 
 8. Fill out the name and description.
 

src/pages/guides/getting-started/index.md

@@ -32,16 +32,22 @@ Learn how to create an Event Integration Project to receive webhooks when your p
 
 [Getting Started with Postman](/src/pages/guides/getting-started/getting-started-with-postman.md)
 
-Learn how to expirement with the API using Postman.
+Learn how to experiment with the API using Postman.
 
 <DiscoverBlock slots="link, text"/>
 
-[Authentication](/src/pages/guides/getting-started/authentication.md)
+[Authentication](/src/pages/guides/getting-started/authentication/authentication.md)
 
 Learn how to authenticate API calls.
 
 <DiscoverBlock slots="link, text"/>
 
+[JWT Authentication (Deprecated)](/src/pages/guides/getting-started/authentication/jwt-authentication.md)
+
+Learn how to authenticate API calls using JWT.
+
+<DiscoverBlock slots="link, text"/>
+
 [Permissions](/src/pages/guides/getting-started/permissions.md)
 
 See which permissions are required for using the API.