Migrating safely to reduce the risk of blocked traffic

If your site is already live, exercise caution when migrating to customer-managed CDN since a misconfiguration can block public traffic; this is because only requests with the expected X-AEM-Edge-Key header value will be accepted by the Adobe CDN. An approach is recommended where an additional condition is temporarily included in the authentication rule, which causes it to block the request only if a test header is included or if a path is matched:

    - name: edge-auth-rule
        when:
          allOf:
            - { reqProperty: tier, equals: "publish" }
            - { reqHeader: x-edge-test, equals: "test" }
        action:
          type: authenticate
          authenticator: edge-auth
    - name: edge-auth-rule
        when:
          allOf:
            - { reqProperty: tier, equals: "publish" }
            - { reqProperty: path, like: "/test*" }
        action:
          type: authenticate
          authenticator: edge-auth

The following curl request pattern can be used:

curl https://publish-p<PROGRAM_ID>-e<ENV-ID>.adobeaemcloud.com -H "X-Forwarded-Host: example.com" -H "X-AEM-Edge-Key: <CONFIGURED_EDGE_KEY>" -H "x-edge-test: test"

After successfully testing, the additional condition can be removed and the configuration redeployed.

Purge API Token

Customers can purge the CDN cache by using a declared Purge API token. The token is declared in a file named cdn.yaml or similar, somewhere under a top-level config folder. Read Using Config Pipelines for details about the folder structure and how to deploy the configuration.

The syntax is described below:

kind: "CDN"
version: "1"
metadata:
  envTypes: ["dev"]
data:
  authentication:
    authenticators:
       - name: purge-auth
         type: purge
         purgeKey1: ${{CDN_PURGEKEY_031224}}
         purgeKey2: ${{CDN_PURGEKEY_021225}}
    rules:
       - name: purge-auth-rule
         when: { reqProperty: tier, equals: "publish" }
         action:
           type: authenticate
           authenticator: purge-auth

See Using Config Pipelines for a description of the properties above the data node. The kind property value should be CDN and the version property should be set to 1.

Additional properties include:

  • data node that contains a child authentication node.

  • Under authentication, one authenticators node and one rules node, both of which are arrays.

  • Authenticators: Lets you declare a type of token or credential, which in this case is an purge key. It includes the following properties:

    • name - a descriptive string.
    • type - must be purge.
    • purgeKey1 - its value must reference a Cloud Manager secret-type Environment Variable. For the Service Applied field, select All. It is recommended that the value (for example, ${{CDN_PURGEKEY_031224}}) reflects the day it was added.
    • purgeKey2 - used for rotation of secrets, which is described in the rotating secrets section section below. At least one of purgeKey1 and purgeKey2 must be declared.
  • Rules: Lets you declare which of the authenticators should be used, and whether it’s for the publish and/or preview tier. It includes:

    • name - a descriptive string
    • when - a condition that determines when the rule should be evaluated, according to the syntax in the Traffic Filter Rules article. Typically, it will include a comparison of the current tier (for example., publish).
    • action - must specify “authenticate”, with the intended authenticator referenced.
NOTE
The Purge Key must be configured as a secret type Cloud Manager Environment Variable, before the configuration referencing it is deployed. It is recommended to use a unique random key of minimum 32 bytes length; for example, the Open SSL cryptographic library can generate a random key by executing the command openssl rand -hex 32

You may reference a tutorial focused on configuring purge keys and performing the CDN cache purge.

Basic Authentication

Protect certain content resources by popping up a basic auth dialog requiring a username and password. This feature is primarily intended for light authentication use cases such as business stakeholder review of content, rather than as a full-fledged solution for end-user access rights.

The end user will experience a basic auth dialog popping up like the following:

basicauth-dialog

The syntax is as follows:


kind: "CDN"
version: "1"
metadata:
  envTypes: ["dev"]
data:
  authentication:
    authenticators:
       - name: my-basic-authenticator
         type: basic
         credentials:
           - user: johndoe
             password: ${{JOHN_DOE_PASSWORD}}
           - user: janedoe
             password: ${{JANE_DOE_PASSWORD}}
    rules:
       - name: basic-auth-rule
         when: { reqProperty: path, like: "/summercampaign" }
         action:
           type: authenticate
           authenticator: my-basic-authenticator

See Using Config Pipelines for a description of the properties above the data node. The kind property value should be CDN and the version property should be set to 1.

In addition, the syntax includes:

  • a data node that contains an authentication node.

  • Under authentication, one authenticators node and one rules node, both of which are arrays.

  • Authenticators: in this scenario declare a basic authenticator, which has the following structure:

    • name - a descriptive string

    • type - must be basic

    • an array of up to 10 credentials, each of which includes the following name/value pairs, which end-users can enter in the basic auth dialog:

  • Rules: Lets you declare which of the authenticators should be used, and which resources should be protected. Each rule includes:

    • name - a descriptive string
    • when - a condition that determines when the rule should be evaluated, according to the syntax in the Traffic Filter Rules article. Typically, it will include a comparison of the publish tier or specific paths.
    • action - must specify “authenticate”, with the intended authenticator referenced, which is basic-auth for this scenario
NOTE
The passwords must be configured as secret type Cloud Manager environment variables, before the configuration referencing it is deployed.

Rotating secrets

  1. It is good security practice to occasionally change credentials. This can be accomplished as exemplified below, using the example of an edge key, although the same strategy is used for purge keys.

  2. Initially just edgeKey1 has been defined, in this case referenced as ${{CDN_EDGEKEY_052824}}, which as a recommended convention, reflects the date it was created.

    authentication:
      authenticators:
        - name: edge-auth
          type: edge
          edgeKey1: ${{CDN_EDGEKEY_052824}}
    
  3. When it’s time to rotate the key, create a new Cloud Manager secret, for example ${{CDN_EDGEKEY_041425}}.

  4. In the configuration, reference it from edgeKey2 and deploy.

    authentication:
      authenticators:
        - name: edge-auth
          type: edge
          edgeKey1: ${{CDN_EDGEKEY_052824}}
          edgeKey2: ${{CDN_EDGEKEY_041425}}
    
  5. Once you are sure the old edge key is not used anymore, remove it by removing edgeKey1 from the configuration.

    authentication:
      authenticators:
        - name: edge-auth
          type: edge
          edgeKey2: ${{CDN_EDGEKEY_041425}}
    
  6. Delete the old secret reference (${{CDN_EDGEKEY_052824}}) from Cloud Manager and deploy.

  7. When ready for the next rotation, follow the same procedure, however this time you will add edgeKey1 to the configuration, referencing a new Cloud Manager environment secret named, for example, ${{CDN_EDGEKEY_031426}}.

    authentication:
      authenticators:
        - name: edge-auth
          type: edge
          edgeKey2: ${{CDN_EDGEKEY_041425}}
          edgeKey1: ${{CDN_EDGEKEY_031426}}
    
recommendation-more-help