This workflow uses the Property Manager API (PAPI) to create a property that's protected by a Default Domain Validated (DV) certificate. ​Akamai​ automatically generates a new Default DV certificate and a dual-stack IPv4+IPv6 edge hostname to securely deliver your content.

📘

Default DV certificates are limited availability

This is an additional service that needs to be added to your contract. However, it hasn't been released to general availability yet. Contact your account team to see if you're eligible. Otherwise, you need to onboard a custom cert property.

Who should use it

Usually, ​Akamai​ recommends the Auto DNS method, where you add an _acme-challenge CNAME DNS record to validate the domains in your default DV certificate. However, if you're a SaaS/PaaS/IaaS provider and your customer has CNAMEd their hostname to a domain that you control, then this workflow covers the Manual HTTP validation method that you can use to obtain an edge certificate and go live without needing the customer to modify their DNS records.

Example current DNS setup
www.example.com CNAME example.saas.net
example.saas.net A 1.2.3.4

Assumptions
SaaS has access to configure saas.net domain server.
SaaS doesn't have access to configure their customer’s domain server - example.com.

For a more detailed comparison of available domain validation methods, see the Property Manager guide.

Before you begin

Make sure you get these things done before you jump into the 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 for PAPI. To make calls through PAPI, you need to authenticate to ​Akamai​ using tokens you generate in your API client tool.

• Make sure you have access to the SaaS DNS configuration. See the example above.

Create a property with the Default DV certificate

1 - Add the origin layer to the SaaS DNS zone

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

2 - Get contracts, groups, and products

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

3 - 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.

4 - Create a property

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

5 - Set variables for your property (optional)

Do you have specific values you'll repeatedly use in the property's rule tree? Use built-in system variables or create your own and apply them as you need them.

6 - Set up property hostnames

Here, you map your property hostnames to an edge hostname, so that the edge servers can take over the client traffic from your origin. With Default DV, you specify "certificateProvisioningType": "DEFAULT" using this API operation to have Property Manager automatically attempt to create a TLS certificate and create an edge hostname upon activation:

The response's authorization object will only show advanced validation methods once you activate version 1 of your property.

🚧

You can provision up to 50 Default DV certificates per hour. If you exceed that limit, PAPI automatically queues and processes the remaining certificates in the next batch.

7 - 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. What you'll get in the response varies depending on your ​Akamai​ product.

8 - Edit the rule tree

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

• origin.
• cpCode.

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.

9 - 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.

10 - Update the property's rule tree

Push your updated JSON file back to the property.

11 - 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.

12 - Confirm activation

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

Validate domains with advanced methods

This section summarizes the initial domain validation for the Default DV certificates. Your certificates may renew automatically. Learn more about Auto HTTP.

1 - Get the domain validation challenges

Run this operation and in the response, locate your hostname, based on its "cnameFrom": "<your domain>". It should also include "certProvisioningType": "DEFAULT".

Once the status in the authorization object is either ATTEMPTING_VALIDATION or PAUSED_AWAITING_PROCEED, the response contains the dns01, and—unless you use a wildcard hostname—the http01 objects with validation challenges.

The challenge tokens are valid only for a certain number of days. Once the token expires, we will fetch a new token from the CA. If the current token expires before you are able to use it, then you can request a new token.

2 - Copy the validation challenges to a plain text file

For the Manual HTTP validation method, create a file containing the body token and save it on your origin server so that it's returned at the given url. This method is recommended if you're a SaaS/PaaS/IaaS provider without direct access to modify your customers' DNS records.

"authorization": {
                    "status": "ATTEMPTING_VALIDATION",
                    "validUntil": "2024-07-25T16:17:37Z",
                    "http01": {
                        "url": "http://www.example.com/.well-known/acme-challenge/UMb99-08TaSYHSi2isWraUeTA7g8MYHgN4Oqsrf5j78",
                        "body": "UMb99-08TaSYHSi2isWraUeTA7g8MYHgN4OMJg80sy8.V9Ciog4m_UaWKzrrmmphysbein7h_WNKIbsjuHsuJsyO",
                          "result": {
                            "src": "CPS",
                            "message": "Validation tokens mismatch for www.example.com",
                            "timestamp": "2024-07-25T16:17:37Z"
                        }
                      },
                      “dns01”: {...}
   }

3 - Confirm the domain validation and certificate deployment statuses

Make sure your certificate is in the DEPLOYED status and the validation for the domains in your certificate was successful. The authorization’s status should be VALIDATED.

🚧

If the authorization status shows PAUSED_AWAITING_PROCEED, you need to resume the certificate domain validation process. If there are issues that you need to fix, you get a warning message with reasons why the process has been paused.

Test and go live

1 - Test the activated settings

Temporarily set up your local browser to target an edge server to access your property.

1. You need to obtain the IP address of an ​Akamai​ edge server by doing a DNS lookup of your edge hostname. For example, assume the edge hostname you set up was www.example.com.edgesuite.net:

   Windows:

   • Text IPv4-only / IPv4 + IPv6 dual stack
   • nslookup www.example.com.edgesuite.net

   macOS, Linux, or Unix:

   • Text IPv4 + IPv6 dual stack
   • dig www.example.com.edgesuite.net

2. Navigate 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
   • macOS, Linux, or Unix. You should be able to find your hosts file in: /etc/hosts

3. At the end of the hosts file, add an entry for the actual domain to your website that includes the edge hostname's IP address.

   1.23.45.78 example.com
   

4. Save and close your hosts file. Restart your browser to clear your DNS cache and verify that your site is working the way you expect.

For more details on testing and activation, see Activate a property.

2 - Go live

Start serving live traffic through the ​Akamai​ Edge Platform. Change the SaaS-controlled hostname (for example, example.saas.net) from an A record pointing to the origin server to instead be a CNAME record pointing to the ​Akamai​ edge hostname.

Final setup

www.example.com CNAME example.saas.net
example.saas.net CNAME example.edgesuite.net
example-origin.saas.net A 1.2.3.4

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.

Configure alerts for your certificates

Learn more aboutconfiguring alerts for your certificates in Property Manager, and create an alert in the Alerts API.