diff --git a/src/pages/guides/getting-started/authentication.md b/src/pages/guides/getting-started/authentication.md index c5bba16c..7ebd3c12 100644 --- a/src/pages/guides/getting-started/authentication.md +++ b/src/pages/guides/getting-started/authentication.md @@ -23,23 +23,27 @@ 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/oauth-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`. + + + +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. ## Generating an Access Token ### Manual Generation Using Adobe Developer Console - + 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 and pasting the private key for the project. +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 Token_ button, an access token will be generated and can be copied to the clipboard. +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) @@ -47,25 +51,21 @@ Access tokens generated in this fashion will be valid for 24 hours, after which ### Programatic Generation -Programmatic generation of an access token is done by generating a JSON Web Token (JWT) and exchanging it with the Adobe Identity Management Service (IMS) for an access token. - - - -The below is a summary of this process. Complete documentation can be found in the [Adobe I/O JWT Documentation](https://developer.adobe.com/developer-console/docs/guides/authentication/JWT/) +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. -The JWT is constructed as a JSON object with these keys, referred to as _claims_: +![Programatic_Generate Access Token](img/programatic-generate-access-token.png) -* `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 . -* `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/`. -* `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. +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/) -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. +#### 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/) +The query parameters includes: -#### Language Support for JWT +* `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. -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/). +And then these parameters are then included in the body of a `POST` request sent to https://ims-na1.adobelogin.com/ims/token/v3. diff --git a/src/pages/guides/getting-started/create-api-integration.md b/src/pages/guides/getting-started/create-api-integration.md index 2ebfa036..58cbc08b 100644 --- a/src/pages/guides/getting-started/create-api-integration.md +++ b/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: + +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. + +##### Inorder to authenticate Cloud Manager API using a JSON Web Token (JWT) access token. 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. + +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. diff --git a/src/pages/guides/getting-started/create-event-integration.md b/src/pages/guides/getting-started/create-event-integration.md index abfe8b16..b9efe2ec 100644 --- a/src/pages/guides/getting-started/create-event-integration.md +++ b/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,11 @@ 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. diff --git a/src/pages/guides/getting-started/img/creating-api-integration.png b/src/pages/guides/getting-started/img/creating-api-integration.png new file mode 100644 index 00000000..ef3047bc Binary files /dev/null and b/src/pages/guides/getting-started/img/creating-api-integration.png differ diff --git a/src/pages/guides/getting-started/img/creating-event-integration.png b/src/pages/guides/getting-started/img/creating-event-integration.png new file mode 100644 index 00000000..d54cdc3d Binary files /dev/null and b/src/pages/guides/getting-started/img/creating-event-integration.png differ diff --git a/src/pages/guides/getting-started/img/generate-access-token-deprecated.png b/src/pages/guides/getting-started/img/generate-access-token-deprecated.png new file mode 100644 index 00000000..732c9b0a Binary files /dev/null and b/src/pages/guides/getting-started/img/generate-access-token-deprecated.png differ diff --git a/src/pages/guides/getting-started/img/generate-access-token.png b/src/pages/guides/getting-started/img/generate-access-token.png index 732c9b0a..b06e1698 100644 Binary files a/src/pages/guides/getting-started/img/generate-access-token.png and b/src/pages/guides/getting-started/img/generate-access-token.png differ diff --git a/src/pages/guides/getting-started/img/generated-access-token-deprecated.png b/src/pages/guides/getting-started/img/generated-access-token-deprecated.png new file mode 100644 index 00000000..1dbc31ee Binary files /dev/null and b/src/pages/guides/getting-started/img/generated-access-token-deprecated.png differ diff --git a/src/pages/guides/getting-started/img/generated-access-token.png b/src/pages/guides/getting-started/img/generated-access-token.png index 1dbc31ee..5bcb6954 100644 Binary files a/src/pages/guides/getting-started/img/generated-access-token.png and b/src/pages/guides/getting-started/img/generated-access-token.png differ diff --git a/src/pages/guides/getting-started/img/oauth-credential-details.png b/src/pages/guides/getting-started/img/oauth-credential-details.png new file mode 100644 index 00000000..c8bf5f8a Binary files /dev/null and b/src/pages/guides/getting-started/img/oauth-credential-details.png differ diff --git a/src/pages/guides/getting-started/img/programatic-generate-access-token.png b/src/pages/guides/getting-started/img/programatic-generate-access-token.png new file mode 100644 index 00000000..40f6d620 Binary files /dev/null and b/src/pages/guides/getting-started/img/programatic-generate-access-token.png differ