Managing SSL and Domains in AEM as a Cloud Service

 This post will discuss handling SSL and domains when using AEM as a Cloud Service. This is for you if you’ve been wondering about keeping things secure and running smoothly on the cloud. Let’s dive into some easy tips and tricks.

AEM as a Cloud service allows you to manage SSL and domains through a cloud manager.

SSL Management:

As a first step, begin by uploading your SSL certificates to Cloud Manager. refer to SSL Certificate Management Basics — Developers | by Albin Issac | Tech Learnings | Medium for understanding the details of SSL management. At any given time, Cloud Manager will allow a maximum of 50 SSL certificates to be installed. These can be associated with one or more environments across your program and also include any expired certificates. However, some prerequisites exist for the SSL certificates: Domain Validated (DV) or self-signed certificates are not supported. The SSL certificate files must be in PEM format to be installed with Cloud Manager, and the Private Key should be in pkcs8 unencrypted format. For more details on managing SSL certificates in AEM as a Cloud, refer to the guide Introduction to Managing SSL Certificates | Adobe Experience Manager on the Adobe Experience Manager website.

AEM as a Cloud Service supports single domain, SAN, and wildcard certificates via the Cloud Manager.

You can go to cloud manager environments → SSL Certificates →Add SSL Certificates.

Enter a name for the SSL certificate and copy its content. Copy the content of the SSL certificate, you will receive the certificate file from the Certificate Authority (e.g., DigiCert) by following the certificate generation process. Ensure the file is in .pem format; if it’s not, you’ll need to convert it to .pem.

-----BEGIN CERTIFICATE-----
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-----END CERTIFICATE-----

Copy the content of the private key, ensuring that it is in the non-encrypted pkcs8 format. If your key is in another format, such as OpenSSL, it can be converted to pkcs8. I usually use Key Explorer for this purpose, although OpenSSL can also be used to convert to different formats. These tools provide a quick way to change key formats.

Make sure that the key is not encrypted.

In addition to the actual certificate, you will receive certificate chains from the Certificate Authority (CA), which typically include two types of chain certificates: the Intermediate certificate and the Root certificate. You should arrange the Intermediate and Root certificate contents in the correct order and copy the combined content into the certificate chain field.

-----BEGIN CERTIFICATE-----
Intermediate Certificate
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
Root certificate
-----END CERTIFICATE-----

If the private key is uploaded in a format other than pkcs8, you will encounter an error stating, ‘Private key does not match the certificate.

Once the certificate is successfully uploaded, it becomes available for association with a domain and environment. The SSL certificate can also be updated or deleted as needed.

DNS Management:

Now, you have the ability to add a new custom domain, associate it with an SSL certificate, and assign it to a specific environment. For more detailed information on DNS management in AEM as a Cloud service, please refer to ‘ Adding a Custom Domain Name | Adobe Experience Manager’ in the Adobe Experience Manager documentation. Additionally, for a fundamental understanding of DNS management, consult ‘DNS Management Basics for Web Developers | by Albin Issac | Tech Learnings | Medium.

There are certain limitations when managing custom domains in Cloud Manager. Each environment can support a maximum of 500 custom domains. Custom domain names are accommodated in Cloud Manager for both ‘publish’ and ‘preview’ services in Sites programs, but they are not supported for author services. To add a custom domain name in Cloud Manager, a user must hold either the Business Owner or Deployment Manager role. Additionally, you must be utilizing the out-of-the-box (OOTB) Fastly CDN.

Cloud Manager → Environments → Domains →Add Domain

Enter the fully qualified domain name, such as a test domain (e.g., samplesite-dev.test.com) or a live site (e.g., samplesite.test.com). Then, select the environment where this domain will be active, based on your configuration (e.g., dev, uat, stage, prod). Next, choose the service with which you want to associate the domain, either ‘publish’ or ‘preview’. Finally, select the SSL certificate associated with this domain (only those SSL certificates linked to the specified domain will be listed).

Now, you will receive a TXT record that needs to be configured in your Domain Manager to verify domain ownership.

Now, add the TXT record to your domain using your DNS management system, such as CSC Global, GoDaddy, etc.

Wait for the changes to propagate, which may take some time. You can verify this through online tools or command-line utilities like ‘dig’.

Click ‘Create.’ The TXT record will then be validated. You can also choose to create it first and validate it later, once the changes have propagated, by clicking ‘Verify’ again.

Once the domain is successfully validated, a green checkmark will appear.

Now, return to your Domain Manager and create a CNAME record for your custom subdomain (e.g., www.testdomain1.com) that points to cdn.adobeaemcloud.com. Alternatively, you can add an A-Record instead of a CNAME if you are using a root (APEX) domain. For more details, refer to the ‘Configuring DNS Settings | Adobe Experience Manager’ section in Adobe Experience Manager documentation.

Wait for the changes to take effect. You can verify this through the same online tools or command-line utilities,

Now, click ‘Resolve’ again to configure the domain’s CNAME resolution.

Once resolved, you will see a ‘Resolved Correctly’ message, indicating that the domain is now ready for use.

Enable the necessary Dispatcher configurations to direct the domain to a specific content path.

AEM as a Cloud offers a self-service capability for managing SSL and DNS configurations through Cloud Manager, greatly simplifying the process of handling SSL certificates and DNS settings. It’s important to configure your domain well in advance, as the entire process, including domain validation and resolving through your DNS manager, can take a reasonable amount of time.

