Custom origin prerequisites

A custom origin is a physical server that you maintain to house your deliverable content. There are some prerequisites you need to meet before you can add a custom origin to your property.

Set your origin server hostname

Typically, your end users reach your origin server using your primary domain‚ÄĒwhat we refer to as your "hostname." After you go live on ‚Äč‚ÄčAkamai‚Äč, your hostname will point to ‚ÄčAkamai‚Äč edge servers, so you'll need to create a new hostname for your origin in your DNS record. This new name will tell edge servers where they need to go to get your content to serve over the ‚ÄčAkamai‚Äč network.

Define the origin hostname

Origin server hostnames typically use a common formula such as {origin}-{content origin} where the following apply:

  • {origin}. This is what we refer to as the "origin A record." As a best practice, you should use a random string for this value (for example, 1hkeh1g76). This serves to conceal your origin server.

  • {content origin}. This is the actual hostname of your origin server.

Here are some examples:

Primary domainOrigin server hostname
www.mysitecontent.com1hkeh1g76-www.mysitecontent.com
app.resources.com1hkeh1g76-app.resources.com

ūüĎć

Once established, make note of this value for future use.

Don't use the IP address as an origin server hostname

Your origin server has a unique IP address, so technically you could simply use that IP address rather than an origin hostname defined in your public DNS which points to that IP address. However, we strongly advise against doing that, as any address changes or reassignments might make your origin unreachable and result in a denial of service.

Disallowed origin IP addresses and ports

If you specify a hostname, it needs to be an external routable IP address‚ÄĒthat is, it must resolve through public DNS server. Don't use these internal non-routable IP address ranges either directly or as the resolved IP address of your hostname:

  • 10.0.0.0 -10.255.255.255
  • 172.16.0.0 - 172.31.255.255
  • 192.168.0.0 - 192.168.255.255

‚ÄčAkamai‚Äč will not be able to connect to any IP address within these ranges, as they are reserved for internal network use.

Configure the DNS record

Create the DNS record for your origin server hostname on your authoritative name servers, using the same method you'd use for any other DNS record. The IP address should be exactly the same as the IP in the DNS record for your production content origin hostname, before switching to the edge network. For example, in this change, the IP 192.0.2.0 is the same before and after switching to the ‚ÄčAkamai‚Äč edge network:

Original name in DNSOrigin server Hostname in DNS
www.mysitecontent.com. IN A 192.0.2.01hkeh1g76-www.mysitecontent.com. IN A 192.0.2.0
app.resources.com. IN A 192.0.2.01hkeh1g76-app.resources.com. IN A 192.0.2.0

Create an origin certificate

With the second phase of the ‚ÄčAkamai‚Äč request flow, you need a certificate on your origin server to secure the connection between it and ‚ÄčAkamai‚Äč edge servers. There are multiple ways you can set up and install this certificate.

ūüďė

Non-secure HTTP origins

If you're using HTTP, you don't need an origin certificate. While ‚ÄčAkamai‚Äč supports non-secure HTTP connections, this isn't recommended because HTTPS is now the industry norm.

Use a publicly trusted certificate authority

‚ÄčAkamai‚Äč uses Let's Encrypt as the default certificate authority and you can obtain and configure a certificate for your origin from Let's Encrypt. Take a look at the Let's Encrypt guidelines on setting up certificates for your origin server.

You can also install a certificate obtained from another trusted certificate authority. See the Digicert documentation for other popular trusted authorities, for example:

