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 childauthentication
node. -
Under
authentication
, oneauthenticators
node and onerules
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
andpurgeKey2
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.
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:
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 anauthentication
node. -
Under
authentication
, oneauthenticators
node and onerules
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:
- user - the name of user
- password - its value must reference a Cloud Manager secret-type environment variable, with All selected as the service field.
-
-
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
Rotating secrets
-
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.
-
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}}
-
When it’s time to rotate the key, create a new Cloud Manager secret, for example
${{CDN_EDGEKEY_041425}}
. -
In the configuration, reference it from
edgeKey2
and deploy.authentication: authenticators: - name: edge-auth type: edge edgeKey1: ${{CDN_EDGEKEY_052824}} edgeKey2: ${{CDN_EDGEKEY_041425}}
-
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}}
-
Delete the old secret reference (
${{CDN_EDGEKEY_052824}}
) from Cloud Manager and deploy. -
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}}