As an additional note, I recommend creating a common test domain to manage test domains across different environments. For instance, using test.com allows you to create various subdomains for different environments, such as dev.test.com, uat.test.com, stage.test.com, etc.

site1-dev.test.com
site1-uat.test.com
site1.stage.test.com

Now, create a wildcard certificate that supports *.test.com and upload this certificate to Cloud Manager. It can be used to configure all the test domains across various environments. Additionally, create a SAN (Subject Alternative Name) certificate to support all your live domains.

Transforming API Development: How to Use ChatGPT for OpenAPI Specs

 OpenAPI is a prevalent standard for defining and documenting APIs. Although generating documentation according to the OpenAPI specifications can be time-consuming, imagine the possibilities if this process were more streamlined. This is where ChatGPT comes into play, offering a transformative approach to creating OpenAPI specifications.

ChatGPT, with its natural language processing capabilities, offers a unique solution to the often complex and time-consuming task of writing OpenAPI specifications.

With ChatGPT, you can describe your API’s functionality in plain language, and the tool will help translate this into a structured OpenAPI spec.

Prompt:

myailearnings/prompts/generate-openapi-specification.txt at main · techforum-repo/myailearnings (github.com)

Please generate an OpenAPI YAML definition incorporating the following details. 
Ensure the inclusion of separate schemas for any nested objects. 
Also, include request and response examples using the sample values provided.

API base URL - https://test.search.com/rest
Path - /search/v2
Method - POST
Query Parameter - testparam
Add service-level bearer token authentication for this endpoint

Sample Request Body 

{
  "q": "test",
  "context": {
    "country": "US",
    "locale": "en",
    "environment": "stage"
  }
}

Sample Response

{
  "totalCount": 1,
  "result": [
    {
      "uri": "https://test.com/test.pdf",
      "test1": [
        [
          "test1"
        ]
      ],
      "test2": [
        [
          "test2"
        ]
      ],
      "test3": "test3",
      "test4": [
        [
          "test4_1",
          "test4_2"
        ]
      ]     
    }
  ]
}

Additional Prompts:

Include an enum named 'environment' with values 'stage', 'uat', and 'prod'. Give me the complete specification
Add a description for the request body field 'q', labeling it as 'Product Code. Give me the complete specification

This process will develop the OpenAPI specification based on the provided API details. The prompts can be further refined for a more precise API specification. Additionally, incorporating extra prompts will allow for even more detailed fine-tuning of the specification.

openapi: 3.0.0
info:
  title: Test Search API
  version: 1.0.0
servers:
  - url: https://test.search.com/rest
paths:
  /search/v2:
    post:
      summary: Search endpoint
      operationId: search
      parameters:
        - name: testparam
          in: query
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              example1:
                value:
                  q: "test"
                  context:
                    country: "US"
                    locale: "en"
                    environment: "stage"
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              examples:
                example1:
                  value:
                    totalCount: 1
                    result:
                      - uri: "https://test.com/test.pdf"
                        test1: [["test1"]]
                        test2: [["test2"]]
                        test3: "test3"
                        test4: [["test4_1", "test4_2"]]
      security:
        - bearerAuth: []
components:
  schemas:
    SearchRequest:
      type: object
      properties:
        q:
          type: string
          description: Product Code
        context:
          $ref: '#/components/schemas/Context'
    Context:
      type: object
      properties:
        country:
          type: string
        locale:
          type: string
        environment:
          type: string
          enum: [stage, uat, prod]
    SearchResponse:
      type: object
      properties:
        totalCount:
          type: integer
        result:
          type: array
          items:
            $ref: '#/components/schemas/ResultItem'
    ResultItem:
      type: object
      properties:
        uri:
          type: string
          format: uri
        test1:
          type: array
          items:
            type: array
            items:
              type: string
        test2:
          type: array
          items:
            type: array
            items:
              type: string
        test3:
          type: string
        test4:
          type: array
          items:
            type: array
            items:
              type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

Now, you can import the YAML specification to Swagger Editor so that you can review the API details and test the API through the browser. Refer to https://github.com/swagger-api/swagger-editor for more information on Swagger Editor on your local machine.

Now you can either upload the YAML file generated or directly paste the YAML file on the Editor.

You can review the various API details through the UI and test the API by providing the required authorization and the request payloads.

You can even host a local server to share the API specifications with teams.

Another option is the online Swagger Hub, a licensed version, but the free trial is available for testing; here, you can upload the API specification, review, test, and share it with the teams.

Import the definition

Now, you can review, test, and share the API with the teams.

Also, another option to share the API is through Confluence; the Swagger UI can be integrated into Confluence through the Swagger Plugin, and the UI can be embedded into the Confluence page and shared with different teams.

Enable one of the Open API Integration plugins from the confluence marketplace, I am going to use “Open API Documentation for Confluence” that supports both JSON and YAML (you can use the free trial version to test)

Now add the plugin inside the Confluence document.

You can embed the OpenAPI YAML or JSON specification from remote systems or directly paste it into the plugin.

Now the Swagger UI is embedded into the confluence page, the API can be reviewed and tested and the confluence page can be shared with different teams.

The API documentation is critical; the OpenAPI specification allows you to document the API details in a standard way. ChatGPT helps you to simplify the documentation process; you can use ChatGPT to create the basic documentation and modify it based on your need also follow the option to share with the different teams.