Edit in GitHubLog an issue

CNAME and Target

Instructions for working with Adobe Client Care to implement CNAME (Canonical Name) support in Adobe Target. Use CNAME to handle ad blocking issues or ITP-related (Intelligent Tracking Prevention) cookie policies. With CNAME, calls are made to a domain owned by the customer rather than a domain owned by Adobe.

Request CNAME support in Target#

  1. Determine the list of hostnames you need for your SSL certificate (see FAQ below).

  2. For each hostname, create a CNAME record in your DNS pointing to your regular Target hostname clientcode.tt.omtrdc.net.

    For example, if your client code is "cnamecustomer" and your proposed hostname is target.example.com, your DNS CNAME record looks similar to:

    Copied to your clipboard
    target.example.com. IN CNAME cnamecustomer.tt.omtrdc.net.
  1. Fill out this form and include it when you open an Adobe Client Care ticket requesting CNAME support:

    • Adobe Target client code:
    • SSL certificate hostnames (example: target.example.com target.example.org):
    • SSL certificate purchaser (Adobe is highly recommended, see FAQ): Adobe/customer
    • If the customer is purchasing the certificate, also known as "Bring Your Own Certificate" (BYOC), fill out these additional details:
      • Certificate organization (example: Example Company Inc):
      • Certificate organizational unit (optional, example: Marketing):
      • Certificate country (example: US):
      • Certificate state/region (example: California):
      • Certificate city (example: San Jose):
  2. If Adobe is purchasing the certificate, Adobe works with DigiCert to purchase and deploy your certificate on Adobe's production servers.

    If the customer is purchasing the certificate (BYOC), Adobe Client Care sends you the certificate signing request (CSR). Use the CSR when purchasing the certificate through your certificate authority of choice. After the certificate is issued, send a copy of the certificate and any intermediate certificates to Adobe Client Care for deployment.

    Adobe Client Care notifies you when your implementation is ready.

  3. Update the serverDomain documentation to the new CNAME hostname and set overrideMboxEdgeServer to false documentation in your at.js configuration.

Frequently Asked Questions#

The following information answers frequently asked questions about requesting and implementing CNAME support in Target:

Can I provide my own certificate (Bring Your Own Certificate or BYOC)?#

You can provide your own certificate. However, Adobe does not recommend this practice. Management of the SSL certificate lifecycle is easier for both Adobe and you if Adobe purchases and controls the certificate. SSL certificates must be renewed every year. Therefore, Adobe Client Care must contact you every year to obtain a new certificate in a timely manner. Some customers can have difficulty producing a renewed certificate in a timely manner. Your Target implementation is jeopardized when the certificate expires because browsers refuse connections.

How long until my new SSL certificate expires?#

All Adobe-purchased certificates are valid for one year. See DigiCert's article on 1-year certificates for more information.

What hostnames should I choose? How many hostnames per domain should I choose?#

Target CNAME implementations require only one hostname per domain on the SSL certificate and in the customer's DNS. Adobe recommends one hostname per domain. Some customers require more hostnames per domain for their own purposes (testing in staging, for example), which is supported.

Most customers choose a hostname like target.example.com. Adobe recommends following this practice, but the choice is ultimately yours. Do not request a hostname of an existing DNS record. Doing so causes a conflict and delays time to resolution of your Target CNAME request.

I already have a CNAME implementation for Adobe Analytics, can I use the same certificate or hostname?#

No, Target requires a separate hostname and certificate.

Is my current implementation of Target impacted by ITP 2.x?#

Apple Intelligent Tracking Prevention (ITP) version 2.3 introduced its CNAME Cloaking Mitigation feature, which is able to detect Adobe Target CNAME implementations and reduces the cookie's expiration to seven days. Currently Target has no workaround for ITP's CNAME Cloaking Mitigation. For more information about ITP, see Apple Intelligent Tracking Prevention (ITP) 2.x.

What kind of service disruptions can I expect when my CNAME implementation is deployed?#

There is no service disruption when the certificate is deployed (including certificate renewals).

However, after you change the hostname in your Target implementation code (serverDomain in at.js) to the new CNAME hostname (target.example.com), web browsers treat returning visitors as new visitors. Returning visitors' profile data is lost because the previous cookie is inaccessible under the old hostname (clientcode.tt.omtrdc.net). The previous cookie is inaccessible due to browser security models. This disruption occurs only on the initial cut-over to the new CNAME. Certificate renewals do not have the same effect because the hostname doesn't change.