Review the "‚ÄčAkamai‚Äč Certificate Store" to see a list of certificate authorities that have been tested and are trusted for use:

  1. Use Property Manager to create a brand new property.

  2. Scroll down to the Property Configuration Settings and locate the Origin Server behavior. (It's typically in the Default Rule for ‚ÄčAkamai‚Äč products.) Apply settings as follows:

    • Origin Type. Set to Your Origin.

    • Verification Settings. Set to Choose Your Own.

    • Trust. Set to Akamai-managed Certificate Authorities Sets.

  3. Click View CA Set next to the ‚ÄčAkamai‚Äč Certificate Store switch.

  1. In the ‚ÄčAkamai‚Äč Certificate Store window, review the list of certificate authorities to see if the one you want is supported.

  2. Make note of the associated Expiration Date and the SHA-1 Fingerprint for use in creating your cert and applying it on your origin server.

  3. You can Cancel the creation of the property. This process just serves to get you a list of supported certificate authorities. There are several other things you need to do before you create a new property.

What's next for a publicly trusted certificate authority

Later, you'll configure the Origin Server behavior in your property, to apply Verification Settings. You can select Use Platform Settings to apply default verification or customize verification by selecting Choose Your Own.

For detailed instructions, see The custom origin (publicly trusted certificate)

Advantages and disadvantages with a publicly trusted certificate authority

There are pros and cons to using this certificate method:

AdvantagesDisadvantages
  • If your origin certificate is going to expire soon, you can rotate it on your origin by creating a new certificate. You don't need to change any settings for the edge network.

  • If you ever need end users to make requests directly to your origin, their browsers will also trust this certificate.

  • We keep the list of trusted certificate authorities up to date for you.

You need to rotate a certificate that is close to expiring. If you don't, and it expires, an edge server will no longer trust it and won't be able to connect to your origin. After renewal, ensure that the new certificate is also signed by one of the trusted certificate authorities and that it's valid for the same hostnames. See Rotate your origin certificate.

Use a custom certificate authority

You can specify which certificate authorities you want ‚ÄčAkamai‚Äč to trust for your site. This can even be a certificate authority that you set up yourself.

  1. Provision an origin certificate using a custom certificate authority, and install it on your origin server. If you want to set up your own and sign the origin certificate yourself, you can do that using multiple tools, for example:

  2. Install the certificate on your origin server, very similar to how you'd install a certificate from any other certificate authority, for example Apache or Nginx.

What's next with a custom certificate authority

Later, you'll configure the Origin Server behavior in your property, to customize Verification Settings by selecting Choose Your Own and setting Trust to Custom Certificate Authority Set. You'll also add your SSL certification list by telling your property to either retrieve it from your origin server or include a privacy-enhanced mail (PEM)-encoded version of it, directly in your property.

Advantages and disadvantages to a custom certificate authority

There are pros and cons to using this certificate method:

AdvantagesDisadvantages

If your origin certificate is going to expire soon, you can rotate it on your origin by creating a new certificate. You don't need to change any settings for the edge network.

  • If any of the trusted certificate authorities are compromised, your site may be vulnerable until you remove that certificate authority from your custom trusted list.

  • If the certificate authority itself is going to expire soon, you'll need to rotate it. This also includes changing various settings. If you don't, and it expires, an edge server will no longer trust it and won't be able to connect to your origin.

  • You need to rotate a certificate that is close to expiring. If you don't, and it expires, an edge server will no longer trust it and won't be able to connect to your origin. See Rotate your origin certificate.

Pin an exact certificate

You can create and specify the exact certificate(s) that ‚ÄčAkamai‚Äč should trust for your origin, including self-signed certificates. This is also known as "pinning" a certificate.

In this case, edge servers check that the origin sent the right certificate and then they skip the other usual checks, such as the signature, the SAN list of sites the cert is valid for, and the expiration date.

Generate the certificate

There are multiple ways to generate this certificate.

MethodDetails

Manual self-signed certificates

If you want to manually create a self-signed certificate, you can use multiple tools, for example:

Then, you need to install that certificate on your origin server, very similar to how you'd install a certificate from any other CA, for example Apache or Nginx.

Certificate management apps

You can install something like Certbot on your origin server to create and manage certificates. You can set it up to automatically renew a domain-validated certificate before it expires, but you'll need to update your property here after it does.

What's next when pinning an exact certificate

Later, you'll configure the Origin Server behavior in your property, to customize Verification Settings by selecting Choose Your Own and setting Trust to Specific Certificates (pinning). You'll also add your pinned certificate to your property by telling it to either retrieve it from your origin server via your domain, or include a privacy-enhanced mail (PEM)-encoded version of it, directly in your property. For detailed instructions, see The custom origin (pinned certificate).

ūüöß

Pinned certificates accumulate in the last instance of the Origin behavior

A request may process multiple Origin Server behaviors in multiple rules, including the Origin Server behavior you specify in the default rule. However, only the last Origin Server behavior in the rule tree applies to requests going forward. As certificates accumulate, it will trust all certificates pinned in the Origin Server behaviors executed earlier.

Consider this scenario: you pin a certificate for origin_A in the Origin Server behavior in the default rule. In another rule later on in the rule tree, you set up a match criteria, for example Hostname, and add another instance of the Origin Server behavior, pinning a different certificate there for origin_B. Because the certificates accumulate, if the request meets the match criteria, origin_B will trust both certificates.

Advantages and disadvantages to pinning an exact certificate

There are pros and cons to using this certificate method:

AdvantagesDisadvantages
  • This establishes a direct trust relationship between your origin server and edge servers, without depending on any intermediaries.

  • Since the expiration date is not checked, you can continue to use this certificate indefinitely. However, we recommend that you rotate your certificate regularly, to ensure the best security. See Rotate your origin certificate.

  • If the certificate is compromised, your site may be vulnerable until you rotate it.

  • Every time you rotate your certificate, you need to update the Origin Server behavior in your property.

  • There may be security implications associated with pinning that make it undesirable in your environment. You can review them on the OWASP website.

Rotate your origin certificate

Based on how you created and applied your origin certificate, you may need to rotate to a new one.

Before you begin

  1. If applicable, make changes to your Property Manager property file settings so that both the old and new certificates are trusted.

  2. You can optionally set up a second instance of your origin using the new origin certificate, and set up your property to use that origin for a particular test URL. Make sure to use the same trust settings on the test origin as the actual origin. For example, both properties should check for the same hostnames on the certificate.

  3. Push the property changes to the staging network and test that your current origin certificate is still trusted on this network.

  4. You can optionally use the test URL pointing to the second instance of your origin to test that your new origin certificate is trusted on staging network, too.

  5. Push your property changes to the production network and test that your current origin certificate is still trusted on this network.

  6. If you set up the optional second instance of your origin, you can use the test URL pointing to this instance of your origin to test that your new origin certificate is trusted on production.

Switch the certificate on your origin

Switch your origin server to the new certificate, and test that your new origin certificate is still trusted on production.

Perform some clean-up

  1. If applicable, make any required changes to your property settings so that the old certificate is no longer trusted.

  2. Push property changes to the staging network, and test that your new origin certificate is still trusted on this network.

  3. Push property changes to the production network, and again test that your new origin certificate is still trusted on this network.

Pinned certificate rotation

If you have a specific leaf certificate pinned and it's expiring, start the rotation before it does:

  1. Add your new certificate to the list in the Origin Server behavior.

  2. Push your property to production.

  3. Change your origin certificate to the new one.

ūüöß

Create custom certs beforehand

You need to complete the process in this order. Otherwise, edge servers won't trust the new certificate and may cause a service outage.