Onboard a custom cert property

Here, we'll set up a property using a custom certificate that we'll create to secure the connection between a requesting client and the ‚ÄčAkamai‚Äč network.

Before you begin

Make sure you get these things done before you start with this workflow.

  • Determine the level of security. What level of security do you need to deliver your content to requesting clients? Have a look at Understand the levels of security to figure out if you need Enhanced or Standard TLS security.

  • Set up authentication. To make calls through the various ‚ÄčAkamai‚Äč APIs available for this workflow, you need to authenticate using tokens you generate and apply in requests from your API client tool.

    • Property Manager API (PAPI). This is what you'll use to set up your property to deliver your traffic. You'll need to ensure that your authentication is set up for READ/WRITE access to PAPI.

    • Certificate Provisioning System (CPS) API. As a step in this workflow, you'll need to set up a certificate to secure the connection between clients requesting your content and the ‚ÄčAkamai‚Äč edge network. You can use an API for this process. You'll need to ensure that the access authentication for it is also set up for READ/WRITE access.

  • Make sure you have write access to your primary DNS servers. You'll need to modify DNS records during the process.

1 - Add the origin layer to your DNS

Get the IP address of your existing origin and create an A record in your DNS.

2 - Use CPS to prepare your edge certificate

CPS is a separate ‚Äč‚ÄčAkamai‚Äč‚Äč utility you can use to generate a custom certificate using either Standard or Enhanced TLS security. All certificates are signed by a Certificate Authority that is known to be trusted by every major browser or operating system. When creating one, you need to set the domain name that clients use to access your site or asset as the common name (CN), or include it as a subject alternate name (SAN) in the certificate.

Use the CPS API

Have a look at the developer documentation for CPS for details.

Use ‚Äč‚ÄčAkamai Control Center‚Äč

You can also use a separate user interface in ‚Äč‚ÄčControl Center‚Äč‚Äč to create custom certificates. See the Certificate Provisioning System user documentation for instructions on this process. There are multiple phases of the process, and you need to apply specific settings:

  1. When you enter certificate information, you'll set your domain name as either the Common Name (CN) or a Subject Alternate Name (SAN). Make note of it, because you need this value later in the process.

  2. During the select network setting phase, set Deployment Network to the desired level of security, Standard TLS or Enhanced TLS.

  3. Set all other options for all other phases of the certificate creation process as desired.

Wait for the certificate to provision

Regardless of the tool you used, a certificate can take from 3 - 6 hours to provision, based on the level of security you've chosen. The email address set for the ‚ÄčControl Center‚Äč account that you used to create the certificate will receive an email when it's ready.

3 - Get contracts, groups, and products

These identifiers specify what modules and features you'll be able to use in your property.

4 - Create an edge hostname

An edge hostname is used to process the request between a client and the ‚Äč‚ÄčAkamai‚Äč edge network. Using the custom cert method, you need to create one using the domain name you set as your CN or SAN in your certificate:

5 - Create a CP code

CP codes track any web traffic handled by edge servers. Each property’s default rule needs a valid CP code to bill and report for the service.

6 - Create a property

Think of a property as a container for your product configuration. Set one up to control how your content is delivered.

7 - Update your property with your edge hostname

Here, you map your property hostname to the edge hostname that you created, so it can take over the client traffic from your origin.

8 - Check the status of your hostname

Run this operation and locate your hostname, based on its "cnameFrom": "<your domain>". It needs to be active. Check for the status object in the response:

  • You see the status object. Any status value indicates that it's still provisioning. Wait a while and try the operation again.
  • There's no status object. The hostname is active. Review the response to confirm that the cnameFrom value is the correct domain for your site or resource, and store the cnameTo value for use later in the process.

9 - Add the edge hostname to your DNS

In your DNS configuration, create a CNAME record and map your domain (cnameFrom) to the cnameTo value that you stored.

10 - Get the rule tree

Get the baseline of your property's rule tree. It includes all of the default rules and behaviors that ‚ÄčAkamai‚Äč adds. So, what you'll get in the response varies based on your ‚ÄčAkamai‚Äč product.

11 - Edit the rule tree

Provide necessary details for the top-level default rule. At a minimum, configure these mandatory behaviors in a rule:

You can optionally include any number of your own rules to customize content delivery. Rule trees are maintained in a special form of JSON that you can best edit and validate in the dedicated VS code or Eclipse IDE plugins.

12 - Validate the rule tree changes

Make sure your JSON file is correct and complete before deploying it on edge servers. You need to resolve returned errors, as they block an activation, but you can activate a property version that yields less severe warnings. For more information, see Rule tree errors and warnings. Both VS code and Eclipse plugins support full rule tree validation.

13 - Update the property's rule tree

Push your updated JSON file to the property configuration.

14 - Activate the property on staging and production

With brand new setups, you only need to test your configuration on production. But, you can activate your property on both networks at the same time.

15 - Confirm activation

Make sure the activation was successful. The response should contain "status": ACTIVE.

16 - Test the activated settings

  1. Look up the IP address of your edge hostname and copy it. For example, assume the domain you set in your edge hostname was "example.com":

    Windows:

    nslookup www.example.com.edgekey.net
    

    Mac OS, Linux, or Unix:

    dig www.example.com.edgekey.net
    
  2. Paste the edge hostname IP address to your local hosts file in a text editor.

    • Windows. You should be able to find your hosts file in: C:\Windows\System32\drivers\etc\hosts
    • Mac OS, Linux, or Unix. You should be able to find your hosts file in: /etc/hosts
  3. Restart your browser to clear your DNS cache and verify that your site is working the way you expect.

17 - Go live

Start serving live traffic through the ‚ÄčAkamai‚Äč Edge Platform. Replace your existing CNAME record and with a new one, setting its value to the ‚ÄčAkamai‚Äč edge hostname.

Remember to remove any entries from your local hosts file that you may have set up for testing. Now, you can restart your browser and do a smoke test of your website or application.