What key type and certificate signature algorithm is used for my CNAME implementation?#

All certificates are RSA SHA-256 and keys are RSA 2048-bit, by default. Key sizes larger than 2048-bit are not currently supported.

How can I validate that my CNAME implementation is ready for traffic?#

Use the following set of commands (in the macOS or Linux command-line terminal, using bash and curl >=7.49):

  1. Copy and paste this bash function into your terminal, or paste the function into your bash startup script file (usually ~/.bash_profile or ~/.bashrc) so the function is available across terminal sessions:

    Copied to your clipboard
    1function adobeTargetCnameValidation {
    2 local hostname="$1"
    3 if [ -z "$hostname" ]; then
    4 echo "ERROR: no hostname specified"
    5 return 1
    6 fi
    7
    8 local service="Adobe Target CNAME implementation"
    9 local edges="31 32 34 35 36 37 38"
    10 local edgeDomain="tt.omtrdc.net"
    11 local edgeFormat="mboxedge%d%s.$edgeDomain"
    12 local shardFormat="-alb%02d"
    13 local shards=5
    14 local shardsFoundCount=0
    15 local shardsFound
    16 local shardsFoundOutput
    17 local curlRegex="subject:.*CN=|expire date:|issuer:"
    18 local curlValidation="SSL certificate verify ok"
    19 local curlResponseValidation='"OK"'
    20 local curlEndpoint="/uptime?mboxClient=uptime3"
    21 local url="https://$hostname$curlEndpoint"
    22 local sslLabsUrl="https://ssllabs.com/ssltest/analyze.html?hideResults=on&latest&d=$hostname"
    23 local success="✅"
    24 local failure="🚫"
    25 local info="🔎"
    26 local rule="="
    27 local horizontalRule="$(seq ${COLUMNS:-30} | xargs printf "$rule%.0s")"
    28 local miniRule="$(seq 5 | xargs printf "$rule%.0s")"
    29 local curlVersion="$(curl --version | head -1 | cut -d' ' -f2 )"
    30 local curlVersionRequired=">=7.49"
    31 local edgeCount="$(wc -w <<< "$edges" | tr -d ' ')"
    32 local edge
    33 local shard
    34 local currEdgeShard
    35 local dnsOutput
    36 local cnameExists
    37 local endToEndTestSucceeded
    38 local curlResult
    39
    40 for shard in $(seq $shards); do
    41 if [ "$shardsFoundCount" -eq 0 ]; then
    42 for edge in $edges; do
    43 if [ "$shard" -eq 1 ]; then
    44 currEdgeShard="$(printf "$edgeFormat" "$edge" "")"
    45 else
    46 currEdgeShard="$(
    47 printf "$edgeFormat" "$edge" "$(
    48 printf -- "$shardFormat" "$shard"
    49 )"
    50 )"
    51 fi
    52 curlResult="$(curl -vsm20 --connect-to "$hostname:443:$currEdgeShard:443" "$url" 2>&1)"
    53 if grep -q "$curlValidation" <<< "$curlResult"; then
    54 shardsFound+=" $currEdgeShard"
    55 if grep -q "$curlResponseValidation" <<< "$curlResult"; then
    56 shardsFoundCount=$((shardsFoundCount+1))
    57 shardsFoundOutput+="\n\n$miniRule $success $hostname [edge shard: $currEdgeShard] $miniRule\n"
    58 else
    59 shardsFoundOutput+="\n\n$miniRule $failure $hostname [edge shard: $currEdgeShard] $miniRule\n"
    60 fi
    61 shardsFoundOutput+="$(grep -E "$curlRegex" <<< "$curlResult" | sort)"
    62 if ! grep -q "$curlResponseValidation" <<< "$curlResult"; then
    63 shardsFoundOutput+="\nERROR: unexpected HTTP response from this shard using $url"
    64 fi
    65 fi
    66 done
    67 fi
    68 done
    69
    70 echo
    71 echo "$horizontalRule"
    72 echo
    73 echo "$service validation for hostname $hostname:"
    74 dnsOutput="$(dig -t CNAME +short "$hostname" 2>&1)"
    75 if grep -qFi ".$edgeDomain" <<< "$dnsOutput"; then
    76 echo "$success $hostname passes DNS CNAME validation"
    77 cnameExists=true
    78 else
    79 echo -n "$failure $hostname FAILED DNS CNAME validation -- "
    80 if [ -n "$dnsOutput" ]; then
    81 echo -e "$dnsOutput is not in the subdomain $edgeDomain"
    82 else
    83 echo "required DNS CNAME record pointing to <target-client-code>.$edgeDomain not found"
    84 fi
    85 fi
    86
    87 curlResult="$(curl -vsm20 "$url" 2>&1)"
    88 if grep -q "$curlValidation" <<< "$curlResult"; then
    89 if grep -q "$curlResponseValidation" <<< "$curlResult"; then
    90 echo -en "$success $hostname passes TLS and HTTP response validation"
    91 if [ -n "$cnameExists" ]; then
    92 echo
    93 else
    94 echo " -- the DNS CNAME is not pointing to the correct subdomain for ${service}s with Adobe-managed certificates" \
    95 "(bring-your-own-certificate implementations don't have this requirement), but this test passes as configured"
    96 fi
    97 endToEndTestSucceeded=true
    98 else
    99 echo -n "$failure $hostname FAILED HTTP response validation --" \
    100 "unexpected response from $url -- "
    101 if [ -n "$cnameExists" ]; then
    102 echo "DNS is NOT pointing to the correct shard, notify Adobe Client Care"
    103 else
    104 echo "the required DNS CNAME record is missing, see above"
    105 fi
    106 fi
    107 else
    108
    109 echo -n "$failure $hostname FAILED TLS validation -- "
    110 if [ -n "$cnameExists" ]; then
    111 echo "DNS is likely NOT pointing to the correct shard or there's a validation issue with the certificate or" \
    112 "protocols, see curl output below and optionally SSL Labs ($sslLabsUrl):"
    113 echo ""
    114 echo "$horizontalRule"
    115 echo "$curlResult" | sed 's/^/ /g'
    116 echo "$horizontalRule"
    117 echo ""
    118 else
    119 echo "the required DNS CNAME record is missing, see above"
    120 fi
    121 fi
    122
    123 if [ "$shardsFoundCount" -ge "$edgeCount" ]; then
    124 echo -n "$success $hostname passes shard validation for the following $shardsFoundCount edge shards:"
    125 echo -e "$shardsFoundOutput"
    126 echo
    127
    128 if [ -n "$cnameExists" ] && [ -n "$endToEndTestSucceeded" ]; then
    129 echo "$horizontalRule"
    130 echo ""
    131 echo " For additional TLS/SSL validation, including detailed browser/client support,"
    132 echo " see SSL Labs (click the first IP address if prompted):"
    133 echo ""
    134 echo " $info $sslLabsUrl"
    135 echo ""
    136 echo " To check DNS propagation around the world, see whatsmydns.net:"
    137 echo ""
    138 echo " $info DNS A records: https://whatsmydns.net/#A/$hostname"
    139 echo " $info DNS CNAME record: https://whatsmydns.net/#CNAME/$hostname"
    140 fi
    141 else
    142 echo -n "$failure $hostname FAILED shard validation -- shards found: $shardsFoundCount," \
    143 "expected: $edgeCount"
    144 if bc -l <<< "$(cut -d. -f1,2 <<< "$curlVersion") $curlVersionRequired" 2>/dev/null | grep -q 0; then
    145 echo -n " -- insufficient curl version installed: $curlVersion, but this script requires curl version" \
    146 "$curlVersionRequired because it uses the curl --connect-to flag to bypass DNS and directly test" \
    147 "each Adobe Target edge shards' SNI confirguation for $hostname"
    148 fi
    149 if [ -n "$shardsFoundOutput" ]; then
    150 echo -e ":\n$shardsFoundOutput"
    151 fi
    152 echo
    153 fi
    154 echo
    155 echo "$horizontalRule"
    156 echo
    157}
    158
  2. Paste this command (replacing target.example.com with your hostname):

    Copied to your clipboard
    adobeTargetCnameValidation target.example.com

    If the implementation is ready, you see output like below. The important part is that all validation status lines show ✅ rather than 🚫. Each Target edge CNAME shard should show CN=target.example.com, which matches the primary hostname on the requested certificate (additional SAN hostnames on the certificate aren't printed in this output).

    Copied to your clipboard
    1$ adobeTargetCnameValidation target.example.com
    2
    3==========================================================
    4
    5Adobe Target CNAME implementation validation for hostname target.example.com:
    6✅ target.example.com passes DNS CNAME validation
    7✅ target.example.com passes TLS and HTTP response validation
    8✅ target.example.com passes shard validation for the following 7 edge shards:
    9
    10===== ✅ target.example.com [edge shard: mboxedge31-alb02.tt.omtrdc.net] =====
    11* expire date: Jul 22 23:59:59 2022 GMT
    12* issuer: C=US; O=DigiCert Inc; CN=DigiCert TLS RSA SHA256 2020 CA1
    13* subject: C=US; ST=California; L=San Jose; O=Adobe Systems Incorporated; CN=target.example.com
    14
    15===== ✅ target.example.com [edge shard: mboxedge32-alb02.tt.omtrdc.net] =====
    16* expire date: Jul 22 23:59:59 2022 GMT
    17* issuer: C=US; O=DigiCert Inc; CN=DigiCert TLS RSA SHA256 2020 CA1
    18* subject: C=US; ST=California; L=San Jose; O=Adobe Systems Incorporated; CN=target.example.com
    19
    20===== ✅ target.example.com [edge shard: mboxedge34-alb02.tt.omtrdc.net] =====
    21* expire date: Jul 22 23:59:59 2022 GMT
    22* issuer: C=US; O=DigiCert Inc; CN=DigiCert TLS RSA SHA256 2020 CA1
    23* subject: C=US; ST=California; L=San Jose; O=Adobe Systems Incorporated; CN=target.example.com
    24
    25===== ✅ target.example.com [edge shard: mboxedge35-alb02.tt.omtrdc.net] =====
    26* expire date: Jul 22 23:59:59 2022 GMT
    27* issuer: C=US; O=DigiCert Inc; CN=DigiCert TLS RSA SHA256 2020 CA1
    28* subject: C=US; ST=California; L=San Jose; O=Adobe Systems Incorporated; CN=target.example.com
    29
    30===== ✅ target.example.com [edge shard: mboxedge36-alb02.tt.omtrdc.net] =====
    31* expire date: Jul 22 23:59:59 2022 GMT
    32* issuer: C=US; O=DigiCert Inc; CN=DigiCert TLS RSA SHA256 2020 CA1
    33* subject: C=US; ST=California; L=San Jose; O=Adobe Systems Incorporated; CN=target.example.com
    34
    35===== ✅ target.example.com [edge shard: mboxedge37-alb02.tt.omtrdc.net] =====
    36* expire date: Jul 22 23:59:59 2022 GMT
    37* issuer: C=US; O=DigiCert Inc; CN=DigiCert TLS RSA SHA256 2020 CA1
    38* subject: C=US; ST=California; L=San Jose; O=Adobe Systems Incorporated; CN=target.example.com
    39
    40===== ✅ target.example.com [edge shard: mboxedge38-alb02.tt.omtrdc.net] =====
    41* expire date: Jul 22 23:59:59 2022 GMT
    42* issuer: C=US; O=DigiCert Inc; CN=DigiCert TLS RSA SHA256 2020 CA1
    43* subject: C=US; ST=California; L=San Jose; O=Adobe Systems Incorporated; CN=target.example.com
    44
    45==========================================================
    46
    47 For additional TLS/SSL validation, including detailed browser/client support,
    48 see SSL Labs (click the first IP address if prompted):
    49
    50 🔎 https://ssllabs.com/ssltest/analyze.html?hideResults=on&latest&d=target.example.com
    51
    52 To check DNS propagation around the world, see whatsmydns.net:
    53
    54 🔎 DNS A records: https://whatsmydns.net/#A/target.example.com
    55 🔎 DNS CNAME record: https://whatsmydns.net/#CNAME/target.example.com
    56
    57==========================================================

How do I use an opt-out link with CNAME#

If you are using CNAME, the opt-out link should contain the "client=clientcode parameter, for example: https://my.cname.domain/optout?client=clientcode.

Replace clientcode with your client code, then add the text or image to be linked to the opt-out URL.

Known limitations#

  • QA mode is not sticky when you have CNAME and at.js 1.x because it is based on a third-party cookie. The workaround is to add the preview parameters to each URL you navigate to. QA mode is sticky when you have CNAME and at.js 2.x.
  • When using CNAME, it becomes more likely that the size of the cookie header for Target calls increase. Adobe recommends keeping the cookie size under 8 KB.
Was this helpful?
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.